errors.h

Go to the documentation of this file.

/* -*- C -*-
 * Serene programming language
 * Copyright (C) 2019-2026 Sameer Rahmani <[email protected]>
 *
 * 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>
#define ERROR_HEADER srn_error_t *maybe_error
 
/**
 * 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)
 
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
 
/**
 * The kind of a failure. Each `srn_error_t` carries one of these.
 */
typedef enum srn_error_tag_t {
  ABSURD,
  SEQ_LIMIT_REACHED,
  INDEX_OUT_OF_BOUND,
  CORRUPTED_SEQ,
  FAILED_TO_ADD_MODULE,
  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,
  UNKNOWN_IO_ERROR,
} srn_error_tag_t;
 
/**
 * A runtime error, a tag classifying the failure and a human-readable
 * message.
 */
typedef struct srn_error_t {
  srn_error_tag_t tag;
  char *msg;
} srn_error_t;
 
/**
 * Build an error in `ctx`'s memory, tagged `tag` and carrying `msg`. Returns
 * the error to attach to a value's `maybe_error` (or to inspect directly). The
 * ERR macro below is the shorthand for the common call.
 */
srn_error_t *srn_errors_make(const srn_context_t *ctx, srn_error_tag_t tag, const char *msg);
 
/**
 * 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
);
 
#define ERR(ctx, err, msg)     srn_errors_make(ctx, err, msg)
#define FAIL(ctx, T, err, msg) ((T *)srn_errors_fail(ctx, sizeof(T), alignof(T), err, msg))
 
/**
 * 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