errors.h File Reference

Error handling for the runtime. More...

#include <stddef.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_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	HAS_ERROR(x)
	True when x – a value carrying an ERROR_HEADER – has an error attached.
#define	ERR(ctx, err, msg)
#define	FAIL(ctx, T, err, msg)

Typedefs
typedef enum srn_error_tag_t	srn_error_tag_t
	The kind of a failure.
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 , 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 ,   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 , UNKNOWN_IO_ERROR }
	The kind of a failure. More...

Functions
srn_error_t *	srn_errors_make (const srn_context_t *ctx, srn_error_tag_t tag, const char *msg)
	Build an error in ctx's memory, tagged tag and carrying msg.
void *	srn_errors_fail (const srn_context_t *ctx, size_t size, size_t alignment, 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.
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)

Definition at line 148 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 56 of file errors.h.

FAIL

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

Value:

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

Definition at line 149 of file errors.h.

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 63 of file errors.h.

Typedef Documentation

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.

Enumeration Type Documentation

srn_error_tag_t

enum srn_error_tag_t

The kind of a failure.

Each srn_error_t carries one of these.

Enumerator
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
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.
UNKNOWN_IO_ERROR

Definition at line 75 of file errors.h.

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

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_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 )

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 39 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);
  return value;
}

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 )

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.

Definition at line 31 of file errors.c.

                                                                                             {
  srn_error_t *err = ALLOC(ctx, srn_error_t);
  PANIC_IF_NULL(err);
  err->tag = tag;
  err->msg = (char *)msg;
  return err;
}

Here is the caller graph for this function: