TinySTM
1.0.5
|
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) |
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).
abort_reason | Reason for aborting the transaction. |
int stm_aborted | ( | void | ) |
Check if the current transaction has aborted.
int stm_active | ( | void | ) |
Check if the current transaction is still active.
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).
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.
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.
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.
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().
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 | ( | 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.
int stm_killed | ( | void | ) |
Check if the current transaction has been killed.
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_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.
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_precommit | Function called before transaction try to commit. |
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 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).
serial | 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. Attributes are copied in transaction-local storage. 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. |