TinySTM  1.0.5
Data Structures | Macros | Typedefs | Enumerations | Functions
stm.h File Reference

STM functions. More...

Go to the source code of this file.

Data Structures

union  stm_tx_attr
 Transaction attributes specified by the application. More...
 

Macros

#define STM_VERSION   "1.0.5"
 Version string.
 
#define STM_VERSION_NB   105
 Version number (times 100)
 
#define _CALLCONV
 Calling convention.
 

Typedefs

typedef uintptr_t stm_word_t
 Size of a word (accessible atomically) on the target architecture. More...
 
typedef union stm_tx_attr stm_tx_attr_t
 Transaction attributes specified by the application.
 

Enumerations

enum  {
  STM_PATH_INSTRUMENTED = 0x01, STM_PATH_UNINSTRUMENTED = 0x02, STM_ABORT_EXPLICIT = (1 << 5), STM_ABORT_NO_RETRY = (1 << 5) | (0x01 << 8),
  STM_ABORT_IMPLICIT = (1 << 6), STM_ABORT_RR_CONFLICT = (1 << 6) | (0x01 << 8), STM_ABORT_RW_CONFLICT = (1 << 6) | (0x02 << 8), STM_ABORT_WR_CONFLICT = (1 << 6) | (0x03 << 8),
  STM_ABORT_WW_CONFLICT = (1 << 6) | (0x04 << 8), STM_ABORT_VAL_READ = (1 << 6) | (0x05 << 8), STM_ABORT_VAL_WRITE = (1 << 6) | (0x06 << 8), STM_ABORT_VALIDATE = (1 << 6) | (0x07 << 8),
  STM_ABORT_IRREVOCABLE = (1 << 6) | (0x09 << 8), STM_ABORT_KILLED = (1 << 6) | (0x0A << 8), STM_ABORT_SIGNAL = (1 << 6) | (0x0B << 8), STM_ABORT_EXTEND_WS = (1 << 6) | (0x0C << 8),
  STM_ABORT_OTHER = (1 << 6) | (0x0F << 8)
}
 Reason for aborting (returned by sigsetjmp() upon transaction restart). More...
 

Functions

struct stm_tx * stm_current_tx (void)
 Return the current transaction descriptor. More...
 
void stm_init (void)
 Initialize the STM library. More...
 
void stm_exit (void)
 Clean up the STM library. More...
 
struct stm_tx * stm_init_thread (void)
 Initialize a transactional thread. More...
 
int stm_get_parameter (const char *name, void *val)
 Get various parameters of the STM library. More...
 
int stm_set_parameter (const char *name, void *val)
 Set various parameters of the STM library. More...
 
int stm_create_specific (void)
 Create a key to associate application-specific data to the current thread/transaction. More...
 
int stm_register (void(*on_thread_init)(void *arg), void(*on_thread_exit)(void *arg), void(*on_start)(void *arg), void(*on_precommit)(void *arg), void(*on_commit)(void *arg), void(*on_abort)(void *arg), void *arg)
 Register application-specific callbacks that are triggered each time particular events occur. More...
 
stm_word_t stm_unit_load (volatile stm_word_t *addr, stm_word_t *timestamp)
 Transaction-safe load. More...
 
int stm_unit_store (volatile stm_word_t *addr, stm_word_t value, stm_word_t *timestamp)
 Transaction-safe store. More...
 
int stm_unit_store2 (volatile stm_word_t *addr, stm_word_t value, stm_word_t mask, stm_word_t *timestamp)
 Transaction-safe store. More...
 
stm_word_t stm_get_clock (void)
 Read the current value of the global clock (used for timestamps). More...
 
void stm_exit_thread (void)
 Clean up a transactional thread. More...
 
void stm_exit_thread_tx (struct stm_tx *tx)
 
sigjmp_buf * stm_start (stm_tx_attr_t attr)
 Start a transaction. More...
 
sigjmp_buf * stm_start_tx (struct stm_tx *tx, stm_tx_attr_t attr)
 
int stm_commit (void)
 Try to commit a transaction. More...
 
int stm_commit_tx (struct stm_tx *tx)
 
void stm_abort (int abort_reason)
 Explicitly abort a transaction. More...
 
void stm_abort_tx (struct stm_tx *tx, int abort_reason)
 
stm_word_t stm_load (volatile stm_word_t *addr)
 Transactional load. More...
 
stm_word_t stm_load_tx (struct stm_tx *tx, volatile stm_word_t *addr)
 
void stm_store (volatile stm_word_t *addr, stm_word_t value)
 Transactional store. More...
 
void stm_store_tx (struct stm_tx *tx, volatile stm_word_t *addr, stm_word_t value)
 
