Skip to content

README.md

Latest commit

 

History

History
213 lines (154 loc) · 3.43 KB

README.md

File metadata and controls

213 lines (154 loc) · 3.43 KB

Vix Error

The error module provides a unified, explicit, and lightweight system for handling failures in Vix.

It is designed as a foundational building block for:

  • filesystem operations
  • networking and transport layers
  • parsing and validation
  • CLI tools
  • backend services

The module favors explicit control flow, predictability, and zero hidden behavior.

Philosophy

Error handling in Vix follows strict rules:

  • No hidden exceptions
  • Errors are explicit values
  • No implicit control flow
  • Minimal overhead
  • Stable and composable APIs

Every operation returns either:

  • a value
  • or a structured Error

Core Concepts

Concept Purpose
ErrorCode What went wrong
ErrorCategory Where the error happened
Error Structured error object
Result<T> Value or error
Exception Optional exception wrapper

Error Model

A failure is represented by:

Error

Which contains:

  • code — semantic error code
  • category — domain (io, network, validation…)
  • message — human-readable description

Example:

Error err(
  ErrorCode::InvalidArgument,
  ErrorCategory::validation(),
  "invalid port"
);

Using Result

Result<T> is the primary abstraction for returning values.

#include <vix/error/Result.hpp>

Result<int> divide(int a, int b)
{
  if (b == 0)
  {
    return Error(
      ErrorCode::InvalidArgument,
      ErrorCategory::validation(),
      "division by zero"
    );
  }

  return a / b;
}

Usage

auto r = divide(10, 0);

if (!r)
{
  std::cout << r.error().message() << "\n";
}
else
{
  std::cout << r.value() << "\n";
}

Chaining Operations

Results can be composed without exceptions:

auto result =
  parse_int("8080")
    .and_then(validate_port)
    .map([](int port) {
      return port * 2;
    });

This allows building pipelines with clear error propagation.

Result

Operations without a return value use:

Result<void> write_file(...)
{
  if (fail)
    return Error(...);

  return {};
}

Error Categories

Categories group errors by domain:

  • ErrorCategory::io()
  • ErrorCategory::network()
  • ErrorCategory::validation()
  • ErrorCategory::system()
  • ErrorCategory::internal()

They are lightweight and allocation-free.

Exception Interoperability

Vix does not require exceptions, but supports them when needed.

throw Exception(
  ErrorCode::IoError,
  ErrorCategory::io(),
  "failed to open file"
);

Catch:

catch (const Exception& e)
{
  std::cout << e.what() << "\n";
}

Examples

See examples/:

  • basic.cpp
  • result.cpp
  • chaining.cpp
  • exception.cpp

Run:

vix run examples/result.cpp

Performance Notes

  • No hidden allocations (except error message)
  • Result<T> uses std::variant
  • Categories use string_view (no allocation)
  • No exceptions in normal flow

Suitable for:

  • hot paths
  • low-latency systems
  • embedded environments

Relationship with Other Modules

The error module is used everywhere in Vix:

  • fs → file operations return Result<T>
  • conversion → returns structured errors
  • validation → builds on explicit error propagation
  • http / p2p → network failures modeled as values

It is the foundation of error handling in Vix.

Design Goals Recap

  • Errors as values
  • Explicit control flow
  • Composable APIs
  • No surprises
  • Minimal runtime cost

License

MIT Part of the Vix.cpp project.