picotm-error.h File Reference

Contains struct picotm_error and helper functions. More...

#include <picotm/config/picotm-config.h>
#include <stdbool.h>
#include <stddef.h>
#include "compiler.h"

Data Structures
struct	picotm_error

Enumerations
enum	picotm_error_code { PICOTM_GENERAL_ERROR, PICOTM_OUT_OF_MEMORY, PICOTM_INVALID_FENV, PICOTM_OUT_OF_BOUNDS }
enum	picotm_error_status {   PICOTM_CONFLICTING, PICOTM_REVOCABLE, PICOTM_ERROR_CODE, PICOTM_ERRNO,   PICOTM_KERN_RETURN_T }

Functions
PICOTM_NOTHROW void	picotm_error_clear (struct picotm_error *error)
PICOTM_NOTHROW const char *	picotm_error_get_description (const struct picotm_error *error)
PICOTM_NOTHROW bool	picotm_error_is_conflicting (const struct picotm_error *error)
PICOTM_NOTHROW bool	picotm_error_is_error (const struct picotm_error *error)
PICOTM_NOTHROW bool	picotm_error_is_revocable (const struct picotm_error *error)
static bool	picotm_error_is_set (const struct picotm_error *error)
PICOTM_NOTHROW void	picotm_error_mark_as_non_recoverable (struct picotm_error *error)
PICOTM_NOTHROW void	picotm_error_set_conflicting (struct picotm_error *error, struct picotm_rwlock *conflicting_lock)
PICOTM_NOTHROW void	picotm_error_set_description (struct picotm_error *error, const char *description)
PICOTM_NOTHROW void	picotm_error_set_errno (struct picotm_error *error, int errno_hint)
PICOTM_NOTHROW void	picotm_error_set_error_code (struct picotm_error *error, enum picotm_error_code error_hint)
PICOTM_NOTHROW void	picotm_error_set_kern_return_t (struct picotm_error *error, kern_return_t value)
PICOTM_NOTHROW void	picotm_error_set_revocable (struct picotm_error *error)

Enumeration Type Documentation

picotm_error_code

enum picotm_error_code

Signals detected errors to picotm.

If a component detects an error, it should prefer setting the system- specific error code that was returned by the failed call. This is more specific than the generic one's below. In some portable code, such as the tm module, using the generic codes might be preferable.

Enumerator
PICOTM_GENERAL_ERROR	The exact error is unknown.
PICOTM_OUT_OF_MEMORY	Out-of-Memory error.
PICOTM_INVALID_FENV	Invalid floating-point environment.
PICOTM_OUT_OF_BOUNDS	Out-of-Bounds memory access.

picotm_error_status

enum picotm_error_status

Signals error status to picotm.

Enumerator
PICOTM_CONFLICTING	Conflict among transactions detected.
PICOTM_REVOCABLE	Transaction requires irrevocability to continue.
PICOTM_ERROR_CODE	Error detected. Encoded as enum picotm_error_code.
PICOTM_ERRNO	Error detected. Encoded as errno code.
PICOTM_KERN_RETURN_T	Error detected. Encoded as kern_return_t value.

Function Documentation

picotm_error_clear()

PICOTM_NOTHROW void picotm_error_clear

(

struct picotm_error *

error

)

Clears an error structure.

Parameters

error

The error to clear.

picotm_error_get_description()

PICOTM_NOTHROW const char* picotm_error_get_description

(

const struct picotm_error *

error

)

Returns an error's description.

Parameters

error

The error.

Returns

The error description if set, or NULL otherwise.

picotm_error_is_conflicting()

PICOTM_NOTHROW bool picotm_error_is_conflicting

(

const struct picotm_error *

error

)

Tests if an error has been set to CONFLICTING status.

Parameters

error

The error to set.

Returns

True if an error has been set to CONFLICTING, or false otherwise.

picotm_error_is_error()

PICOTM_NOTHROW bool picotm_error_is_error

(

const struct picotm_error *

error

)

Tests if an error has been set to an error status.

Parameters

error

The error to set.

Returns

True if an error has been set to an error status, or false otherwise.

picotm_error_is_revocable()

PICOTM_NOTHROW bool picotm_error_is_revocable

(

const struct picotm_error *

error

)

Tests if an error has been set to REVOCABLE status.

Parameters

error

The error to set.

Returns

True if an error has been set to REVOCABLE, or false otherwise.

picotm_error_is_set()

static bool picotm_error_is_set ( const struct picotm_error *  error )

inlinestatic

Tests if an error has been set.

Parameters

error

The error to set.

Returns

True if an error has been set, or false otherwise.

picotm_error_mark_as_non_recoverable()

PICOTM_NOTHROW void picotm_error_mark_as_non_recoverable

(

struct picotm_error *

error

)

Marks an error as non-recoverable.

By default, errors are expected to recoverable. For irrevocable transactions or after applying events from the transaction log, errors cannot easily be recovered, because the program state is undefined in these situations. An errors that happens under such conditions is marked as being non-recoverable.

Normally, modules should not care baout this flag. The commit logic within picotm will set this flag if appropriate.

Parameters

error

The error to mark as non-recoverable.

picotm_error_set_conflicting()

PICOTM_NOTHROW void picotm_error_set_conflicting	(	struct picotm_error *	error,
		struct picotm_rwlock *	conflicting_lock
	)

Sets an error of type PICOTM_CONFLICTING.

Parameters

error	The error to set.
conflicting_lock	The conflicting lock if known, or NULL otherwise.

picotm_error_set_description()

PICOTM_NOTHROW void picotm_error_set_description	(	struct picotm_error *	error,
		const char *	description
	)

Sets an error's description.

Parameters

error	The error.
description	A descriptive string.

picotm_error_set_errno()

PICOTM_NOTHROW void picotm_error_set_errno	(	struct picotm_error *	error,
		int	errno_hint
	)

Sets an error of type PICOTM_ERRNO.

Parameters

error	The error to set.
errno_hint	The errno code if known, or 0 otherwise.

picotm_error_set_error_code()

PICOTM_NOTHROW void picotm_error_set_error_code	(	struct picotm_error *	error,
		enum picotm_error_code	error_hint
	)

Sets an error of type PICOTM_ERROR_CODE.

Parameters

error	The error to set.
error_hint	The picotm error code if known, or PICOTM_GENERAL_ERROR otherwise.

picotm_error_set_kern_return_t()

PICOTM_NOTHROW void picotm_error_set_kern_return_t	(	struct picotm_error *	error,
		kern_return_t	value
	)

Sets an error of type PICOTM_KERN_RETURN_T.

Parameters

error	The error to set.
value	The kern_return_t value.

picotm_error_set_revocable()

PICOTM_NOTHROW void picotm_error_set_revocable

(

struct picotm_error *

error

)

Sets an error of type PICOTM_REVOCABLE.

Parameters

error

The error to set.