void stm_store2 (volatile stm_word_t *addr, stm_word_t value, stm_word_t mask)
 Transactional store. More...
 
void stm_store2_tx (struct stm_tx *tx, volatile stm_word_t *addr, stm_word_t value, stm_word_t mask)
 
int stm_active (void)
 Check if the current transaction is still active. More...
 
int stm_active_tx (struct stm_tx *tx)
 
int stm_aborted (void)
 Check if the current transaction has aborted. More...
 
int stm_aborted_tx (struct stm_tx *tx)
 
int stm_irrevocable (void)
 Check if the current transaction is still active and in irrevocable state. More...
 
int stm_irrevocable_tx (struct stm_tx *tx)
 
int stm_killed (void)
 Check if the current transaction has been killed. More...
 
int stm_killed_tx (struct stm_tx *tx)
 
sigjmp_buf * stm_get_env (void)
 Get the environment used by the current thread to jump back upon abort. More...
 
sigjmp_buf * stm_get_env_tx (struct stm_tx *tx)
 
stm_tx_attr_t stm_get_attributes (void)
 Get attributes associated with the current transactions, if any. More...
 
stm_tx_attr_t stm_get_attributes_tx (struct stm_tx *tx)
 
int stm_get_stats (const char *name, void *val)
 Get various statistics about the current thread/transaction. More...
 
int stm_get_stats_tx (struct stm_tx *tx, const char *name, void *val)
 
void * stm_get_specific (int key)
 Get application-specific data associated to the current thread/transaction and a given key. More...
 
void * stm_get_specific_tx (struct stm_tx *tx, int key)
 
void stm_set_specific (int key, void *data)
 Set application-specific data associated to the current thread/transaction and a given key. More...
 
void stm_set_specific_tx (struct stm_tx *tx, int key, void *data)
 
void stm_set_extension (int enable, stm_word_t *timestamp)
 Enable or disable snapshot extensions for the current transaction, and optionally set an upper bound for the snapshot. More...
 
void stm_set_extension_tx (struct stm_tx *tx, int enable, stm_word_t *timestamp)
 
int stm_set_irrevocable (int serial)
 Enter irrevocable mode for the current transaction. More...
 
int stm_set_irrevocable_tx (struct stm_tx *tx, int serial)
 

Detailed Description

STM functions.

This library contains the core functions for programming with STM.

Author
Pascal Felber pasca.nosp@m.l.fe.nosp@m.lber@.nosp@m.unin.nosp@m.e.ch Patrick Marlier patri.nosp@m.ck.m.nosp@m.arlie.nosp@m.r@un.nosp@m.ine.c.nosp@m.h
Date
2007-2014

Typedef Documentation

typedef uintptr_t stm_word_t

Size of a word (accessible atomically) on the target architecture.

The library supports 32-bit and 64-bit architectures.

Enumeration Type Documentation

anonymous enum

Reason for aborting (returned by sigsetjmp() upon transaction restart).

Enumerator
STM_PATH_INSTRUMENTED 

Indicates that the instrumented code path must be executed.

STM_PATH_UNINSTRUMENTED 

Indicates that the uninstrumented code path must be executed (serial irrevocable mode).

STM_ABORT_EXPLICIT 

Abort due to explicit call from the programmer.

STM_ABORT_NO_RETRY 

Abort and no retry due to explicit call from the programmer.

STM_ABORT_IMPLICIT 

Implicit abort (high order bits indicate more detailed reason).

STM_ABORT_RR_CONFLICT 

Abort upon reading a memory location being read by another transaction.

STM_ABORT_RW_CONFLICT 

Abort upon writing a memory location being read by another transaction.

STM_ABORT_WR_CONFLICT 

Abort upon reading a memory location being written by another transaction.

STM_ABORT_WW_CONFLICT 

Abort upon writing a memory location being written by another transaction.

STM_ABORT_VAL_READ 

Abort upon read due to failed validation.

STM_ABORT_VAL_WRITE 

Abort upon write due to failed validation.

STM_ABORT_VALIDATE 

Abort upon commit due to failed validation.

STM_ABORT_IRREVOCABLE 

Abort upon deferring to an irrevocable transaction.

STM_ABORT_KILLED 

Abort due to being killed by another transaction.

STM_ABORT_SIGNAL 

Abort due to receiving a signal.

STM_ABORT_EXTEND_WS 

Abort due to reaching the write set size limit.

STM_ABORT_OTHER 

Abort due to other reasons (internal to the protocol).

Function Documentation

void stm_abort ( int  abort_reason)

Explicitly abort a transaction.

Execution continues at the point where sigsetjmp() has been called after starting the outermost transaction (unless the attributes indicate that the transaction should not retry).

Parameters
abort_reasonReason for aborting the transaction.
int stm_aborted ( void  )

