STM functions. More...
Go to the source code of this file.
Data Structures | |
struct | stm_tx_attr |
Transaction attributes specified by the application. More... | |
Defines | |
#define | STM_VERSION "1.0.0" |
#define | STM_VERSION_NB 100 |
Typedefs | |
typedef uintptr_t | stm_word_t |
Size of a word (accessible atomically) on the target architecture. | |
typedef struct stm_tx_attr | stm_tx_attr_t |
Transaction attributes specified by the application. | |
Enumerations | |
enum | { STM_ABORT_EXPLICIT = (1 << 4), STM_ABORT_IMPLICIT = (1 << 5), STM_ABORT_RR_CONFLICT = (1 << 5) | (0x01 << 8), STM_ABORT_RW_CONFLICT = (1 << 5) | (0x02 << 8), STM_ABORT_WR_CONFLICT = (1 << 5) | (0x03 << 8), STM_ABORT_WW_CONFLICT = (1 << 5) | (0x04 << 8), STM_ABORT_VAL_READ = (1 << 5) | (0x05 << 8), STM_ABORT_VAL_WRITE = (1 << 5) | (0x06 << 8), STM_ABORT_VALIDATE = (1 << 5) | (0x07 << 8), STM_ABORT_RO_WRITE = (1 << 5) | (0x08 << 8), STM_ABORT_IRREVOCABLE = (1 << 5) | (0x09 << 8), STM_ABORT_KILLED = (1 << 5) | (0x0A << 8), STM_ABORT_SIGNAL = (1 << 5) | (0x0B << 8), STM_ABORT_OTHER = (1 << 5) | (0x0F << 8) } |
Reason for aborting (returned by sigsetjmp() upon transaction restart). More... | |
Functions | |
void | stm_init () |
Initialize the STM library. | |
void | stm_exit () |
Clean up the STM library. | |
void | stm_init_thread () |
Initialize a transactional thread. | |
void | stm_exit_thread () |
Clean up a transactional thread. | |
sigjmp_buf * | stm_start (stm_tx_attr_t *attr) |
Start a transaction. | |
int | stm_commit () |
Try to commit a transaction. | |
void | stm_abort (int abort_reason) |
Explicitly abort a transaction. | |
stm_word_t | stm_load (volatile stm_word_t *addr) |
Transactional load. | |
void | stm_store (volatile stm_word_t *addr, stm_word_t value) |
Transactional store. | |
void | stm_store2 (volatile stm_word_t *addr, stm_word_t value, stm_word_t mask) |
Transactional store. | |
int | stm_active () |
Check if the current transaction is still active. | |
int | stm_aborted () |
Check if the current transaction has aborted. | |
int | stm_irrevocable () |
Check if the current transaction is still active and in irrevocable state. | |
sigjmp_buf * | stm_get_env () |
Get the environment used by the current thread to jump back upon abort. | |
stm_tx_attr_t * | stm_get_attributes () |
Get attributes associated with the current transactions, if any. | |
int | stm_get_stats (const char *name, void *val) |
Get various statistics about the current thread/transaction. | |
int | stm_get_parameter (const char *name, void *val) |
Get various parameters of the STM library. | |
int | stm_set_parameter (const char *name, void *val) |
Set various parameters of the STM library. | |
int | stm_create_specific () |
Create a key to associate application-specific data to the current thread/transaction. | |
void * | stm_get_specific (int key) |
Get application-specific data associated to the current thread/transaction and a given key. | |
void | stm_set_specific (int key, void *data) |
Set application-specific data associated to the current thread/transaction and a given key. | |
int | stm_register (void(*on_thread_init)(void *arg), void(*on_thread_exit)(void *arg), void(*on_start)(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. | |
stm_word_t | stm_unit_load (volatile stm_word_t *addr, stm_word_t *timestamp) |
Transaction-safe load. | |
int | stm_unit_store (volatile stm_word_t *addr, stm_word_t value, stm_word_t *timestamp) |
Transaction-safe store. | |
int | stm_unit_store2 (volatile stm_word_t *addr, stm_word_t value, stm_word_t mask, stm_word_t *timestamp) |
Transaction-safe store. | |
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. | |
stm_word_t | stm_get_clock () |
Read the current value of the global clock (used for timestamps). | |
int | stm_set_irrevocable (int serial) |
Enter irrevokable mode for the current transaction. |
STM functions.
This library contains the core functions for programming with STM.
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.
anonymous enum |
Reason for aborting (returned by sigsetjmp() upon transaction restart).
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).
int stm_aborted | ( | ) |
Check if the current transaction has aborted.
int stm_active | ( | ) |
Check if the current transaction is still active.
int stm_commit | ( | ) |
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).
int stm_create_specific | ( | ) |
Create a key to associate application-specific data to the current thread/transaction.
This mechanism can be combined with callbacks to write modules.
void stm_exit | ( | ) |
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 | ( | ) |
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 | ( | ) |
Get attributes associated with the current transactions, if any.
These attributes were passed as parameters when starting the transaction.
stm_word_t stm_get_clock | ( | ) |
Read the current value of the global clock (used for timestamps).
This function is useful when programming with unit loads and stores.
sigjmp_buf* stm_get_env | ( | ) |
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().
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.
name | Name of the parameter. | |
val | Pointer to the variable that should hold the value of the parameter. |
void* stm_get_specific | ( | int | key | ) |
Get application-specific data associated to the current thread/transaction and a given key.
key | Key designating the data to read. |
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.
name | Name of the statistics. | |
val | Pointer to the variable that should hold the value of the statistics. |
void stm_init | ( | ) |
Initialize the STM library.
This function must be called once, from the main thread, before any access to the other functions of the library.
void stm_init_thread | ( | ) |
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 | ( | ) |
Check if the current transaction is still active and in irrevocable state.
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.
addr | Address of the memory location. |
int stm_register | ( | void(*)(void *arg) | on_thread_init, | |
void(*)(void *arg) | on_thread_exit, | |||
void(*)(void *arg) | on_start, | |||
void(*)(void *arg) | on_commit, | |||
void(*)(void *arg) | on_abort, | |||
void * | arg | |||
) |
Register application-specific callbacks that are triggered each time particular events occur.
on_thread_init | Function called upon initialization of a transactional thread. | |
on_thread_exit | Function called upon cleanup of a transactional thread. | |
on_start | Function called upon start of a transaction. | |
on_commit | Function called upon successful transaction commit. | |
on_abort | Function called upon transaction abort. | |
arg | Parameter to be passed to the callback functions. |
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.
enable | True (non-zero) to enable snapshot extensions, false (zero) to disable them. | |
timestamp | If 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 irrevokable 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).
enable | True (non-zero) for serial-irrevocable mode (no transaction can execute concurrently), false for parallel-irrevocable mode. |
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.
name | Name of the parameter. | |
val | Pointer to a variable that holds the new value of the parameter. |
void stm_set_specific | ( | int | key, | |
void * | data | |||
) |
Set application-specific data associated to the current thread/transaction and a given key.
key | Key designating the data to read. | |
data | Data to store under the given key. |
sigjmp_buf* stm_start | ( | stm_tx_attr_t * | attr | ) |
Start a transaction.
attr | Specifies optional attributes associated to the transaction. If null, the transaction uses default attributes. |
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.
addr | Address of the memory location. | |
value | Value 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.
addr | Address of the memory location. | |
value | Value to be written. | |
mask | Mask 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.
addr | Address of the memory location. | |
timestamp | If non-null, the referenced variable is updated to hold the timestamp of the memory location being read. |
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.
addr | Address of the memory location. | |
value | Value to be written. | |
timestamp | If 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. |
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.
addr | Address of the memory location. | |
value | Value to be written. | |
mask | Mask specifying the bits to be written. | |
timestamp | If 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. |