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.

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.

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

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.

Macros

Functions