stm.h File Reference

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_tstm_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.

Detailed Description

STM functions.

This library contains the core functions for programming with STM.

Author:
Pascal Felber <pascal.felber@unine.ch>
Date:
2007-2009

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_ABORT_EXPLICIT 

Abort due to explicit call from the programmer (no retry).

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_RO_WRITE 

Abort upon write from a transaction declared as read-only.

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

int stm_aborted (  ) 

Check if the current transaction has aborted.

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

Check if the current transaction is still active.

Returns:
True (non-zero) if the transaction is active, false (zero) otherwise.
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).

Returns:
1 upon success, 0 otherwise.
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.

Returns:
The new key.
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.

Returns:
Attributes associated with the current transaction, or NULL if no attributes were specified 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.

Returns:
Value of the global clock.
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().

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:
name Name of the parameter.
val Pointer 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:
key Key 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:
name Name of the statistics.
val Pointer to the variable that should hold the value of the statistics.
Returns:
1 upon success, 0 otherwise.
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.

Returns:
True (non-zero) if the transaction is active and irrevocable, 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:
addr Address 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_commit,
void(*)(void *arg)  on_abort,
void *  arg 
)

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

Parameters:
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.
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:
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).

Parameters:
enable True (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:
name Name of the parameter.
val Pointer 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:
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.

Parameters:
attr Specifies optional attributes associated to the transaction. 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:
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.

Parameters:
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.

Parameters:
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.
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:
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.
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:
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.
Returns:
1 if value has been written, 0 otherwise.
Generated on Mon Feb 22 15:49:59 2010 for TinySTM by  doxygen 1.6.3