The Transactional Memory module provides transactional semantics when accessing main memory. You can load and store variables in main memory, or adopt memory regions into a transactions.
More...
|
file | picotm-tm-ctypes.h |
| Provides Transactional Memory operations for native C types.
|
|
file | picotm-tm.h |
| Public interfaces of picotm's Transactional Memory module.
|
|
|
static _Bool | load__Bool_tx (const _Bool *addr) |
|
static char | load_char_tx (const char *addr) |
|
static double | load_double_tx (const double *addr) |
|
static float | load_float_tx (const float *addr) |
|
static int | load_int_tx (const int *addr) |
|
static long double | load_ldouble_tx (const long double *addr) |
|
static long long | load_llong_tx (const long long *addr) |
|
static long | load_long_tx (const long *addr) |
|
static void * | load_ptr_tx (const void *addr) |
|
static signed char | load_schar_tx (const signed char *addr) |
|
static short | load_short_tx (const short *addr) |
|
static void | load_tx (const void *addr, void *buf, size_t siz) |
|
static unsigned char | load_uchar_tx (const unsigned char *addr) |
|
static unsigned int | load_uint_tx (const unsigned int *addr) |
|
static unsigned long long | load_ullong_tx (const unsigned long long *addr) |
|
static unsigned long | load_ulong_tx (const unsigned long *addr) |
|
static unsigned short | load_ushort_tx (const unsigned short *addr) |
|
static void | loadstore_tx (const void *laddr, void *saddr, size_t siz) |
|
static void | privatize__Bool_tx (const _Bool *addr, unsigned long flags) |
|
static void | privatize_c_tx (const void *addr, int c, unsigned long flags) |
|
static void | privatize_char_tx (const char *addr, unsigned long flags) |
|
static void | privatize_double_tx (const double *addr, unsigned long flags) |
|
static void | privatize_float_tx (const float *addr, unsigned long flags) |
|
static void | privatize_int_tx (const int *addr, unsigned long flags) |
|
static void | privatize_ldouble_tx (const long double *addr, unsigned long flags) |
|
static void | privatize_llong_tx (const long long *addr, unsigned long flags) |
|
static void | privatize_long_tx (const long *addr, unsigned long flags) |
|
static void | privatize_schar_tx (const signed char *addr, unsigned long flags) |
|
static void | privatize_short_tx (const short *addr, unsigned long flags) |
|
static void | privatize_tx (const void *addr, size_t siz, unsigned long flags) |
|
static void | privatize_uchar_tx (const unsigned char *addr, unsigned long flags) |
|
static void | privatize_uint_tx (const unsigned int *addr, unsigned long flags) |
|
static void | privatize_ullong_tx (const unsigned long long *addr, unsigned long flags) |
|
static void | privatize_ulong_tx (const unsigned long *addr, unsigned long flags) |
|
static void | privatize_ushort_tx (const unsigned short *addr, unsigned long flags) |
|
static void | store__Bool_tx (_Bool *addr, _Bool value) |
|
static void | store_char_tx (char *addr, char value) |
|
static void | store_double_tx (double *addr, double value) |
|
static void | store_float_tx (float *addr, float value) |
|
static void | store_int_tx (int *addr, int value) |
|
static void | store_ldouble_tx (long double *addr, long double value) |
|
static void | store_llong_tx (long long *addr, long long value) |
|
static void | store_long_tx (long *addr, long value) |
|
static void | store_ptr_tx (void *addr, const void *ptr) |
|
static void | store_schar_tx (signed char *addr, signed char value) |
|
static void | store_short_tx (short *addr, short value) |
|
static void | store_tx (void *addr, const void *buf, size_t siz) |
|
static void | store_uchar_tx (unsigned char *addr, unsigned char value) |
|
static void | store_uint_tx (unsigned int *addr, unsigned int value) |
|
static void | store_ullong_tx (unsigned long long *addr, unsigned long long value) |
|
static void | store_ulong_tx (unsigned long *addr, unsigned long value) |
|
static void | store_ushort_tx (unsigned short *addr, unsigned short value) |
|
The Transactional Memory module provides load and store operations for main memory. In order to avoid conflicting access to shared memory locations, picotm has to know which transaction uses which locations. The Transactional Memory module maintains these information.
A call to load_tx()
copies a memory location's value into a transaction, as illustrated in the example below.
This copies the value of x
into our transaction's variable x_tx
and puts the memory location of x
under control of the transaction manager. We are free to change the value of x_tx
at will, since it's transaction local. If we change it, the original non-transactional value in x
remains unchanged.
In a similarly way we store a copy of a transactional variable in a memory location. This is done with store_tx()
.
As with all transactional modifications, the store will not be executed immediately, but only become permanent after the transaction successfully committed.
We don't have to deal with all these addresses ourselves. The TM module comes with helper functions for the basic C types. With load_int_tx()
and store_int_tx()
we can rewrite the example transactions as shown below.
Besides load_int_tx()
and store_int_tx()
, the Transactional Memory module provides similar functions for the basic C types. Each is defined via the macros PICOTM_TM_LOAD_TX()
and PICOTM_TM_STORE_TX()
. We can use these macros to define load and store functions for our application's data types. Both macros expand to inline C functions, so we don't loose performance compared to load_tx()
and store_tx()
.
typedef unsigned int my_int_type;
Since address and pointer handling can be tricky, there are also helpers for loading and storing pointers. These functions load and store the address stored in a pointer variable, but not the value stored at that address.
Loads and stores always copy values into or out of a transaction. There are cases where we don't want a copy, but the exact memory location of a value. This is called privatization. For example, the function memcpy()
loads and stores an indefinite amount of data between memory buffers. The actual buffer size is often not known in advance. It would be wasteful to first load the data into a transaction-local buffer and then further store it in another buffer.
The functions privatize_tx()
and privatize_c_tx()
offer privatization of memory locations.
This privatizes x
for transactional access from within the transaction. The number of bytes is given in the second argument. The flags argument is a bitmask of PICOTM_TM_PRIVATIZE_LOAD
and PICOTM_TM_PRIVATIZE_STORE
. These flags control how picotm handles the memory location. If we only privatized a memory location for loading or storing, we may never invoke the other operation. Setting no flags at all will discard the memory location. This signals to other transactions that the memory is invalid and to be freed.
There can be cases where we don't know in advance how large in size the privatized buffer is going to be. For example, if we privatize a C string, the length is not explicitly stored in the string, but given by the location of the terminating \0
character. To privatize a memory region up to and including a specific character, there is privatize_c_tx()
.
Using privatize_c_tx()
with strings is the most common use case, but arbitrary characters are possible.
Finally, there is loadstore_tx()
. Even through the name suggests load-and-store, the function is a mixture of load, store and privatization. It privatizes an input buffer for loading and an output buffer for storing, and copies the input buffer's content into the output buffer.
int ibuf[20];
int obuf[20];
A call to loadstore_tx()
is like a call to memcpy()
that privatizes its input buffers. It's an optimization for platform without transactional C library.
◆ PICOTM_TM_LOAD_TX
#define PICOTM_TM_LOAD_TX |
( |
|
__name, |
|
|
|
__type |
|
) |
| |
Defines a C function for conveniently loading a value of a specific type into a transaction. The helper function's name is load_<__name>_tx.
- Parameters
-
__name | The name of the type. |
__type | The C type. |
◆ PICOTM_TM_PRIVATIZE_LOADSTORE
#define PICOTM_TM_PRIVATIZE_LOADSTORE |
Privatizes a memory region for loading and storing.
◆ PICOTM_TM_PRIVATIZE_TX
#define PICOTM_TM_PRIVATIZE_TX |
( |
|
__name, |
|
|
|
__type |
|
) |
| |
Defines a C function for conveniently privatizing a value of a specific type into a transaction. The helper function's name is store_<__name>_tx.
- Parameters
-
__name | The name of the type. |
__type | The C type. |
◆ PICOTM_TM_STORE_TX
#define PICOTM_TM_STORE_TX |
( |
|
__name, |
|
|
|
__type |
|
) |
| |
Defines a C function for conveniently storing a value of a specific type into a transaction. The helper function's name is store_<__name>_tx.
- Parameters
-
__name | The name of the type. |
__type | The C type. |
◆ anonymous enum
Flags for memory privatizations.
Enumerator |
---|
PICOTM_TM_PRIVATIZE_LOAD | Privatizes a memory region for loading.
|
PICOTM_TM_PRIVATIZE_STORE | Privatizes a memory region for storing.
|
◆ load__Bool_tx()
static _Bool load__Bool_tx |
( |
const _Bool * |
addr | ) |
|
|
inlinestatic |
Loads a value of type ' _Bool ' with transactional semantics.
- Parameters
-
- Returns
- The transaction-local value loaded from address 'addr'.
◆ load_char_tx()
static char load_char_tx |
( |
const char * |
addr | ) |
|
|
inlinestatic |
Loads a value of type ' char ' with transactional semantics.
- Parameters
-
- Returns
- The transaction-local value loaded from address 'addr'.
◆ load_double_tx()
static double load_double_tx |
( |
const double * |
addr | ) |
|
|
inlinestatic |
Loads a value of type ' double ' with transactional semantics.
- Parameters
-
- Returns
- The transaction-local value loaded from address 'addr'.
◆ load_float_tx()
static float load_float_tx |
( |
const float * |
addr | ) |
|
|
inlinestatic |
Loads a value of type ' float ' with transactional semantics.
- Parameters
-
- Returns
- The transaction-local value loaded from address 'addr'.
◆ load_int_tx()
static int load_int_tx |
( |
const int * |
addr | ) |
|
|
inlinestatic |
Loads a value of type ' int ' with transactional semantics.
- Parameters
-
- Returns
- The transaction-local value loaded from address 'addr'.
◆ load_ldouble_tx()
static long double load_ldouble_tx |
( |
const long double * |
addr | ) |
|
|
inlinestatic |
Loads a value of type ' long double ' with transactional semantics.
- Parameters
-
- Returns
- The transaction-local value loaded from address 'addr'.
◆ load_llong_tx()
static long long load_llong_tx |
( |
const long long * |
addr | ) |
|
|
inlinestatic |
Loads a value of type ' long long ' with transactional semantics.
- Parameters
-
- Returns
- The transaction-local value loaded from address 'addr'.
◆ load_long_tx()
static long load_long_tx |
( |
const long * |
addr | ) |
|
|
inlinestatic |
Loads a value of type ' long ' with transactional semantics.
- Parameters
-
- Returns
- The transaction-local value loaded from address 'addr'.
◆ load_ptr_tx()
static void* load_ptr_tx |
( |
const void * |
addr | ) |
|
|
inlinestatic |
Loads a pointer with transactional semantics.
- Parameters
-
addr | The address to load from. |
- Returns
- The transaction-local pointer.
◆ load_schar_tx()
static signed char load_schar_tx |
( |
const signed char * |
addr | ) |
|
|
inlinestatic |
Loads a value of type ' signed char ' with transactional semantics.
- Parameters
-
- Returns
- The transaction-local value loaded from address 'addr'.
◆ load_short_tx()
static short load_short_tx |
( |
const short * |
addr | ) |
|
|
inlinestatic |
Loads a value of type ' short ' with transactional semantics.
- Parameters
-
- Returns
- The transaction-local value loaded from address 'addr'.
◆ load_tx()
static void load_tx |
( |
const void * |
addr, |
|
|
void * |
buf, |
|
|
size_t |
siz |
|
) |
| |
|
inlinestatic |
Loads the memory at address into a buffer.
- Parameters
-
addr | The address to load from. |
buf | The transaction-local buffer to store the loaded value in. |
siz | The number of bytes to load. |
◆ load_uchar_tx()
static unsigned char load_uchar_tx |
( |
const unsigned char * |
addr | ) |
|
|
inlinestatic |
Loads a value of type ' unsigned char ' with transactional semantics.
- Parameters
-
- Returns
- The transaction-local value loaded from address 'addr'.
◆ load_uint_tx()
static unsigned int load_uint_tx |
( |
const unsigned int * |
addr | ) |
|
|
inlinestatic |
Loads a value of type ' unsigned int ' with transactional semantics.
- Parameters
-
- Returns
- The transaction-local value loaded from address 'addr'.
◆ load_ullong_tx()
static unsigned long long load_ullong_tx |
( |
const unsigned long long * |
addr | ) |
|
|
inlinestatic |
Loads a value of type ' unsigned long long ' with transactional semantics.
- Parameters
-
- Returns
- The transaction-local value loaded from address 'addr'.
◆ load_ulong_tx()
static unsigned long load_ulong_tx |
( |
const unsigned long * |
addr | ) |
|
|
inlinestatic |
Loads a value of type ' unsigned long ' with transactional semantics.
- Parameters
-
- Returns
- The transaction-local value loaded from address 'addr'.
◆ load_ushort_tx()
static unsigned short load_ushort_tx |
( |
const unsigned short * |
addr | ) |
|
|
inlinestatic |
Loads a value of type ' unsigned short ' with transactional semantics.
- Parameters
-
- Returns
- The transaction-local value loaded from address 'addr'.
◆ loadstore_tx()
static void loadstore_tx |
( |
const void * |
laddr, |
|
|
void * |
saddr, |
|
|
size_t |
siz |
|
) |
| |
|
inlinestatic |
Copies data between non-transactional memory regions.
- Parameters
-
laddr | The address of the source region. |
saddr | The address of the destination region. |
siz | The number of bytes ot copy. |
◆ privatize__Bool_tx()
static void privatize__Bool_tx |
( |
const _Bool * |
addr, |
|
|
unsigned long |
flags |
|
) |
| |
|
inlinestatic |
Privatizes a value of type ' _Bool '.
- Parameters
-
addr | The address to privatize.
|
flags | Privatizes for loading and/or storing. Not setting flags discards the buffer. |
◆ privatize_c_tx()
static void privatize_c_tx |
( |
const void * |
addr, |
|
|
int |
c, |
|
|
unsigned long |
flags |
|
) |
| |
|
inlinestatic |
Privatizes the memory region starting at address, ending at character 'c'.
- Parameters
-
addr | The address to privatize. |
c | The region's terminating character. |
flags | Privatizes for loading and/or storing. Not setting flags discards the buffer. |
◆ privatize_char_tx()
static void privatize_char_tx |
( |
const char * |
addr, |
|
|
unsigned long |
flags |
|
) |
| |
|
inlinestatic |
Privatizes a value of type ' char '.
- Parameters
-
addr | The address to privatize.
|
flags | Privatizes for loading and/or storing. Not setting flags discards the buffer. |
◆ privatize_double_tx()
static void privatize_double_tx |
( |
const double * |
addr, |
|
|
unsigned long |
flags |
|
) |
| |
|
inlinestatic |
Privatizes a value of type ' double '.
- Parameters
-
addr | The address to privatize.
|
flags | Privatizes for loading and/or storing. Not setting flags discards the buffer. |
◆ privatize_float_tx()
static void privatize_float_tx |
( |
const float * |
addr, |
|
|
unsigned long |
flags |
|
) |
| |
|
inlinestatic |
Privatizes a value of type ' float '.
- Parameters
-
addr | The address to privatize.
|
flags | Privatizes for loading and/or storing. Not setting flags discards the buffer. |
◆ privatize_int_tx()
static void privatize_int_tx |
( |
const int * |
addr, |
|
|
unsigned long |
flags |
|
) |
| |
|
inlinestatic |
Privatizes a value of type ' int '.
- Parameters
-
addr | The address to privatize.
|
flags | Privatizes for loading and/or storing. Not setting flags discards the buffer. |
◆ privatize_ldouble_tx()
static void privatize_ldouble_tx |
( |
const long double * |
addr, |
|
|
unsigned long |
flags |
|
) |
| |
|
inlinestatic |
Privatizes a value of type ' long double '.
- Parameters
-
addr | The address to privatize.
|
flags | Privatizes for loading and/or storing. Not setting flags discards the buffer. |
◆ privatize_llong_tx()
static void privatize_llong_tx |
( |
const long long * |
addr, |
|
|
unsigned long |
flags |
|
) |
| |
|
inlinestatic |
Privatizes a value of type ' long long '.
- Parameters
-
addr | The address to privatize.
|
flags | Privatizes for loading and/or storing. Not setting flags discards the buffer. |
◆ privatize_long_tx()
static void privatize_long_tx |
( |
const long * |
addr, |
|
|
unsigned long |
flags |
|
) |
| |
|
inlinestatic |
Privatizes a value of type ' long '.
- Parameters
-
addr | The address to privatize.
|
flags | Privatizes for loading and/or storing. Not setting flags discards the buffer. |
◆ privatize_schar_tx()
static void privatize_schar_tx |
( |
const signed char * |
addr, |
|
|
unsigned long |
flags |
|
) |
| |
|
inlinestatic |
Privatizes a value of type ' signed char '.
- Parameters
-
addr | The address to privatize.
|
flags | Privatizes for loading and/or storing. Not setting flags discards the buffer. |
◆ privatize_short_tx()
static void privatize_short_tx |
( |
const short * |
addr, |
|
|
unsigned long |
flags |
|
) |
| |
|
inlinestatic |
Privatizes a value of type ' short '.
- Parameters
-
addr | The address to privatize.
|
flags | Privatizes for loading and/or storing. Not setting flags discards the buffer. |
◆ privatize_tx()
static void privatize_tx |
( |
const void * |
addr, |
|
|
size_t |
siz, |
|
|
unsigned long |
flags |
|
) |
| |
|
inlinestatic |
Privatizes the memory region starting at address.
- Parameters
-
addr | The address to privatize. |
siz | The number of bytes to privatize. |
flags | Privatizes for loading and/or storing. Not setting flags discards the buffer. |
◆ privatize_uchar_tx()
static void privatize_uchar_tx |
( |
const unsigned char * |
addr, |
|
|
unsigned long |
flags |
|
) |
| |
|
inlinestatic |
Privatizes a value of type ' unsigned char '.
- Parameters
-
addr | The address to privatize.
|
flags | Privatizes for loading and/or storing. Not setting flags discards the buffer. |
◆ privatize_uint_tx()
static void privatize_uint_tx |
( |
const unsigned int * |
addr, |
|
|
unsigned long |
flags |
|
) |
| |
|
inlinestatic |
Privatizes a value of type ' unsigned int '.
- Parameters
-
addr | The address to privatize.
|
flags | Privatizes for loading and/or storing. Not setting flags discards the buffer. |
◆ privatize_ullong_tx()
static void privatize_ullong_tx |
( |
const unsigned long long * |
addr, |
|
|
unsigned long |
flags |
|
) |
| |
|
inlinestatic |
Privatizes a value of type ' unsigned long long '.
- Parameters
-
addr | The address to privatize.
|
flags | Privatizes for loading and/or storing. Not setting flags discards the buffer. |
◆ privatize_ulong_tx()
static void privatize_ulong_tx |
( |
const unsigned long * |
addr, |
|
|
unsigned long |
flags |
|
) |
| |
|
inlinestatic |
Privatizes a value of type ' unsigned long '.
- Parameters
-
addr | The address to privatize.
|
flags | Privatizes for loading and/or storing. Not setting flags discards the buffer. |
◆ privatize_ushort_tx()
static void privatize_ushort_tx |
( |
const unsigned short * |
addr, |
|
|
unsigned long |
flags |
|
) |
| |
|
inlinestatic |
Privatizes a value of type ' unsigned short '.
- Parameters
-
addr | The address to privatize.
|
flags | Privatizes for loading and/or storing. Not setting flags discards the buffer. |
◆ store__Bool_tx()
static void store__Bool_tx |
( |
_Bool * |
addr, |
|
|
_Bool |
value |
|
) |
| |
|
inlinestatic |
Stores a value of type ' _Bool ' with transactional semantics.
- Parameters
-
addr | The destination address. |
value | The value to store at 'addr'. |
◆ store_char_tx()
static void store_char_tx |
( |
char * |
addr, |
|
|
char |
value |
|
) |
| |
|
inlinestatic |
Stores a value of type ' char ' with transactional semantics.
- Parameters
-
addr | The destination address. |
value | The value to store at 'addr'. |
◆ store_double_tx()
static void store_double_tx |
( |
double * |
addr, |
|
|
double |
value |
|
) |
| |
|
inlinestatic |
Stores a value of type ' double ' with transactional semantics.
- Parameters
-
addr | The destination address. |
value | The value to store at 'addr'. |
◆ store_float_tx()
static void store_float_tx |
( |
float * |
addr, |
|
|
float |
value |
|
) |
| |
|
inlinestatic |
Stores a value of type ' float ' with transactional semantics.
- Parameters
-
addr | The destination address. |
value | The value to store at 'addr'. |
◆ store_int_tx()
static void store_int_tx |
( |
int * |
addr, |
|
|
int |
value |
|
) |
| |
|
inlinestatic |
Stores a value of type ' int ' with transactional semantics.
- Parameters
-
addr | The destination address. |
value | The value to store at 'addr'. |
◆ store_ldouble_tx()
static void store_ldouble_tx |
( |
long double * |
addr, |
|
|
long double |
value |
|
) |
| |
|
inlinestatic |
Stores a value of type ' long double ' with transactional semantics.
- Parameters
-
addr | The destination address. |
value | The value to store at 'addr'. |
◆ store_llong_tx()
static void store_llong_tx |
( |
long long * |
addr, |
|
|
long long |
value |
|
) |
| |
|
inlinestatic |
Stores a value of type ' long long ' with transactional semantics.
- Parameters
-
addr | The destination address. |
value | The value to store at 'addr'. |
◆ store_long_tx()
static void store_long_tx |
( |
long * |
addr, |
|
|
long |
value |
|
) |
| |
|
inlinestatic |
Stores a value of type ' long ' with transactional semantics.
- Parameters
-
addr | The destination address. |
value | The value to store at 'addr'. |
◆ store_ptr_tx()
static void store_ptr_tx |
( |
void * |
addr, |
|
|
const void * |
ptr |
|
) |
| |
|
inlinestatic |
Stores the pointer in memory.
- Parameters
-
addr | The address to store to. |
ptr | The pointer value to store. |
◆ store_schar_tx()
static void store_schar_tx |
( |
signed char * |
addr, |
|
|
signed char |
value |
|
) |
| |
|
inlinestatic |
Stores a value of type ' signed char ' with transactional semantics.
- Parameters
-
addr | The destination address. |
value | The value to store at 'addr'. |
◆ store_short_tx()
static void store_short_tx |
( |
short * |
addr, |
|
|
short |
value |
|
) |
| |
|
inlinestatic |
Stores a value of type ' short ' with transactional semantics.
- Parameters
-
addr | The destination address. |
value | The value to store at 'addr'. |
◆ store_tx()
static void store_tx |
( |
void * |
addr, |
|
|
const void * |
buf, |
|
|
size_t |
siz |
|
) |
| |
|
inlinestatic |
Stores the buffer at address in memory.
- Parameters
-
addr | The address to store to. |
buf | The transaction-local buffer to load the loaded value from. |
siz | The number of bytes to store. |
◆ store_uchar_tx()
static void store_uchar_tx |
( |
unsigned char * |
addr, |
|
|
unsigned char |
value |
|
) |
| |
|
inlinestatic |
Stores a value of type ' unsigned char ' with transactional semantics.
- Parameters
-
addr | The destination address. |
value | The value to store at 'addr'. |
◆ store_uint_tx()
static void store_uint_tx |
( |
unsigned int * |
addr, |
|
|
unsigned int |
value |
|
) |
| |
|
inlinestatic |
Stores a value of type ' unsigned int ' with transactional semantics.
- Parameters
-
addr | The destination address. |
value | The value to store at 'addr'. |
◆ store_ullong_tx()
static void store_ullong_tx |
( |
unsigned long long * |
addr, |
|
|
unsigned long long |
value |
|
) |
| |
|
inlinestatic |
Stores a value of type ' unsigned long long ' with transactional semantics.
- Parameters
-
addr | The destination address. |
value | The value to store at 'addr'. |
◆ store_ulong_tx()
static void store_ulong_tx |
( |
unsigned long * |
addr, |
|
|
unsigned long |
value |
|
) |
| |
|
inlinestatic |
Stores a value of type ' unsigned long ' with transactional semantics.
- Parameters
-
addr | The destination address. |
value | The value to store at 'addr'. |
◆ store_ushort_tx()
static void store_ushort_tx |
( |
unsigned short * |
addr, |
|
|
unsigned short |
value |
|
) |
| |
|
inlinestatic |
Stores a value of type ' unsigned short ' with transactional semantics.
- Parameters
-
addr | The destination address. |
value | The value to store at 'addr'. |