picotm  0.10.0
Macros | Functions
picotm.h File Reference

Main header file for picotm. More...

#include <picotm/config/picotm-config.h>
#include <setjmp.h>
#include "compiler.h"
#include "picotm-error.h"

Macros

#define picotm_begin
 
#define picotm_commit
 
#define picotm_end
 
#define picotm_safe
 

Functions

PICOTM_NOTHROW int picotm_error_as_errno (void)
 
PICOTM_NOTHROW enum picotm_error_code picotm_error_as_error_code (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

This is the main header file for picotm. It contains the entry points for starting, committing and ending a transaction; for restarting, and for error handling.

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

#define picotm_safe

Marks a non-transactional variable in a function.

When restarting a transaction, picotm uses non-local goto, based on the sigjmp() 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 sigjmp() 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.

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

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.