Provided by: libpmemobj-dev_1.13.1-1.1ubuntu2_amd64 
NAME
pmemobj_tx_add_range(), pmemobj_tx_add_range_direct(), pmemobj_tx_xadd_range(),
pmemobj_tx_xadd_range_direct()
TX_ADD(), TX_ADD_FIELD(), TX_ADD_DIRECT(), TX_ADD_FIELD_DIRECT(),
TX_XADD(), TX_XADD_FIELD(), TX_XADD_DIRECT(), TX_XADD_FIELD_DIRECT(),
TX_SET(), TX_SET_DIRECT(), TX_MEMCPY(), TX_MEMSET() - transactional object manipulation
SYNOPSIS
#include <libpmemobj.h>
int pmemobj_tx_add_range(PMEMoid oid, uint64_t off, size_t size);
int pmemobj_tx_add_range_direct(const void *ptr, size_t size);
int pmemobj_tx_xadd_range(PMEMoid oid, uint64_t off, size_t size, uint64_t flags);
int pmemobj_tx_xadd_range_direct(const void *ptr, size_t size, uint64_t flags);
TX_ADD(TOID o)
TX_ADD_FIELD(TOID o, FIELD)
TX_ADD_DIRECT(TYPE *p)
TX_ADD_FIELD_DIRECT(TYPE *p, FIELD)
TX_XADD(TOID o, uint64_t flags)
TX_XADD_FIELD(TOID o, FIELD, uint64_t flags)
TX_XADD_DIRECT(TYPE *p, uint64_t flags)
TX_XADD_FIELD_DIRECT(TYPE *p, FIELD, uint64_t flags)
TX_SET(TOID o, FIELD, VALUE)
TX_SET_DIRECT(TYPE *p, FIELD, VALUE)
TX_MEMCPY(void *dest, const void *src, size_t num)
TX_MEMSET(void *dest, int c, size_t num)
DESCRIPTION
pmemobj_tx_add_range() takes a “snapshot” of the memory block of given size, located at
given offset off in the object specified by oid, and saves it to the undo log. The
application is then free to directly modify the object in that memory range. In case of a
failure or abort, all the changes within this range will be rolled back. The supplied
block of memory has to be within the pool registered in the transaction. This function
must be called during TX_STAGE_WORK.
The pmemobj_tx_xadd_range() function behaves exactly the same as pmemobj_tx_add_range()
when flags equals zero. flags is a bitmask of the following values:
• POBJ_XADD_NO_FLUSH - skip flush on commit (when application deals with flushing or uses
pmemobj_memcpy_persist)
• POBJ_XADD_NO_SNAPSHOT - added range will not be “snapshotted”, i.e. any changes made
within it during the transaction will not be rolled backed after abort
• POBJ_XADD_ASSUME_INITIALIZED - added range is assumed to be initialized. If this flag
is not specified, passing uninitialized memory will result in an error when run under
Valgrind memcheck.
• POBJ_XADD_NO_ABORT - if the function does not end successfully, do not abort the
transaction.
pmemobj_tx_add_range_direct() behaves the same as pmemobj_tx_add_range() with the
exception that it operates on virtual memory addresses and not persistent memory objects.
It takes a “snapshot” of a persistent memory block of given size, located at the given
address ptr in the virtual memory space and saves it to the undo log. The application is
then free to directly modify the object in that memory range. In case of a failure or
abort, all the changes within this range will be rolled back. The supplied block of
memory has to be within the pool registered in the transaction. This function must be
called during TX_STAGE_WORK.
The pmemobj_tx_xadd_range_direct() function behaves exactly the same as
pmemobj_tx_add_range_direct() when flags equals zero. flags is a bitmask of the following
values:
• POBJ_XADD_NO_FLUSH - skip flush on commit (when application deals with flushing or uses
pmemobj_memcpy_persist)
• POBJ_XADD_NO_SNAPSHOT - added range will not be “snapshotted”, i.e. any changes made
within it during the transaction will not be rolled backed after abort
• POBJ_XADD_ASSUME_INITIALIZED - added range is assumed to be initialized. If this flag
is not specified, passing uninitialized memory will result in an error when run under
Valgrind memcheck.
• POBJ_XADD_NO_ABORT - if the function does not end successfully, do not abort the
transaction.
Similarly to the macros controlling the transaction flow, libpmemobj defines a set of
macros that simplify the transactional operations on persistent objects. Note that those
macros operate on typed object handles, thus eliminating the need to specify the size of
the object, or the size and offset of the field in the user-defined structure that is to
be modified.
The TX_ADD_FIELD() macro saves the current value of given FIELD of the object referenced
by a handle o in the undo log. The application is then free to directly modify the
specified FIELD. In case of a failure or abort, the saved value will be restored.
The TX_XADD_FIELD() macro works exactly like TX_ADD_FIELD when flags equals 0. The flags
argument is a bitmask of values described in pmemobj_tx_xadd_range, above.
The TX_ADD() macro takes a “snapshot” of the entire object referenced by object handle o
and saves it in the undo log. The object size is determined from its TYPE. The
application is then free to directly modify the object. In case of a failure or abort,
all the changes within the object will be rolled back.
The TX_XADD() macro works exactly like TX_ADD when flags equals 0. The flags argument is
a bitmask of values as described in pmemobj_tx_xadd_range, above.
The TX_ADD_FIELD_DIRECT() macro saves the current value of the given FIELD of the object
referenced by (direct) pointer p in the undo log. The application is then free to
directly modify the specified FIELD. In case of a failure or abort, the saved value will
be restored.
The TX_XADD_FIELD_DIRECT() macro works exactly like TX_ADD_FIELD_DIRECT when flags equals
0. The flags argument is a bitmask of values as described in
pmemobj_tx_xadd_range_direct, above.
The TX_ADD_DIRECT() macro takes a “snapshot” of the entire object referenced by (direct)
pointer p and saves it in the undo log. The object size is determined from its TYPE. The
application is then free to directly modify the object. In case of a failure or abort,
all the changes within the object will be rolled back.
The TX_XADD_DIRECT() macro works exactly like TX_ADD_DIRECT when flags equals 0. The
flags argument is a bitmask of values as described in pmemobj_tx_xadd_range_direct, above.
The TX_SET() macro saves the current value of the given FIELD of the object referenced by
handle o in the undo log, and then sets its new VALUE. In case of a failure or abort, the
saved value will be restored.
The TX_SET_DIRECT() macro saves in the undo log the current value of given FIELD of the
object referenced by (direct) pointer p, and then set its new VALUE. In case of a failure
or abort, the saved value will be restored.
The TX_MEMCPY() macro saves in the undo log the current content of dest buffer and then
overwrites the first num bytes of its memory area with the data copied from the buffer
pointed by src. In case of a failure or abort, the saved value will be restored.
The TX_MEMSET() macro saves the current content of the dest buffer in the undo log and
then fills the first num bytes of its memory area with the constant byte c. In case of a
failure or abort, the saved value will be restored.
RETURN VALUE
On success, pmemobj_tx_add_range() and pmemobj_tx_add_range_direct() return 0. Otherwise,
the stage is changed to TX_STAGE_ONABORT, errno is set appropriately and transaction is
aborted.
On success, pmemobj_tx_xadd_range() and pmemobj_tx_xadd_range_direct() returns 0.
Otherwise, the error number is returned, errno is set and when flags do not contain
POBJ_XADD_NO_ABORT, the transaction is aborted.
SEE ALSO
pmemobj_tx_alloc(3), pmemobj_tx_begin(3), libpmemobj(7) and <https://pmem.io>