errors.h File Reference

Error handling for the runtime. More...

#include <stddef.h>
#include <stdint.h>

Include dependency graph for errors.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	srn_trace_frames_t
	This is how we create a traceback for the C level code in the runtime lib. More...
struct	srn_error_t
	A runtime error, a tag classifying the failure and a human-readable message. More...

Macros
#define	ERROR_HEADER   srn_error_t *maybe_error
	The first member every fallible data structure embeds (see the file note above).
#define	TRACE_FRAME_DEPTH   32
#define	HAS_ERROR(x)
	True when x – a value carrying an ERROR_HEADER – has an error attached.
#define	PUSH_TRACE(ctx, x)
#define	PUSH_AND_MOVE(ctx, from, to)
#define	ERR(ctx, err, msg)
#define	ERR_FROM(ctx, src)
#define	FAIL(ctx, T, err, msg)

Typedefs
typedef enum srn_error_tag_t	srn_error_tag_t
	The kind of a failure.
typedef enum srn_error_layer_t	srn_error_layer_t
typedef struct srn_trace_frames_t	srn_trace_frames_t
	This is how we create a traceback for the C level code in the runtime lib.
typedef struct srn_error_t	srn_error_t
	A runtime error, a tag classifying the failure and a human-readable message.

Enumerations
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 , JIT_IR_PARSE_FAILED , JIT_SYMBOL_NOT_FOUND , 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 , 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 , INVALID_ARGUMENT ,   CHANNEL_BUSY , MEMORY_MAP_FAILED , IR_PARSE_ERROR , UNKNOWN_IO_ERROR }
	The kind of a failure. More...
enum	srn_error_layer_t : uint8_t { SRN_ERR_RUNTIME_LAYER = 0 }

Functions
void	srn_error_trace_push (const srn_context_t *ctx, srn_error_t *err, void *addr)
	Append a return address to the trace of a runtime-layer error.
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, tagged tag and carrying msg.
srn_error_t *	srn_errors_from (const srn_context_t *ctx, const srn_error_t *src, 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.
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)
	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.
char *	srn_error_to_string (const srn_context_t *ctx, const srn_error_t *err)
	Format err as a newly allocated string of the form [TAG]: msg, allocated in ctx.
srn_error_tag_t	srn_errno_to_tag (int errno_value, srn_error_tag_t default_tag)
	Map a POSIX errno to error tag.

Detailed Description

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:

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.

Definition in file errors.h.

Macro Definition Documentation

ERR

#define ERR	(		ctx,
			err,
			msg )

Value:

srn_errors_make(ctx, err, msg, __builtin_return_address(0))

Definition at line 223 of file errors.h.

ERR_FROM

#define ERR_FROM	(		ctx,
			src )

Value:

srn_errors_from(ctx, src, __builtin_return_address(0))

Definition at line 224 of file errors.h.

ERROR_HEADER

#define ERROR_HEADER   srn_error_t *maybe_error

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.

Definition at line 62 of file errors.h.

FAIL

#define FAIL	(		ctx,
			T,
			err,
			msg )

Value:

((T *)srn_errors_fail(ctx, sizeof(T), alignof(T), err, msg, __builtin_return_address(0)))

Definition at line 225 of file errors.h.

#define FAIL(ctx, T, err, msg) \
  ((T *)srn_errors_fail(ctx, sizeof(T), alignof(T), err, msg, __builtin_return_address(0)))

HAS_ERROR

#define HAS_ERROR

(

x

)

Value:

((x).maybe_error != nullptr)

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.

Definition at line 70 of file errors.h.

PUSH_AND_MOVE

#define PUSH_AND_MOVE	(		ctx,
			from,
			to )

Value:

{                                        \
  (to).maybe_error = (from).maybe_error; \
  PUSH_TRACE(ctx, to);                   \
}

Definition at line 73 of file errors.h.

#define PUSH_AND_MOVE(ctx, from, to)       \
  {                                        \
    (to).maybe_error = (from).maybe_error; \
    PUSH_TRACE(ctx, to);                   \
  }

PUSH_TRACE

#define PUSH_TRACE	(		ctx,
			x )

Value:

srn_error_trace_push(ctx, (x).maybe_error, __builtin_return_address(0))

Definition at line 72 of file errors.h.

TRACE_FRAME_DEPTH

#define TRACE_FRAME_DEPTH   32

Definition at line 63 of file errors.h.

Typedef Documentation

srn_error_layer_t

typedef enum srn_error_layer_t srn_error_layer_t

srn_error_t

typedef struct srn_error_t srn_error_t

A runtime error, a tag classifying the failure and a human-readable message.

srn_error_tag_t

typedef enum srn_error_tag_t srn_error_tag_t

The kind of a failure.

Each srn_error_t carries one of these.

srn_trace_frames_t

typedef struct srn_trace_frames_t srn_trace_frames_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.

Enumeration Type Documentation

srn_error_layer_t

enum srn_error_layer_t : uint8_t

Enumerator
SRN_ERR_RUNTIME_LAYER

Definition at line 150 of file errors.h.

                               : uint8_t {
  SRN_ERR_RUNTIME_LAYER = 0,
#ifdef SRN_WITH_SERENE
  SRN_ERR_PARSE_LAYER,
#endif
} srn_error_layer_t;

srn_error_tag_t

enum srn_error_tag_t

The kind of a failure.

Each srn_error_t carries one of these.

