errors.h

Go to the documentation of this file.

/* -*- C -*-
 * Serene programming language
 * Copyright (C) 2019-2026 Sameer Rahmani <lxsameer@lxsameer.com>
 *
 * This library is free software: you can redistribute it and/or modify
 * it under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License
 * along with this library.  If not, see <https://www.gnu.org/licenses/>.
 */
 
/** @file
 
 Error handling for the runtime.
 
 An `srn_error_t` pairs a `srn_error_tag_t`, naming the kind of failure, with a
 human-readable message, and is allocated from a `srn_context_t`. Fallible
 operations report failures as these explicit error values rather than through
 return codes or out-of-band state, so an error travels with the data it
 describes. When the Serene language layer is built, an error can also be lifted
 into a `srn_value_t` so the failure is representable inside the language
 itself.
 
 ## IMPORTANT NOTE: ##
 
 By Convention, all the data structures that in anyway may, interacting with
 them may result in an error, must use the ERROR_HEADER macro as the first
 member. For example:
 
 ```c
 typedef struct foo {
   ERROR_HEADER
   bar other;
   ...
 } foo;
 ```
 Following this convention let you use the error handling helpers from this
 header uniformly across the runtime library.
*/
 
#pragma once
 
/**
 * The first member every fallible data structure embeds (see the file note
 * above). Holds the error attached to a value, or null when the value is
 * good.
 */
#include <stddef.h>
#include <stdint.h>
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define ERROR_HEADER      srn_error_t *maybe_error
#define TRACE_FRAME_DEPTH 32
 
/**
 * True when `x` -- a value carrying an `ERROR_HEADER` -- has an error
 * attached. Takes the struct by value, the way these results are passed and
 * checked.
 */
#define HAS_ERROR(x) ((x).maybe_error != nullptr)
 
#define PUSH_TRACE(ctx, x) srn_error_trace_push(ctx, (x).maybe_error, __builtin_return_address(0))
#define PUSH_AND_MOVE(ctx, from, to)       \
  {                                        \
    (to).maybe_error = (from).maybe_error; \
    PUSH_TRACE(ctx, to);                   \
  }
 
typedef struct srn_context_t srn_context_t;
 
#ifdef SRN_WITH_SERENE
typedef struct srn_value_t srn_value_t;
typedef struct srn_metadata_t srn_metadata_t;
#endif
 
// TODO(lxsameer): Move this function to an auto generated file alongside
// the actual `srn_error_tag_name`, something like tablegen or something.
 
/**
 * The kind of a failure. Each `srn_error_t` carries one of these.
 */
typedef enum srn_error_tag_t {
  ABSURD,
  NOT_IMPLEMENTED,
  SEQ_LIMIT_REACHED,
  AL_LIMIT_REACHED,
  SM_BUFFER_ID_EXHAUSTED,
  INDEX_OUT_OF_BOUND,
  CORRUPTED_SEQ,
  CORRUPTED_ARRAY_LIST,
  FAILED_TO_ADD_MODULE,
  /// The JIT could not parse a module's LLVM IR or bitcode.
  JIT_IR_PARSE_FAILED,
  /// A JIT symbol lookup found no symbol of that name.
  JIT_SYMBOL_NOT_FOUND,
  /// A JIT symbol definition collided with a name already defined.
  JIT_SYMBOL_ALREADY_DEFINED,
  EMPTY_NAMESPACE_NAME,
  EMPTY_SYMBOL_NAME,
  STRING_LENGTH_LIMIT_EXCEEDED,
  WRONG_RANGE,
  EPOLL_INIT_FAILED,
  EPOLL_EVENT_FD_FAILED,
  EPOLL_FAILED_TO_ADD_FD,
 
  // IO operation failures, reactor backends will maps their platform
  // errors to these tags.
  CONNECTION_REFUSED,
  CONNECTION_RESET,
  CONNECTION_ABORTED,
  BROKEN_PIPE,
  BAD_DESCRIPTOR,
  TIMED_OUT,
  CANCELED,
  NOT_CONNECTED,
  ADDRESS_IN_USE,
  HOST_UNREACHABLE,
  NETWORK_UNREACHABLE,
  MESSAGE_TOO_LONG,
  TOO_MANY_OPEN_FILES,
  PERMISSION_DENIED,
  OUT_OF_MEMORY,
  NOT_FOUND,
  ALREADY_EXISTS,
  IS_A_DIRECTORY,
  NOT_A_DIRECTORY,
  NO_SPACE,
  /// The request itself is malformed (an empty POLL interest mask, for
  /// example), so retrying it unchanged can never succeed.
  INVALID_ARGUMENT,
  /// The channel already has a full ring's worth of operations in flight.
  /// Transient by construction, it clears as the worker consumes
  /// completions, so the caller can retry.
  CHANNEL_BUSY,
  MEMORY_MAP_FAILED,
  IR_PARSE_ERROR,
  UNKNOWN_IO_ERROR,
} srn_error_tag_t;
 
