Error handling

The SSM_THROW() macro is used to throw unrecoverable runtime errors. More...

Discussion

The SSM_THROW() macro is used to throw unrecoverable runtime errors.

SSM_THROW() calls the underlying ssm_throw() function with information about where in the source code the error was encountered. Because each platform may have different error-handling and logging capabilities, this library requires that the ssm_throw() symbol to be defined externally, typically by platform-specific bindings.

Any definition of ssm_throw() should not be expected to return; otherwise, the behavior of subsequently interacting with the runtime library becomes undefined. For example, a platform-independent definition of ssm_throw() may just spin indefinitely, though this does not provide very helpful feedback for debugging:

void ssm_throw(ssm_error_t reason, const char *file, int line,
               const char *func) {
  for (;;);
}

A more sensible definition might call exit(), perhaps after logging some relevant information using the provided arguments:

void ssm_throw(ssm_error_t reason, const char *file, int line,
               const char *func) {
  printf("SSM error at %s:%d (%s): reason: %d\n", file, line, func, reason);
  exit(reason);
}

Macros
#define	SSM_ASSERT(cond)
	Throw an internal error. More...
#define	SSM_THROW(reason)   ssm_throw(reason, __FILE__, __LINE__, __func__)
	Terminate due to a non-recoverable error, with a specified reason. More...

Typedefs
typedef enum ssm_error	ssm_error_t
	Error codes indicating reason for failure. More...

Enumerations
enum	ssm_error {   SSM_INTERNAL_ERROR = 1 , SSM_EXHAUSTED_ACT_QUEUE , SSM_EXHAUSTED_EVENT_QUEUE , SSM_EXHAUSTED_MEMORY ,   SSM_EXHAUSTED_PRIORITY , SSM_NOT_READY , SSM_INVALID_TIME , SSM_INVALID_MEMORY ,   SSM_PLATFORM_ERROR }
	Error codes indicating reason for failure. More...

Functions
void	ssm_throw (ssm_error_t reason, const char *file, int line, const char *func)
	Underlying exception handler; must be overridden by each platform. More...

Macro Definition Documentation

SSM_ASSERT

#define SSM_ASSERT

(

cond

)

Value:

  do                                                                           \
    if (!(cond))                                                               \
      SSM_THROW(SSM_INTERNAL_ERROR);                                           \
  while (0)

Throw an internal error.

Note

Intended for platform code; should not be used in user code.

Parameters

cond	the condition to assert.

Definition at line 23 of file ssm-internal.h.

SSM_THROW

#define SSM_THROW

(

reason

)

ssm_throw(reason, __FILE__, __LINE__, __func__)

Terminate due to a non-recoverable error, with a specified reason.

Invoked when a process must terminate, e.g., when memory or queue space is exhausted. Not expected to terminate.

Wraps the underlying ssm_throw() exception handler, passing along the file name, line number, and function name in the source file where the error was thrown.

Parameters

reason

an ssm_error_t specifying the reason for the error.

Definition at line 69 of file ssm.h.

Typedef Documentation

ssm_error_t

typedef enum ssm_error ssm_error_t

Error codes indicating reason for failure.

Platforms may extend the list of errors using SSM_PLATFORM_ERROR like this:

enum {
  SSM_CUSTOM_ERROR_CODE1 = SSM_PLATFORM_ERROR,
  SSM_CUSTOM_ERROR_CODE2,
  // etc.
};

Enumeration Type Documentation

ssm_error

enum ssm_error

Error codes indicating reason for failure.

Platforms may extend the list of errors using SSM_PLATFORM_ERROR like this:

enum {
  SSM_CUSTOM_ERROR_CODE1 = SSM_PLATFORM_ERROR,
  SSM_CUSTOM_ERROR_CODE2,
  // etc.
};

Enumerator
SSM_INTERNAL_ERROR	Reserved for unforeseen, non-user-facing errors.
SSM_EXHAUSTED_ACT_QUEUE	Tried to insert into full activation record queue.
SSM_EXHAUSTED_EVENT_QUEUE	Tried to insert into full event queue.
SSM_EXHAUSTED_MEMORY	Could not allocate more memory.
SSM_EXHAUSTED_PRIORITY	Tried to exceed available recursion depth.
SSM_NOT_READY	Not yet ready to perform the requested action.
SSM_INVALID_TIME	Specified invalid time, e.g., scheduled assignment at an earlier time.
SSM_INVALID_MEMORY	Invalid memory layout, e.g., using a pointer where int was expected.
SSM_PLATFORM_ERROR	Start of platform-specific error code range.

Definition at line 37 of file ssm.h.

Function Documentation

ssm_throw()

void ssm_throw	(	ssm_error_t	reason,
		const char *	file,
		int	line,
		const char *	func
	)

Underlying exception handler; must be overridden by each platform.

This is left undefined by the SSM runtime for portability. On platforms where exit() is available, that may be used. Where possible, an exception handler may also log additional information using the given parameters for better debuggability.

Parameters

reason	an ssm_error_t specifying the reason for the error.
file	the file name of the source file where the error was thrown.
line	the line number of the source file where the error was thrown.
func	the function name where the error was thrown.