Files | Macros | Enumerations | Functions
The picotm Programming Interface

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


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.


#define picotm_begin
#define picotm_commit
#define picotm_end
#define picotm_safe
#define PICOTM_STATIC_ASSERT(_cond, _errmsg)
 _cond The compile-time assertion. More...


enum  picotm_error_status {


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

Writing Transactions

Each transactions contains at least the statements

  1. picotm_begin,
  2. picotm_commit, and
  3. picotm_end

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

// non-transactional code
int x = 0;
// transactional code
// 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 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.



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.

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

◆ picotm_end

#define picotm_end

Ends the current transaction.



End interface declarations



Export interface from binary object.



Exported function does not return.



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.

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.


#define PICOTM_STATIC_ASSERT (   _cond,

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

Enumeration Type Documentation

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


The exact error is unknown.


Out-of-Memory error.


Invalid floating-point environment.


Out-of-Bounds memory access.

◆ picotm_error_status

Signals error status to picotm.


Conflict among transactions detected.


Transaction requires irrevocability to continue.


Error detected. Encoded as enum picotm_error_code.


Error detected. Encoded as errno code.


Error detected. Encoded as kern_return_t value.


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.

This function is only valid during the transaction's recovery phase, and if picotm_error_status() is PICOTM_ERRNO.
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.

This function is only valid during the transaction's recovery phase, and if picotm_error_status() is PICOTM_ERROR_CODE.
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.

This function is only valid during the transaction's recovery phase, and if picotm_error_status() is PICOTM_KERN_RETURN_T.
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.

This function is only valid during the transaction's recovery phase, and if picotm_error_status() is PICOTM_SIGINFO_T.
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.

This function is only valid during the transaction's recovery phase.
The current error status.

◆ picotm_error_status()

Returns the current error status.

This function is only valid during the transaction's recovery phase.
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.