Files | Macros | Enumerations | Functions
The Transactional Memory Module

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

Files

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.
 

Macros

#define PICOTM_TM_LOAD_TX(__name, __type)
 
#define PICOTM_TM_PRIVATIZE_LOADSTORE
 
#define PICOTM_TM_PRIVATIZE_TX(__name, __type)
 
#define PICOTM_TM_STORE_TX(__name, __type)
 

Enumerations

enum  { PICOTM_TM_PRIVATIZE_LOAD, PICOTM_TM_PRIVATIZE_STORE }
 

Functions

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)
 

Detailed Description

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.

int x;
int x_tx;
load_tx(&x, &x_tx, sizeof(x));
// The value of 'x' is now stored in 'x_tx'.

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

int x;
int x_tx;
store_tx(&x, &x_tx, sizeof(x));
// The value of 'x_tx' will be committed into 'x'.

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.

int x;
int x_tx = load_int_tx(&x);
// The value of 'x' is now stored in 'x_tx'.
store_int_tx(&x, x_tx);
// The value of 'x_tx' will be committed into 'x'.

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

// An application-specific type
typedef unsigned int my_int_type;
// Define load_my_int_type_tx()
PICOTM_TM_LOAD_TX(my_int_type, my_int_type);
// Define store_my_int_type_tx()
PICOTM_TM_STORE_TX(my_int_type, 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.

int* x_ptr;
int* x_ptr_tx = load_ptr_tx(&x_ptr);
// The value of 'x_ptr' is now stored in 'x_ptr_tx'.
store_ptr_tx(&x_ptr, &x_ptr_tx);
// The value of 'x_ptr_tx' will be committed into 'x_ptr'.

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.

int x;
// The memory location of 'x' is now available within the transaction.
// Changes to 'x' will be committed into the memory location of 'x'.

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

char* str = "foo";
// The string at 'str' is now available within the transaction.
// Changes to 'str' will be committed into the string at 'str'.

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];
loadstore_tx(ibuf, obuf, sizeof(obuf));
// The data in 'ibuf' will be committed into the memory of 'obuf'.

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.

Macro Definition Documentation

◆ 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
__nameThe name of the type.
__typeThe 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
__nameThe name of the type.
__typeThe 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
__nameThe name of the type.
__typeThe C type.

Enumeration Type Documentation

◆ anonymous enum

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.

Function Documentation

◆ load__Bool_tx()

static _Bool load__Bool_tx ( const _Bool *  addr)
inlinestatic

Loads a value of type ' _Bool ' with transactional semantics.

Parameters
addrThe source address.
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
addrThe source address.
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
addrThe source address.
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
addrThe source address.
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
addrThe source address.
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
addrThe source address.
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
addrThe source address.
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
addrThe source address.
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
addrThe 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
addrThe source address.
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
addrThe source address.
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
addrThe address to load from.
bufThe transaction-local buffer to store the loaded value in.
sizThe 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
addrThe source address.
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
addrThe source address.
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
addrThe source address.
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
addrThe source address.
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
addrThe source address.
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
laddrThe address of the source region.
saddrThe address of the destination region.
sizThe 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
addrThe address to privatize.
flagsPrivatizes 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
addrThe address to privatize.
cThe region's terminating character.
flagsPrivatizes 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
addrThe address to privatize.
flagsPrivatizes 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
addrThe address to privatize.
flagsPrivatizes 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
addrThe address to privatize.
flagsPrivatizes 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
addrThe address to privatize.
flagsPrivatizes 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
addrThe address to privatize.
flagsPrivatizes 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
addrThe address to privatize.
flagsPrivatizes 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
addrThe address to privatize.
flagsPrivatizes 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
addrThe address to privatize.
flagsPrivatizes 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
addrThe address to privatize.
flagsPrivatizes 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
addrThe address to privatize.
sizThe number of bytes to privatize.
flagsPrivatizes 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
addrThe address to privatize.
flagsPrivatizes 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
addrThe address to privatize.
flagsPrivatizes 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
addrThe address to privatize.
flagsPrivatizes 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
addrThe address to privatize.
flagsPrivatizes 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
addrThe address to privatize.
flagsPrivatizes 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
addrThe destination address.
valueThe 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
addrThe destination address.
valueThe 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
addrThe destination address.
valueThe 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
addrThe destination address.
valueThe 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
addrThe destination address.
valueThe 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
addrThe destination address.
valueThe 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
addrThe destination address.
valueThe 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
addrThe destination address.
valueThe 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
addrThe address to store to.
ptrThe 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
addrThe destination address.
valueThe 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
addrThe destination address.
valueThe 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
addrThe address to store to.
bufThe transaction-local buffer to load the loaded value from.
sizThe 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
addrThe destination address.
valueThe 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
addrThe destination address.
valueThe 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
addrThe destination address.
valueThe 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
addrThe destination address.
valueThe 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
addrThe destination address.
valueThe value to store at 'addr'.