This section provides information for users of picotm. It explains the concept of transactions and how to run a transaction with picotm. More...

Files
file	compiler.h
	Contains macros for dealing with compiler extensions.

file	picotm-error-base.h
	Contains picotm error constants.

file	picotm.h
	Main header file for picotm.

Macros
#define	picotm_begin

#define	PICOTM_BEGIN_DECLS

#define	picotm_commit

#define	picotm_end

#define	PICOTM_END_DECLS

#define	PICOTM_EXPORT

#define	PICOTM_NORETURN

#define	PICOTM_NOTHROW

#define	picotm_safe

#define	PICOTM_STATIC_ASSERT(_cond, _errmsg)
	_cond The compile-time assertion. More...

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, PICOTM_SIGINFO_T }

Functions
PICOTM_NOTHROW int	picotm_error_as_errno (void)

PICOTM_NOTHROW enum picotm_error_code	picotm_error_as_error_code (void)

kern_return_t	picotm_error_as_kern_return_t (void)

const siginfo_t *	picotm_error_as_siginfo_t (void)

PICOTM_NOTHROW _Bool	picotm_error_is_non_recoverable (void)

PICOTM_NOTHROW enum picotm_error_status	picotm_error_status ()

PICOTM_NOTHROW unsigned long	picotm_number_of_restarts (void)

PICOTM_NOTHROW void	picotm_release (void)

PICOTM_NOTHROW void	picotm_restart (void)

Detailed Description

Properties of a Transaction

The transaction concept is a powerful metaphor for implementing concurrent and fault-tolerant software. A transaction system provides two services to it's users. These are

concurrency control (i.e., thread-safe access to shared resources), and
error handling.

Writing Transactions

Each transactions contains at least the statements

in this exact order. In the source code, this looks like this

void
func()
{
     // non-transactional code
     int x = 0;
     picotm_begin
         // transactional code
     picotm_commit
     picotm_end
     // more non-transactional code
}

Transactional operations are invoked between picotm_begin and picotm_commit. This is called the transaction's execution phase. Operations listed in the execution phase are subject to speculative execution. This means that an operation might be executed, but it's effects are not permanent until the transaction commits.

The transaction performs a commit when the user invokes picotm_commit. This is called the commit phase. It is completely implemented by picotm. No intervention by the user is required.

Upon entering the commit phase, picotm validates the consistency of all resources that the transaction uses. If validation succeeds, the transaction's effects are applied to become permanent. The program then continuous with the next operation after picotm_end. If validation fails, the transaction's effects are reverted and the transaction restarts from picotm_begin. The roll-back is transparent to the program.

If an operation fails, picotm provides error handling for it's operations. Error handling consists of

error detection, and
error recovery.

Error detection is completely implemented by picotm an it's module. When picotm invokes an operation it tests for reported errors. No intervention by the user is required.

Error recovery is partially provided by picotm. For picotm, it is possible to recover from some errors. For example, if a write operation to a file temporarily fails, picotm can retry.

Some errors require special program logic to recover. For example, if the program runs out of memory, it might free up memory by invoking a garbage collector. This cannot generally be implemented by picotm, as it depends on program-specific constraints. This is called the recovery phase.

Error-recovery code is located between picotm_commit and picotm_end. If picotm detects an error that is cannot recover from, it rolls back the transaction's effects and jumps to the first instruction after picotm_commit. The program now has the chance of performing error recovery and, if successful, restart the transaction by calling picotm_restart().

Macro Definition Documentation

◆ picotm_begin

#define picotm_begin

Starts a new transaction.

Invoking picotm_begin starts a new transaction. Any code between this macro and picotm_commit is considered part of the transaction's execution phase. If the transaction aborts, it will restart from where the picotm_begin had been invoked.

◆ PICOTM_BEGIN_DECLS

#define PICOTM_BEGIN_DECLS

Begin interface declarations

◆ picotm_commit

#define picotm_commit

Commits the current transaction.