typedef enum srn_error_layer_t : uint8_t {
  SRN_ERR_RUNTIME_LAYER = 0,
#ifdef SRN_WITH_SERENE
  SRN_ERR_PARSE_LAYER,
#endif
} srn_error_layer_t;
 
/**
 * This is how we create a traceback for the C level code in the runtime lib. It's similar to how
 * Zig handles it as well. The hard part is to remember to call `__builtin_return_address(0)` every
 * time we return an error and add the address to this array. Later we can use `dladdr` on POSIX
 * (and `SymFromAddr` on Windows) to resolve the function name, and look up the line number in
 * DWARF data when printing the error.
 */
typedef struct srn_trace_frames_t {
  void *return_addrs[TRACE_FRAME_DEPTH];
  uint16_t count;
} srn_trace_frames_t;
 
/**
 * A runtime error, a tag classifying the failure and a human-readable
 * message.
 */
typedef struct srn_error_t {
  srn_error_layer_t layer;
  srn_error_tag_t tag;
  char *msg;
  union {
#ifdef SRN_WITH_SERENE
    srn_metadata_t *metadata; // for every layer, except for runtime
#endif
    srn_trace_frames_t *frames; // for runtime only
  } as;
} srn_error_t;
 
/**
 * Append a return address to the trace of a runtime-layer error. Allocates
 * `frames` from `ctx` on the first call. Silently does nothing when the trace
 * is full or the error is not a runtime-layer error.
 */
void srn_error_trace_push(const srn_context_t *ctx, srn_error_t *err, void *addr);
 
/**
 * Build an error in `ctx`'s memory, tagged `tag` and carrying `msg`. `caller`
 * is the return address of the call site (pass `__builtin_return_address(0)`)
 * and is recorded as the first frame of the trace. The ERR macro supplies it
 * automatically.
 */
srn_error_t *
srn_errors_make(const srn_context_t *ctx, srn_error_tag_t tag, const char *msg, void *caller);
 
/**
 * Build an error in `ctx`'s memory that carries the layer, tag, message and
 * payload of `src`, with a trace of its own that starts at `caller`. `src`
 * is not written to, so this is the way to take a trace on an error that is
 * shared or immutable, such as the reactor's static IO errors. A runtime
 * layer `src` with frames has them copied, so the earlier trace is kept. The
 * ERR_FROM macro supplies `caller`.
 */
srn_error_t *srn_errors_from(const srn_context_t *ctx, const srn_error_t *src, void *caller);
 
/**
 * Allocate a `size`/`alignment` value in `ctx`, set its ERROR_HEADER (the
 * first member, `srn_error_t *maybe_error`) to a fresh error, and return it.
 * The result is a valid fallible value whose `HAS_ERROR` is true. Use the
 * FAIL macro, which fills in `size`/`alignment` from the target type.
 */
[[nodiscard]] [[gnu::nonnull(1)]]
void *srn_errors_fail(
  const srn_context_t *ctx, size_t size, size_t alignment, srn_error_tag_t tag, const char *msg,
  void *caller
);
 
#define ERR(ctx, err, msg) srn_errors_make(ctx, err, msg, __builtin_return_address(0))
#define ERR_FROM(ctx, src) srn_errors_from(ctx, src, __builtin_return_address(0))
#define FAIL(ctx, T, err, msg) \
  ((T *)srn_errors_fail(ctx, sizeof(T), alignof(T), err, msg, __builtin_return_address(0)))
 
/**
 * Format `err` as a newly allocated string of the form `[TAG]: msg`, allocated
 * in `ctx`. Returns `[UNKNOWN]: <null>` when `err` is null.
 */
[[nodiscard]] [[gnu::nonnull(1)]]
char *srn_error_to_string(const srn_context_t *ctx, const srn_error_t *err);
 
/**
 * Map a POSIX `errno` to error tag.
 * Note: an `errno` with no mapping yields `default_tag`, so the caller picks the
 * fallback that fits its domain. Defined on POSIX platforms. a non-POSIX backend should supply its
 * own native-code mapping.
 */
srn_error_tag_t srn_errno_to_tag(int errno_value, srn_error_tag_t default_tag);
 
#ifdef SRN_WITH_SERENE
/**
 * Lift an existing `srn_error_t` into a Serene value, so a failure already
 * produced by the substrate can be returned through the language layer.
 */
srn_value_t *
srn_errors_err_to_value(srn_context_t *ctx, srn_metadata_t *metadata, srn_error_t *err);
/**
 * Created an error as a value. In compare to `srn_errors_make` this function
 * populates the `sr_value_t` data structure, so the returning value can be
 * used in Serene lang directly.
 */
srn_value_t *srn_errors_make_error(
  srn_context_t *ctx, srn_metadata_t *metadata, srn_error_tag_t tag, const char *msg
);
#endif
 
#ifdef __cplusplus
}
#endif