Check if the current transaction has aborted.

Returns
True (non-zero) if the transaction has aborted, false (zero) otherwise.
int stm_active ( void  )

Check if the current transaction is still active.

Returns
True (non-zero) if the transaction is active, false (zero) otherwise.
int stm_commit ( void  )

Try to commit a transaction.

If successful, the function returns 1. Otherwise, execution continues at the point where sigsetjmp() has been called after starting the outermost transaction (unless the attributes indicate that the transaction should not retry).

Returns
1 upon success, 0 otherwise.
int stm_create_specific ( void  )

Create a key to associate application-specific data to the current thread/transaction.

This mechanism can be combined with callbacks to write modules.

Returns
The new key.
struct stm_tx* stm_current_tx ( void  )

Return the current transaction descriptor.

The library does not require to pass the current transaction as a parameter to the functions (the current transaction is stored in a thread-local variable). One can, however, use the library with explicit transaction parameters. This is useful, for instance, for performance on architectures that do not support TLS or for easier compiler integration.

void stm_exit ( void  )

Clean up the STM library.

This function must be called once, from the main thread, after all transactional threads have completed.

void stm_exit_thread ( void  )

Clean up a transactional thread.

This function must be called once from each thread that performs transactional operations, upon exit.

stm_tx_attr_t stm_get_attributes ( void  )

Get attributes associated with the current transactions, if any.

These attributes were passed as parameters when starting the transaction.

Returns
Attributes associated with the current transaction, or NULL if no attributes were specified when starting the transaction.
stm_word_t stm_get_clock ( void  )

Read the current value of the global clock (used for timestamps).

This function is useful when programming with unit loads and stores.

Returns
Value of the global clock.
sigjmp_buf* stm_get_env ( void  )

Get the environment used by the current thread to jump back upon abort.

This environment should be used when calling sigsetjmp() before starting the transaction and passed as parameter to stm_start(). If the current thread is already executing a transaction, i.e., the new transaction will be nested, the function returns NULL and one should not call sigsetjmp().

Returns
The environment to use for saving the stack context, or NULL if the transaction is nested.
int stm_get_parameter ( const char *  name,
void *  val 
)

Get various parameters of the STM library.

See the source code (stm.c) for a list of supported parameters.

Parameters
nameName of the parameter.
valPointer to the variable that should hold the value of the parameter.
Returns
1 upon success, 0 otherwise.
void* stm_get_specific ( int  key)

Get application-specific data associated to the current thread/transaction and a given key.

Parameters
keyKey designating the data to read.
Returns
Data stored under the given key.
int stm_get_stats ( const char *  name,
void *  val 
)

Get various statistics about the current thread/transaction.

See the source code (stm.c) for a list of supported statistics.

Parameters
nameName of the statistics.
valPointer to the variable that should hold the value of the statistics.
Returns
1 upon success, 0 otherwise.
void stm_init ( void  )

Initialize the STM library.

This function must be called once, from the main thread, before any access to the other functions of the library.

struct stm_tx* stm_init_thread ( void  )

Initialize a transactional thread.

This function must be called once from each thread that performs transactional operations, before the thread calls any other functions of the library.

int stm_irrevocable ( void  )

Check if the current transaction is still active and in irrevocable state.

Returns
True (non-zero) if the transaction is active and irrevocable, false (zero) otherwise.
int stm_killed ( void  )

Check if the current transaction has been killed.

Returns
True (non-zero) if the transaction has been killed, false (zero) otherwise.
stm_word_t stm_load ( volatile stm_word_t addr)

Transactional load.

Read the specified memory location in the context of the current transaction and return its value. Upon conflict, the transaction may abort while reading the memory location. Note that the value returned is consistent with respect to previous reads from the same transaction.

Parameters
addrAddress of the memory location.
Returns
Value read from the specified address.
int stm_register ( void(*)(void *arg)  on_thread_init,
void(*)(void *arg)  on_thread_exit,
void(*)(void *arg)  on_start,
void(*)(void *arg)  on_precommit,
void(*)(void *arg)  on_commit,
void(*)(void *arg)  on_abort,
void *  arg 
)

Register application-specific callbacks that are triggered each time particular events occur.

Parameters
on_thread_initFunction called upon initialization of a transactional thread.
on_thread_exitFunction called upon cleanup of a transactional thread.
on_startFunction called upon start of a transaction.
on_precommitFunction called before transaction try to commit.
on_commitFunction called upon successful transaction commit.
on_abortFunction called upon transaction abort.
argParameter to be passed to the callback functions.
Returns
1 if the callbacks have been successfully registered, 0 otherwise.
void stm_set_extension ( int  enable,
stm_word_t timestamp 
)