This macro commits the currently running transaction. Picotm will validate the consistency of all of the transaction's resources and, if successful, apply all outstanding operations. If validation fails, the transaction will be restarted from picotm_begin.

Attention: Calling this macro is only valid after picotm_begin and before picotm_end.

◆ picotm_end

#define picotm_end

Ends the current transaction.

◆ PICOTM_END_DECLS

#define PICOTM_END_DECLS

End interface declarations

◆ PICOTM_EXPORT

#define PICOTM_EXPORT

Export interface from binary object.

◆ PICOTM_NORETURN

#define PICOTM_NORETURN

Exported function does not return.

◆ PICOTM_NOTHROW

#define PICOTM_NOTHROW

Exported function does not throw exceptions.

◆ picotm_safe

#define picotm_safe

Marks a non-transactional variable in a function.

When restarting a transaction, picotm uses non-local goto, based on the setjmp() and longjmp() functions provided by the C Standard Library. These functions save and restore the thread's instruction and stack pointer, but don't save any variables. This can result in program errors if a variable is held in a register that changes its value between invocations of setjmp() and longjmp(). The call to longjmp() will not restore the variable's original value.

To avoid this problem, mark local, non-transactional variables with picotm_safe as shown below.

picotm_safe int var = 0;
picotm_begin
    [...]
picotm_commit
picotm_end

Even with picotm_safe, you still have to privatize the variable when using it within the transaction.

With gcc, the command-line option '-Wclobbered' enables a warning about this problem.

◆ PICOTM_STATIC_ASSERT

#define PICOTM_STATIC_ASSERT	(	_cond,
		_errmsg
	)

Provides a portable static assertion. _errmsg An error message that is printed if the condition fails.

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.
PICOTM_SIGINFO_T	Error detected. Encoded as signal's `siginfo_t` value.

Function Documentation

◆ picotm_error_as_errno()

PICOTM_NOTHROW int picotm_error_as_errno ( void )

Returns the current picotm errno code.

Attention: This function is only valid during the transaction's recovery phase, and if picotm_error_status() is PICOTM_ERRNO.

Returns: The current picotm errno code.

◆ picotm_error_as_error_code()

PICOTM_NOTHROW enum picotm_error_code picotm_error_as_error_code ( void )

Returns the current picotm error code.

Attention: This function is only valid during the transaction's recovery phase, and if picotm_error_status() is PICOTM_ERROR_CODE.

Returns: The current picotm error code.

◆ picotm_error_as_kern_return_t()

kern_return_t picotm_error_as_kern_return_t ( void )

Returns the current picotm kern_return_t value.

Attention: This function is only valid during the transaction's recovery phase, and if picotm_error_status() is PICOTM_KERN_RETURN_T.

Returns: The current picotm kern_return_t value.

◆ picotm_error_as_siginfo_t()

const siginfo_t* picotm_error_as_siginfo_t ( void )

Returns the current error's siginfo_t value.

Attention: This function is only valid during the transaction's recovery phase, and if picotm_error_status() is PICOTM_SIGINFO_T.

Returns: The current siginfo_t value.

◆ picotm_error_is_non_recoverable()

PICOTM_NOTHROW _Bool picotm_error_is_non_recoverable ( void )

Returns the current error's recoverable status.

Attention: This function is only valid during the transaction's recovery phase.

Returns: The current error status.

◆ picotm_error_status()

PICOTM_NOTHROW enum picotm_error_status picotm_error_status ( )

Returns the current error status.

Attention: This function is only valid during the transaction's recovery phase.

Returns: The current error status.

◆ picotm_number_of_restarts()

PICOTM_NOTHROW unsigned long picotm_number_of_restarts ( void )

Returns the number of restarts of the thread's most recent transaction.

◆ picotm_release()

PICOTM_NOTHROW void picotm_release ( void )

Releases all resources of picotm on the current thread.

◆ picotm_restart()

PICOTM_NOTHROW void picotm_restart ( void )

Restarts the current transaction.

Files

Macros

Enumerations

Functions