Enumerator
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
JIT_IR_PARSE_FAILED	The JIT could not parse a module's LLVM IR or bitcode.
JIT_SYMBOL_NOT_FOUND	A JIT symbol lookup found no symbol of that name.
JIT_SYMBOL_ALREADY_DEFINED	A JIT symbol definition collided with a name 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
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
INVALID_ARGUMENT	The request itself is malformed (an empty POLL interest mask, for example), so retrying it unchanged can never succeed.
CHANNEL_BUSY	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.
MEMORY_MAP_FAILED
IR_PARSE_ERROR
UNKNOWN_IO_ERROR

Definition at line 92 of file errors.h.

                             {
  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;

Function Documentation

srn_errno_to_tag()

srn_error_tag_t srn_errno_to_tag	(	int	errno_value,
		srn_error_tag_t	default_tag )

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.

Here is the caller graph for this function:

srn_error_to_string()

char * srn_error_to_string ( const srn_context_t * ctx, const srn_error_t * err )

nodiscard

Format err as a newly allocated string of the form [TAG]: msg, allocated in ctx.

Returns [UNKNOWN]: <null> when err is null.

Definition at line 133 of file errors.c.

                                                                            {
  PANIC_IF_NULL(err);
  const char *tag = srn_error_tag_name(err->tag);
  const char *msg = err->msg != nullptr ? err->msg : "<null>";
 
  int header_len = snprintf(nullptr, 0, "[%s]: %s", tag, msg);
  PANIC_IF(header_len < 0, "srn_error_to_string: formatting failed");
 
  // Measure the trace lines before allocating so a single allocation covers
  // the whole string.
  int trace_len = 0;
  char sym[256];
  if (err->layer == SRN_ERR_RUNTIME_LAYER && err->as.frames != nullptr) {
    for (uint16_t i = 0; i < err->as.frames->count; i++) {
      void *addr       = err->as.frames->return_addrs[i];
      const char *name = srn_dbg_sym_name(addr, sym, sizeof(sym));
      if (name != nullptr) {
        trace_len += snprintf(nullptr, 0, "\n  #%u %p %s", i, addr, name);
      } else {
        trace_len += snprintf(nullptr, 0, "\n  #%u %p", i, addr);
      }
    }
  }
 
  size_t total = (size_t)header_len + (size_t)trace_len + 1;
  char *buf    = srn_allocate(ctx, total, alignof(char));
  PANIC_IF_NULL(buf);
 
  int written = snprintf(buf, total, "[%s]: %s", tag, msg);
  if (err->layer == SRN_ERR_RUNTIME_LAYER && err->as.frames != nullptr) {
    for (uint16_t i = 0; i < err->as.frames->count; i++) {
      void *addr       = err->as.frames->return_addrs[i];
      const char *name = srn_dbg_sym_name(addr, sym, sizeof(sym));
      if (name != nullptr) {
        written += snprintf(buf + written, total - (size_t)written, "\n  #%u %p %s", i, addr, name);
      } else {
        written += snprintf(buf + written, total - (size_t)written, "\n  #%u %p", i, addr);
      }
    }
  }
 
  return buf;
}

Here is the call graph for this function:

Here is the caller graph for this function:

srn_error_trace_push()

void srn_error_trace_push	(	const srn_context_t *	ctx,
		srn_error_t *	err,
		void *	addr )

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.

Definition at line 177 of file errors.c.

                                                                                  {
  if (err->layer != SRN_ERR_RUNTIME_LAYER) {
    return;
  }
 
  if (err->as.frames == nullptr) {
    err->as.frames = ALLOC(ctx, srn_trace_frames_t);
    PANIC_IF_NULL(err->as.frames);
    err->as.frames->count = 0;
  }
 
  if (err->as.frames->count >= TRACE_FRAME_DEPTH) {
    return;
  }
 
  err->as.frames->return_addrs[err->as.frames->count++] = addr;
}

Here is the caller graph for this function:

srn_errors_fail()

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 )

nodiscard

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.

Definition at line 224 of file errors.c.

  {
  // The ERROR_HEADER convention guarantees `srn_error_t *maybe_error` is the
  // first member of any fallible T, so offset 0 of the value is that pointer.
  // Allocate the value and set it to a fresh error; the caller checks it with
  // HAS_ERROR and never reads the other fields of an errored value.
  void *value = srn_allocate(ctx, size, alignment);
  PANIC_IF_NULL(value);
  *(srn_error_t **)value = srn_errors_make(ctx, tag, msg, caller);
  return value;
}

Here is the call graph for this function:

srn_errors_from()

srn_error_t * srn_errors_from	(	const srn_context_t *	ctx,
		const srn_error_t *	src,
		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.

Definition at line 207 of file errors.c.

                                                                                             {
  PANIC_IF_NULL(src);
  srn_error_t *err = ALLOC_OR_PANIC(ctx, srn_error_t);
  err->layer       = src->layer;
  err->tag         = src->tag;
  err->msg         = src->msg;
  err->as          = src->as;
 
  if (src->layer == SRN_ERR_RUNTIME_LAYER && src->as.frames != nullptr) {
    err->as.frames  = ALLOC_OR_PANIC(ctx, srn_trace_frames_t);
    *err->as.frames = *src->as.frames;
  }
 
  srn_error_trace_push(ctx, err, caller);
  return err;
}

Here is the call graph for this function:

srn_errors_make()

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, 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.

Definition at line 196 of file errors.c.

                                                                                              {
  srn_error_t *err = ALLOC(ctx, srn_error_t);
  PANIC_IF_NULL(err);
  err->layer     = SRN_ERR_RUNTIME_LAYER;
  err->tag       = tag;
  err->msg       = (char *)msg;
  err->as.frames = nullptr;
  srn_error_trace_push(ctx, err, caller);
  return err;
}

Here is the call graph for this function:

Here is the caller graph for this function: