src/inc/txc/txc.h File Reference

xCalls' library public interface. More...

#include <sys/types.h>
#include <sys/stat.h>
#include <fcntl.h>
#include <xcalls/condvar/condvar.h>

Go to the source code of this file.

Defines
#define	TXC_FM_NO_RETRY   0x1
#define	__TXC_XSTR(s)   __TXC_STR(s)
#define	__TXC_STR(s)   #s
#define	SRCLOC_STR(file, line)   file ":" __TXC_XSTR(line)
#define	XACT_BEGIN(tag)
#define	XACT_END(tag)   }
#define	XACT_WAIVER   __tm_waiver
#define	XACT_ABORT(abortreason)   _TXC_transaction_abort(abortreason);
#define	TM_WAIVER   __attribute__ ((tm_pure))
#define	TM_PURE   __attribute__ ((tm_pure))
#define	TM_CALLABLE   __attribute__ ((tm_callable))
#define	XCALL_DEF(xcall)   _TXC_##xcall
#define	_XCALL(xcall)   _TXC_##xcall
Typedefs
typedef unsigned int	txc_result_t
Enumerations
enum	txc_tx_abortreason_t {   TXC_ABORTREASON_TMCONFLICT = 0, TXC_ABORTREASON_USERABORT = 1, TXC_ABORTREASON_USERRETRY = 2, TXC_ABORTREASON_BUSYSENTINEL = 4,   TXC_ABORTREASON_INCONSISTENCY = 8, TXC_ABORTREASON_BUSYTXLOCK = 16 }
enum	txc_tx_xactstate_t { TXC_XACTSTATE_NONTRANSACTIONAL = 0, TXC_XACTSTATE_TRANSACTIONAL_RETRYABLE = 1, TXC_XACTSTATE_TRANSACTIONAL_IRREVOCABLE = 2 }
Functions
TM_WAIVER int	_TXC_global_init ()
	Performs global initialization of the library.
TM_WAIVER int	_TXC_global_shutdown ()
	Shutdowns the library.
TM_WAIVER int	_TXC_thread_init ()
	Initializes and assigns an xCalls descriptor to a thread.
TM_WAIVER void	_TXC_transaction_abort (txc_tx_abortreason_t)
	Aborts a transaction.
TM_WAIVER txc_tx_xactstate_t	_TXC_get_xactstate ()
	Returns the transactional state of the current thread.
TM_WAIVER void	_TXC_transaction_pre_begin (const char *srcloc_str, const char *src_file, const char *src_fun, int src_line)
	Informs the xCall library that a transaction is going to begin.
TM_WAIVER int	_TXC_transaction_post_begin ()
	Informs the xCall library that a transaction has begun.
TM_WAIVER void	_TXC_fm_register (int flags, int *err)
	Specifies what action to take when an asynchronous failure occurs.
TM_WAIVER int XCALL_DEF()	x_close (int fildes, int *result)
	Closes a file descriptor.
TM_WAIVER int XCALL_DEF()	x_create (const char *, mode_t, int *)
	Creates a file.
TM_WAIVER int XCALL_DEF()	x_dup (int oldfd, int *result)
	Duplicates a file descriptor.
TM_WAIVER int XCALL_DEF()	x_fsync (int fildes, int *result)
	Synchronizes a file in-core state with storage device.
TM_WAIVER off_t XCALL_DEF()	x_lseek (int fd, off_t offset, int whence, int *result)
	Repositions read/write file offset.
TM_WAIVER int XCALL_DEF()	x_open (const char *pathname, int flags, mode_t mode, int *result)
	Opens a file.
TM_WAIVER int XCALL_DEF()	x_pipe (int fildes[2], int *result)
	Creates a pipe.
TM_WAIVER ssize_t XCALL_DEF()	x_printf (const char *format,...)
	Formatted output conversion.
TM_WAIVER int XCALL_DEF()	x_pthread_create (pthread_t *thread, const pthread_attr_t *attr, void *(*start_routine)(void *), void *arg, int *result)
	Creates a thread.
TM_WAIVER int XCALL_DEF()	x_pthread_mutex_init (pthread_mutex_t *mutex, const pthread_mutexattr_t *attr, int *result)
TM_WAIVER int XCALL_DEF()	x_pthread_mutex_lock (pthread_mutex_t *mutex, int *result)
	Locks a mutex.
TM_WAIVER int XCALL_DEF()	x_pthread_mutex_unlock (pthread_mutex_t *mutex, int *result)
	Unlocks a mutex.
TM_WAIVER ssize_t XCALL_DEF()	x_read (int fd, void *buf, size_t nbyte, int *result)
	Reads from a file.
TM_WAIVER ssize_t XCALL_DEF()	x_read_pipe (int fd, void *buf, size_t nbyte, int *result)
	Reads from a pipe.
TM_WAIVER ssize_t XCALL_DEF()	x_recvmsg (int s, struct msghdr *msg, int flags, int *result)
	Receives a message from a socket.
TM_WAIVER int XCALL_DEF()	x_rename (const char *oldpath, const char *newpath, int *result)
	Changes the name or location of a file.
TM_WAIVER int XCALL_DEF()	x_socket (int domain, int type, int protocol, int *result)
	Creates an endpoint for communication.
TM_WAIVER ssize_t XCALL_DEF()	x_sendmsg (int fd, const struct msghdr *msg, int flags, int *result)
	Sends a message to a socket.
TM_WAIVER ssize_t XCALL_DEF()	x_write_ovr (int fd, const void *buf, size_t nbyte, int *result)
	Writes to a file, while it saves any overwritten data.
TM_WAIVER ssize_t XCALL_DEF()	x_write_ovr_save (int fd, const void *buf, size_t nbyte, int *result)
	Alias of x_write_ovr.
TM_WAIVER ssize_t XCALL_DEF()	x_write_ovr_ignore (int fd, const void *buf, size_t nbyte, int *result)
	Writes to a file without saving any overwritten data.
TM_WAIVER ssize_t XCALL_DEF()	x_write_pipe (int fd, const void *buf, size_t nbyte, int *result)
	Writes to a pipe.
TM_WAIVER ssize_t XCALL_DEF()	x_write_seq (int fd, const void *buf, size_t nbyte, int *result)
	Write appends to a file.
TM_WAIVER int XCALL_DEF()	x_unlink (const char *pathname, int *result)
	Deletes a name and possibly the file it refers to.

---

Detailed Description

xCalls' library public interface.

This is the public header file to be included by any application using xCalls.

Definition in file txc.h.

---

Define Documentation

#define XACT_BEGIN

(

tag

)

Value:

_TXC_transaction_pre_begin(SRCLOC_STR(__FILE__, __LINE__),                 \
                             __FILE__,                                       \
                             __FUNCTION__,                                   \
                             __LINE__);                                      \
  __tm_atomic                                                                \
  {                                                                          \
    _TXC_transaction_post_begin();

Definition at line 48 of file txc.h.

#define XCALL_DEF

(

xcall

)

_TXC_##xcall

xCall API

Please note that xCall functions names are defined using XCALL_DEF(xcall). This is to allow flexibility in choosing the library prefix.

Definition at line 93 of file txc.h.

---

Function Documentation

TM_WAIVER txc_tx_xactstate_t _TXC_get_xactstate

(

)

Returns the transactional state of the current thread.

Returns:

Running outside a transaction (TXC_XACTSTATE_NONTRANSACTIONAL = 0), Running inside a retryable tranasction (TXC_XACTSTATE_TRANSACTIONAL_RETRYABLE = 1), Running inside an irrevocable (non-retryable) transaction TXC_XACTSTATE_TRANSACTIONAL_IRREVOCABLE = 2

Definition at line 124 of file interface.c.

References txc_l_txd, and txc_tx_get_xactstate().

TM_WAIVER int _TXC_global_init

(

)

Performs global initialization of the library.

Creates all necessary managers.

Returns:

Returns 0 on success.

Definition at line 46 of file interface.c.

References txc_buffermgr_create(), txc_config_init(), txc_g_buffermgr, txc_g_koamgr, txc_g_sentinelmgr, txc_g_statsmgr, txc_g_txmgr, txc_koamgr_create(), TXC_R_SUCCESS, txc_runtime_settings, txc_sentinelmgr_create(), txc_statsmgr_create(), and txc_txmgr_create().

TM_WAIVER int _TXC_global_shutdown

(

)

Shutdowns the library.

Todo:

Destroy all library objects.

Returns:

Returns 0 on success.

Definition at line 78 of file interface.c.

References txc_g_statsmgr, TXC_R_SUCCESS, and txc_stats_print().

TM_WAIVER int _TXC_thread_init

(

)

Initializes and assigns an xCalls descriptor to a thread.

Returns:

Returns 0 on success.

Definition at line 92 of file interface.c.

References txc_g_txmgr, txc_l_txd, TXC_R_SUCCESS, and txc_tx_create().

TM_WAIVER void _TXC_transaction_abort

(

txc_tx_abortreason_t

abort_reason

)

Aborts a transaction.

Requests the xCall library to abort a transaction.

Parameters:

[in]

abort_reason

Reason for abort.

Returns:

Never returns.

Definition at line 108 of file interface.c.

References txc_l_txd, and txc_tx_abort_transaction().

TM_WAIVER void _TXC_transaction_pre_begin	(	const char *	srcloc_str,
		const char *	src_file,
		const char *	src_fun,
		int	src_line
	)

Informs the xCall library that a transaction is going to begin.

Parameters:

[in]	srcloc_str	String describing the transaction's source location.
[in]	src_file	The file where the transaction is located.
[in]	src_fun	The function where the transaction is located.
[in]	src_line	The line number where the transaction is located.

Returns:

None

Definition at line 142 of file interface.c.

References txc_l_txd, and txc_tx_pre_begin().

TM_WAIVER int XCALL_DEF() x_close	(	int	fildes,
		int *	result
	)

Closes a file descriptor.

Execution : deferred

Asynchronous failures: commit

Parameters:

[in]	fildes	File descriptor.
[out]	result	Where to store any asynchronous failures.

Returns:

0 on success, or -1 if a synchronous failure occurred (in which case, errno is set appropriately).

Definition at line 74 of file x_close.c.

Referenced by x_close().

TM_WAIVER int XCALL_DEF() x_create	(	const char *	pathname,
		mode_t	mode,
		int *	result
	)

Creates a file.

Creates a file using the creation flags: O_CREAT| O_NOCTTY| O_TRUNC| O_RDWR. If a file already exists then it is renamed and removed if transaction finally commits.

Execution : in-place

Asynchronous failures : commit, abort

Parameters:

[in]	pathname	Path to the file to be created.
[in]	mode	Permissions.
[out]	result	Where to store any asynchronous failures.

Returns:

The new file descriptor on success, or -1 if a synchronous failure occurred (in which case, errno is set appropriately).

Definition at line 150 of file x_create.c.

Referenced by x_create().

TM_WAIVER int XCALL_DEF() x_dup	(	int	oldfd,
		int *	result
	)

Duplicates a file descriptor.

The new file descriptor shares the sentinels of the original file descriptor.

Execution : in-place

Asynchronous failures: abort

Parameters:

[in]	oldfd	The original file descriptor to be duplicated.
[out]	result	Where to store any asynchronous failures.

Returns:

The new file descriptor on success, or -1 if a synchronous failure occurred (in which case, errno is set appropriately).

Definition at line 67 of file x_dup.c.

Referenced by x_dup().

TM_WAIVER int XCALL_DEF() x_fsync	(	int	fildes,
		int *	result
	)

Synchronizes a file in-core state with storage device.

Execution : deferred

Asynchronous failures : commit

Parameters:

[in]	fildes	The file's file descriptor.
[out]	result	Where to store any asynchronous failures.

Returns:

0 on success, or -1 if a synchronous failure occurred (in which case, errno is set appropriately).

Definition at line 78 of file x_fsync.c.

Referenced by x_fsync().

TM_WAIVER off_t XCALL_DEF() x_lseek	(	int	fd,
		off_t	offset,
		int	whence,
		int *	result
	)

Repositions read/write file offset.

Execution : in-place

Asynchronous failures : abort

Parameters:

[in]	fd	File descriptor.
[in]	offset	The new offset relative to whence.
[in]	whence	The absolute offset that the file offset is relatively repositioned to. SEEK_SET: The offset is set to offset bytes. SEEK_CUR: The offset is set to its current location plus offset bytes. SEEK_END: The offset is set to the size of the file plus offset bytes.
[out]	result	Where to store any asynchronous failures.

Returns:

The resulting offset location as measured in bytes from the beginning of the file on success, or (off_t) -1 if a synchronous failure occurred (in which case, errno is set appropriately).

Definition at line 72 of file x_lseek.c.

Referenced by x_lseek().

TM_WAIVER int XCALL_DEF() x_open	(	const char *	pathname,
		int	flags,
		mode_t	mode,
		int *	result
	)

Opens a file.

Execution : in-place

Asynchronous failures : abort

Parameters:

[in]	pathname
[out]	result	Where to store any asynchronous failures.

Returns:

The new file descriptor, or -1 if a synchronous failure occurred (in which case, errno is set appropriately).

Definition at line 69 of file x_open.c.

Referenced by x_open().

TM_WAIVER int XCALL_DEF() x_pipe	(	int	fildes[2],
		int *	result
	)

Creates a pipe.

Creates a pair of file descriptors, pointing to a pipe inode.

Execution : in-place

Asynchronous failures : abort

Parameters:

[in,out]	fildes	Array where to place the new file descriptors.
[out]	result	Where to store any asynchronous failures.

Returns:

0 on success, or -1 if a synchronous failure occurred (in which case, errno is set appropriately).

Definition at line 79 of file x_pipe.c.

Referenced by x_pipe().

TM_WAIVER ssize_t XCALL_DEF() x_printf	(	const char *	format,
			...
	)

Formatted output conversion.

Execution : deferred

Asynchronous failures : abort

Parameters:

[out]

result

Where to store any asynchronous failures.

Returns:

The number of characters printed on success, or -1 if a synchronous failure occurred (in which case, errno is set appropriately).

Definition at line 24 of file x_printf.c.

Referenced by x_printf().

TM_WAIVER int XCALL_DEF() x_pthread_create	(	pthread_t *	thread,
		const pthread_attr_t *	attr,
		void *(*)(void *)	start_routine,
		void *	arg,
		int *	result
	)

Creates a thread.

Execution : in-place creation of the thread but deferred execution of the start_routine

Asynchronous failures : commit, abort

Parameters:

[out]	thread	The new thread's identifier.
[in]	attr	Creation attributes.
[in]	start_routine	The routine that the new thread executes.
[in]	arg	Parameter passed to start_routine
[out]	result	Where to store any asynchronous failures.

Returns:

The new file descriptor on success, or -1 if a synchronous failure occurred (in which case, errno is set appropriately).

Definition at line 99 of file x_pthread_create.c.

TM_WAIVER int XCALL_DEF() x_pthread_mutex_lock	(	pthread_mutex_t *	mutex,
		int *	result
	)

Locks a mutex.

It safely locks a mutex by releasing the lock if the transaction aborts.

Execution : in-place

Asynchronous failures : abort

Parameters:

[in]	mutex	The mutex to lock.
[out]	result	Where to store any asynchronous failures.

Returns:

The new file descriptor on success, or -1 if a synchronous failure occurred (in which case, errno is set appropriately).

Definition at line 52 of file x_pthread_mutex_lock.c.

TM_WAIVER int XCALL_DEF() x_pthread_mutex_unlock	(	pthread_mutex_t *	mutex,
		int *	result
	)

Unlocks a mutex.

It safely unlocks a mutex by releasing the lock when the transaction commits.

Execution : deferred

Asynchronous failures : commit

Parameters:

[in]	mutex	The mutex to unlock.
[out]	result	Where to store any asynchronous failures.

Returns:

The new file descriptor on success, or -1 if a synchronous failure occurred (in which case, errno is set appropriately).

Definition at line 53 of file x_pthread_mutex_unlock.c.

TM_WAIVER ssize_t XCALL_DEF() x_read	(	int	fd,
		void *	buf,
		size_t	nbyte,
		int *	result
	)

Reads from a file.

Execution : in-place

Asynchronous failures : abort

Parameters:

[in]	fd	The file descriptor of the file to read from.
[in]	buf	The buffer where to store read data.
[in]	nbyte	The number of bytes to read.
[out]	result	Where to store any asynchronous failures.

Returns:

The number of read bytes on success, or -1 if a synchronous failure occurred (in which case, errno is set appropriately).

Definition at line 65 of file x_read.c.

Referenced by x_read().

TM_WAIVER ssize_t XCALL_DEF() x_read_pipe	(	int	fd,
		void *	buf,
		size_t	nbyte,
		int *	result
	)

Reads from a pipe.

The xCall buffers any read data so that in case of transaction abort read data are not consumed but stay present for the next pipe read.

Execution : in-place

Asynchronous failures : commit, abort

Parameters:

[in]	fd	The file descriptor of the pipe's read end.
[in]	buf	The buffer where to store read data.
[in]	nbyte	The number of bytes to read.
[out]	result	Where to store asynchronous failures.

Returns:

The number of read bytes on success, or -1 if a synchronous failure occurred (in which case, errno is set appropriately).

Definition at line 257 of file x_read_pipe.c.

TM_WAIVER ssize_t XCALL_DEF() x_recvmsg	(	int	s,
		struct msghdr *	msg,
		int	flags,
		int *	result
	)

Receives a message from a socket.

This xCall buffers any received data so that in case of transaction abort received data are not consumed but stay present for the next socket receive.

Execution : in-place

Asynchronous failures : commit, abort

Parameters:

[in]	fd	The file descriptor of the socket.
[in]	msg	Where to store the received message.
[in]	flags	See man recvmsg.
[out]	result	Where to store any asynchronous failures. failure occurred (in which case, errno is set appropriately).

Todo:

Find which flags of recvmsg can be used with x_recvmsg?

Definition at line 341 of file x_recvmsg.c.

TM_WAIVER int XCALL_DEF() x_rename	(	const char *	oldpath,
		const char *	newpath,
		int *	result
	)

Changes the name or location of a file.

If a file at the new location exists, then it is renamed to a temporary file and removed only when the transaction commits. This allows restoring the file in case the transaction aborts.

Execution : in-place

Asynchronous failures : commit, abort

Parameters:

[in]	oldpath	The old location of the file.
[in]	oldpath	The new location of the file.
[out]	result	Where to store any asynchronous failures.

Returns:

0 on success, or -1 if a synchronous failure occurred (in which case, errno is set appropriately).

Definition at line 124 of file x_rename.c.

Referenced by x_rename().

TM_WAIVER ssize_t XCALL_DEF() x_sendmsg	(	int	fd,
		const struct msghdr *	msg,
		int	flags,
		int *	result
	)

Sends a message to a socket.

Execution : deferred

Asynchronous failures : commit

Parameters:

[in]	fd	The file descriptor of the socket.
[in]	msg	The message to send.
[in]	flags	See man sendmsg.
[out]	result	Where to store any asynchronous failures.

Returns:

The number of sent characters on success, or -1 if a synchronous failure occurred (in which case, errno is set appropriately).

Todo:

Find which flags of sendmsg can be used with x_sendmsg?

Definition at line 68 of file x_sendmsg.c.

Referenced by x_sendmsg().

TM_WAIVER int XCALL_DEF() x_socket	(	int	domain,
		int	type,
		int	protocol,
		int *	result
	)

Creates an endpoint for communication.

Execution : in-place

Asynchronous failures : abort

Parameters:

[in]	domain	Communication domain; this selects the protocol family which will be used for communication. These families are defined in <sys/socket.h>.
[in]	type	Specifies communication semantics. Currently we support: SOCK_DGRAM: Supports datagrams (connectionless, unreliable messages of a fixed maximum length).
[in]	protocol	Specifies a particular protocol to be used with the socket.
[out]	result	Where to store any asynchronous failures.

Returns:

A new file descriptor for the new socket, or -1 if a synchronous failure occurred (in which case, errno is set appropriately).

Todo:

Implement SOCK_STREAM.

Definition at line 76 of file x_socket.c.

Referenced by x_socket().

TM_WAIVER int XCALL_DEF() x_unlink	(	const char *	pathname,
		int *	result
	)

Deletes a name and possibly the file it refers to.

Execution : deferred

Asynchronous failures : commit

Parameters:

[in]	pathname	The location of the file.
[out]	result	Where to store any asynchronous failures.

Returns:

0 on success, or -1 if a synchronous failure occurred (in which case, errno is set appropriately).

Definition at line 76 of file x_unlink.c.

Referenced by x_unlink().

TM_WAIVER ssize_t XCALL_DEF() x_write_ovr	(	int	fd,
		const void *	buf,
		size_t	nbyte,
		int *	result
	)

Writes to a file, while it saves any overwritten data.

Execution : in-place

Asynchronous failures : abort

Parameters:

[in]	fd	The file descriptor of the file.
[in]	buf	The buffer that has the data to be written.
[in]	nbyte	The number of bytes to write.
[out]	result	Where to store any asynchronous failures.

Returns:

The number of written bytes on success, or -1 if a synchronous failure occurred (in which case, errno is set appropriately).

Definition at line 326 of file x_write.c.

TM_WAIVER ssize_t XCALL_DEF() x_write_ovr_ignore	(	int	fd,
		const void *	buf,
		size_t	nbyte,
		int *	result
	)

Writes to a file without saving any overwritten data.

Execution : in-place

Asynchronous failures : abort

Parameters:

[in]	fd	The file descriptor of the file.
[in]	buf	The buffer that has the data to be written.
[in]	nbyte	The number of bytes to write.
[out]	result	Where to store any asynchronous failures.

Returns:

The number of written bytes on success, or -1 if a synchronous failure occurred (in which case, errno is set appropriately).

Definition at line 295 of file x_write.c.

TM_WAIVER ssize_t XCALL_DEF() x_write_pipe	(	int	fd,
		const void *	buf,
		size_t	nbyte,
		int *	result
	)

Writes to a pipe.

Execution : deferred

Asynchronous failures : commit

Parameters:

[in]	fd	The file descriptor of the pipe's write end.
[in]	buf	The buffer that has the data to write.
[in]	nbyte	The number of bytes to write.
[out]	result	Where to store any asynchronous failures.

Returns:

The number of written bytes on success, or -1 if a synchronous failure occurred (in which case, errno is set appropriately).

Definition at line 65 of file x_write_pipe.c.

Referenced by x_printf(), and x_write_pipe().

TM_WAIVER ssize_t XCALL_DEF() x_write_seq	(	int	fd,
		const void *	buf,
		size_t	nbyte,
		int *	result
	)

Write appends to a file.

Execution : in-place

Asynchronous failures : abort

Parameters:

[in]	fd	The file descriptor of the file.
[in]	buf	The buffer that has the data to be written.
[in]	nbyte	The number of bytes to write.
[out]	result	Where to store any asynchronous failures.

Returns:

The number of written bytes on success, or -1 if a synchronous failure occurred (in which case, errno is set appropriately).

Definition at line 274 of file x_write.c.

---