Getting Started

Building

Prerequisites:

• Intel C/C++ STM Compiler, Prototype Edition 3.0
• SCons: A software construction tool

To build xCalls, first check out a copy with SVN. If you have commit access:

% svn co --username username https://xcalls.googlecode.com/svn/trunk $XCALLS

For anonymous checkout:

% svn co https://xcalls.googlecode.com/svn/trunk $XCALLS

then open file $XCALLS/SConstruct with your favorite editor and set the environment variable CC to point to the Intel C Compiler (icc):

env['CC'] = '/path/to/intel/c/compiler/icc'

and finally build xCalls:

% cd $XCALLS
% scons

All generated objects and binaries are placed under $XCALLS/build.

You may then install the library into the location of your choice $INSTALL_DIR:

% scons install prefix=$INSTALL_DIR

Build configuration

You may configure the build process using the following Scons parameters:

• test=(yes|no): Run unit tests.
• select_test=TEST: Run just test suite TEST instead of all tests.
• ubench=(yes|no): Build library performance microbenchmarks.
• mode=(debug|release): Set library type.
• linkage=(static|dynamic): Set library linkage.
• tm_system=(itm|logtm): Set transactional memory system.
• stats=(yes|no): Build library with statistics support.
• prefix=INSTALL_DIR: Install library into INSTALL_DIR

Test Suite

xCalls includes an extensive unit test suite which may be invoked by running 'scons test=yesk' in xCalls' root directory. Running 'scons test=yes select_test=TEST' runs just the single unit test suite TEST instead of all the unit tests.

Using xCalls

The following example demonstrates the major points of xCalls. Function create_file_with_header atomically creates a file and writes a header with a generation ID. The generation ID is kept in the shared variable generation.

#include <txc/txc.h>

volatile int *generation;

int create_file_with_header(char *path, char *header, int header_len)
        int err;
        int fd;

        _TXC_global_init()); 
        _TXC_thread_init()); 

        XACT_BEGIN(xact_create_file)
                _TXC_fm_register(TXC_FM_NO_RETRY, &err);
                fd = _TXC_x_create(path, S_IRUSR|S_IWUSR, &err);
                generation++;
                _TXC_x_write(fd, header, header_len, &err);
                _TXC_x_write(fd, num_creations, sizeof(int), &err);
                _TXC_x_close(fd, NULL);
        XACT_END(xact_undo_action1)

        if (err) {
                _TXC_x_unlink(path, NULL);
                __tm_atomic {
                        generation--;
                }
                return -1;
        }

        return 0;
}       

When compiling a program using xCalls, you should include the public header file <txc/txc.h> which is located under $XCALLS/src/inc. Please make sure that this directory is present in your preprocessor's search path. Please also make sure that if you use the shared library, the library's directory is searched by the dynamic linker. If the library is not located in a standard directory, then you can set the LD_LIBRARY_PATH environment variable with the directory containing the xCalls library.

Before using xCalls, you must properly initialize the library:

• _TXC_global_init performs global library initialization and has to be called once by any thread of the program. While this function is idempotent, multiple calls are not recommended to avoid paying unnecessary call overheads. It is recommended that this function is called once by the main routine of your program.
• _TXC_thread_init performs thread initialization and has to be called once before a thread invokes an xCall. This function is also idempotent, so even if multiple calls are not recommended, they do not break correctness. It is recommended that this function is called once by the start routine of the thread.

To begin and end an xCalls aware transaction, one has to use the MACROs XACT_BEGIN and XACT_END respectively. The use of these MACROs has to be lexically scoped.

The last argument of all xCalls is a pointer to a memory location where the error code of an asynchronous failure should be stored. An asynchronous failure is one that happens during abort or commit. In our example, we pass a pointer to the local variable &err. To simplify error recovery we use _TXC_fm_register to request that the transaction is not retried in case of an asynchronous failure. This allows us to recover from the error by simply removing the file and restoring the counter to its initial value by decrementing it by one.

Source Code Structure

The xCalls library is implemented in C.

• $STASIS/src: The xCalls library source tree.
• $STASIS/src/inc: The xCalls library public header files.
• $STASIS/src/core: The library's core functionality.
• $STASIS/src/libc: Transactional versions of some C library functions we found useful in our workloads.
• $STASIS/src/misc: Some helper functions such as pool allocator, debugging facilities, hash table.
• $STASIS/src/tm: Transactional memory system backends.
• $STASIS/src/xcalls: xCalls API implementation.

---