Enable or disable snapshot extensions for the current transaction, and optionally set an upper bound for the snapshot.

This function is useful for implementing efficient algorithms with unit loads and stores while preserving compatibility with with regular transactions.

Parameters
enableTrue (non-zero) to enable snapshot extensions, false (zero) to disable them.
timestampIf non-null and the timestamp in the referenced variable is smaller than the current upper bound of the snapshot, update the upper bound to the value of the referenced variable.
int stm_set_irrevocable ( int  serial)

Enter irrevocable mode for the current transaction.

If successful, the function returns 1. Otherwise, it aborts and execution continues at the point where sigsetjmp() has been called after starting the outermost transaction (unless the attributes indicate that the transaction should not retry).

Parameters
serialTrue (non-zero) for serial-irrevocable mode (no transaction can execute concurrently), false for parallel-irrevocable mode.
Returns
1 upon success, 0 otherwise.
int stm_set_parameter ( const char *  name,
void *  val 
)

Set various parameters of the STM library.

See the source code (stm.c) for a list of supported parameters.

Parameters
nameName of the parameter.
valPointer to a variable that holds the new value of the parameter.
Returns
1 upon success, 0 otherwise.
void stm_set_specific ( int  key,
void *  data 
)

Set application-specific data associated to the current thread/transaction and a given key.

Parameters
keyKey designating the data to read.
dataData to store under the given key.
sigjmp_buf* stm_start ( stm_tx_attr_t  attr)

Start a transaction.

Parameters
attrSpecifies optional attributes associated to the transaction. Attributes are copied in transaction-local storage. If null, the transaction uses default attributes.
Returns
Environment (stack context) to be used to jump back upon abort. It is the responsibility of the application to call sigsetjmp() immediately after starting the transaction. If the transaction is nested, the function returns NULL and one should not call sigsetjmp() as an abort will restart the top-level transaction (flat nesting).
void stm_store ( volatile stm_word_t addr,
stm_word_t  value 
)

Transactional store.

Write a word-sized value to the specified memory location in the context of the current transaction. Upon conflict, the transaction may abort while writing to the memory location.

Parameters
addrAddress of the memory location.
valueValue to be written.
void stm_store2 ( volatile stm_word_t addr,
stm_word_t  value,
stm_word_t  mask 
)

Transactional store.

Write a value to the specified memory location in the context of the current transaction. The value may be smaller than a word on the target architecture, in which case a mask is used to indicate the bits of the words that must be updated. Upon conflict, the transaction may abort while writing to the memory location.

Parameters
addrAddress of the memory location.
valueValue to be written.
maskMask specifying the bits to be written.
stm_word_t stm_unit_load ( volatile stm_word_t addr,
stm_word_t timestamp 
)

Transaction-safe load.

Read the specified memory location outside of the context of any transaction and return its value. The operation behaves as if executed in the context of a dedicated transaction (i.e., it executes atomically and in isolation) that never aborts, but may get delayed.

Parameters
addrAddress of the memory location.
timestampIf non-null, the referenced variable is updated to hold the timestamp of the memory location being read.
Returns
Value read from the specified address.
int stm_unit_store ( volatile stm_word_t addr,
stm_word_t  value,
stm_word_t timestamp 
)

Transaction-safe store.

Write a word-sized value to the specified memory location outside of the context of any transaction. The operation behaves as if executed in the context of a dedicated transaction (i.e., it executes atomically and in isolation) that never aborts, but may get delayed.

Parameters
addrAddress of the memory location.
valueValue to be written.
timestampIf non-null and the timestamp in the referenced variable is smaller than that of the memory location being written, no data is actually written and the variable is updated to hold the more recent timestamp. If non-null and the timestamp in the referenced variable is not smaller than that of the memory location being written, the memory location is written and the variable is updated to hold the new timestamp.
Returns
1 if value has been written, 0 otherwise.
int stm_unit_store2 ( volatile stm_word_t addr,
stm_word_t  value,
stm_word_t  mask,
stm_word_t timestamp 
)

Transaction-safe store.

Write a value to the specified memory location outside of the context of any transaction. The value may be smaller than a word on the target architecture, in which case a mask is used to indicate the bits of the words that must be updated. The operation behaves as if executed in the context of a dedicated transaction (i.e., it executes atomically and in isolation) that never aborts, but may get delayed.

Parameters
addrAddress of the memory location.
valueValue to be written.
maskMask specifying the bits to be written.
timestampIf non-null and the timestamp in the referenced variable is smaller than that of the memory location being written, no data is actually written and the variable is updated to hold the more recent timestamp. If non-null and the timestamp in the referenced variable is not smaller than that of the memory location being written, the memory location is written and the variable is updated to hold the new timestamp.
Returns
1 if value has been written, 0 otherwise.