.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "" "" "2023-05-31" "PMDK - " "PMDK Programmer's Manual"
.hy
.\" SPDX-License-Identifier: BSD-3-Clause
.\" Copyright 2017-2019, Intel Corporation
.SH NAME
.PP
\f[B]pmemobj_tx_add_range\f[R](),
\f[B]pmemobj_tx_add_range_direct\f[R](),
\f[B]pmemobj_tx_xadd_range\f[R](),
\f[B]pmemobj_tx_xadd_range_direct\f[R]()
.PP
\f[B]TX_ADD\f[R](), \f[B]TX_ADD_FIELD\f[R](), \f[B]TX_ADD_DIRECT\f[R](),
\f[B]TX_ADD_FIELD_DIRECT\f[R](),
.PP
\f[B]TX_XADD\f[R](), \f[B]TX_XADD_FIELD\f[R](),
\f[B]TX_XADD_DIRECT\f[R](), \f[B]TX_XADD_FIELD_DIRECT\f[R](),
.PP
\f[B]TX_SET\f[R](), \f[B]TX_SET_DIRECT\f[R](), \f[B]TX_MEMCPY\f[R](),
\f[B]TX_MEMSET\f[R]() - transactional object manipulation
.SH SYNOPSIS
.IP
.nf
\f[C]
#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)
\f[R]
.fi
.SH DESCRIPTION
.PP
\f[B]pmemobj_tx_add_range\f[R]() takes a \[lq]snapshot\[rq] of the
memory block of given \f[I]size\f[R], located at given offset
\f[I]off\f[R] in the object specified by \f[I]oid\f[R], 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 \f[B]TX_STAGE_WORK\f[R].
.PP
The \f[B]pmemobj_tx_xadd_range\f[R]() function behaves exactly the same
as \f[B]pmemobj_tx_add_range\f[R]() when \f[I]flags\f[R] equals zero.
\f[I]flags\f[R] is a bitmask of the following values:
.IP \[bu] 2
\f[B]POBJ_XADD_NO_FLUSH\f[R] - skip flush on commit (when application
deals with flushing or uses pmemobj_memcpy_persist)
.IP \[bu] 2
\f[B]POBJ_XADD_NO_SNAPSHOT\f[R] - added range will not be
\[lq]snapshotted\[rq], i.e.\ any changes made within it during the
transaction will not be rolled backed after abort
.IP \[bu] 2
\f[B]POBJ_XADD_ASSUME_INITIALIZED\f[R] - 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.
.IP \[bu] 2
\f[B]POBJ_XADD_NO_ABORT\f[R] - if the function does not end
successfully, do not abort the transaction.
.PP
\f[B]pmemobj_tx_add_range_direct\f[R]() behaves the same as
\f[B]pmemobj_tx_add_range\f[R]() with the exception that it operates on
virtual memory addresses and not persistent memory objects.
It takes a \[lq]snapshot\[rq] of a persistent memory block of given
\f[I]size\f[R], located at the given address \f[I]ptr\f[R] 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 \f[B]TX_STAGE_WORK\f[R].
.PP
The \f[B]pmemobj_tx_xadd_range_direct\f[R]() function behaves exactly
the same as \f[B]pmemobj_tx_add_range_direct\f[R]() when \f[I]flags\f[R]
equals zero.
\f[I]flags\f[R] is a bitmask of the following values:
.IP \[bu] 2
\f[B]POBJ_XADD_NO_FLUSH\f[R] - skip flush on commit (when application
deals with flushing or uses pmemobj_memcpy_persist)
.IP \[bu] 2
\f[B]POBJ_XADD_NO_SNAPSHOT\f[R] - added range will not be
\[lq]snapshotted\[rq], i.e.\ any changes made within it during the
transaction will not be rolled backed after abort
.IP \[bu] 2
\f[B]POBJ_XADD_ASSUME_INITIALIZED\f[R] - 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.
.IP \[bu] 2
\f[B]POBJ_XADD_NO_ABORT\f[R] - if the function does not end
successfully, do not abort the transaction.
.PP
Similarly to the macros controlling the transaction flow,
\f[B]libpmemobj\f[R] 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.
.PP
The \f[B]TX_ADD_FIELD\f[R]() macro saves the current value of given
\f[I]FIELD\f[R] of the object referenced by a handle \f[I]o\f[R] in the
undo log.
The application is then free to directly modify the specified
\f[I]FIELD\f[R].
In case of a failure or abort, the saved value will be restored.
.PP
The \f[B]TX_XADD_FIELD\f[R]() macro works exactly like
\f[B]TX_ADD_FIELD\f[R] when \f[I]flags\f[R] equals 0.
The \f[I]flags\f[R] argument is a bitmask of values described in
\f[B]pmemobj_tx_xadd_range\f[R], above.
.PP
The \f[B]TX_ADD\f[R]() macro takes a \[lq]snapshot\[rq] of the entire
object referenced by object handle \f[I]o\f[R] and saves it in the undo
log.
The object size is determined from its \f[I]TYPE\f[R].
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.
.PP
The \f[B]TX_XADD\f[R]() macro works exactly like \f[B]TX_ADD\f[R] when
\f[I]flags\f[R] equals 0.
The \f[I]flags\f[R] argument is a bitmask of values as described in
\f[B]pmemobj_tx_xadd_range\f[R], above.
.PP
The \f[B]TX_ADD_FIELD_DIRECT\f[R]() macro saves the current value of the
given \f[I]FIELD\f[R] of the object referenced by (direct) pointer
\f[I]p\f[R] in the undo log.
The application is then free to directly modify the specified
\f[I]FIELD\f[R].
In case of a failure or abort, the saved value will be restored.
.PP
The \f[B]TX_XADD_FIELD_DIRECT\f[R]() macro works exactly like
\f[B]TX_ADD_FIELD_DIRECT\f[R] when \f[I]flags\f[R] equals 0.
The \f[I]flags\f[R] argument is a bitmask of values as described in
\f[B]pmemobj_tx_xadd_range_direct\f[R], above.
.PP
The \f[B]TX_ADD_DIRECT\f[R]() macro takes a \[lq]snapshot\[rq] of the
entire object referenced by (direct) pointer \f[I]p\f[R] and saves it in
the undo log.
The object size is determined from its \f[I]TYPE\f[R].
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.
.PP
The \f[B]TX_XADD_DIRECT\f[R]() macro works exactly like
\f[B]TX_ADD_DIRECT\f[R] when \f[I]flags\f[R] equals 0.
The \f[I]flags\f[R] argument is a bitmask of values as described in
\f[B]pmemobj_tx_xadd_range_direct\f[R], above.
.PP
The \f[B]TX_SET\f[R]() macro saves the current value of the given
\f[I]FIELD\f[R] of the object referenced by handle \f[I]o\f[R] in the
undo log, and then sets its new \f[I]VALUE\f[R].
In case of a failure or abort, the saved value will be restored.
.PP
The \f[B]TX_SET_DIRECT\f[R]() macro saves in the undo log the current
value of given \f[I]FIELD\f[R] of the object referenced by (direct)
pointer \f[I]p\f[R], and then set its new \f[I]VALUE\f[R].
In case of a failure or abort, the saved value will be restored.
.PP
The \f[B]TX_MEMCPY\f[R]() macro saves in the undo log the current
content of \f[I]dest\f[R] buffer and then overwrites the first
\f[I]num\f[R] bytes of its memory area with the data copied from the
buffer pointed by \f[I]src\f[R].
In case of a failure or abort, the saved value will be restored.
.PP
The \f[B]TX_MEMSET\f[R]() macro saves the current content of the
\f[I]dest\f[R] buffer in the undo log and then fills the first
\f[I]num\f[R] bytes of its memory area with the constant byte
\f[I]c\f[R].
In case of a failure or abort, the saved value will be restored.
.SH RETURN VALUE
.PP
On success, \f[B]pmemobj_tx_add_range\f[R]() and
\f[B]pmemobj_tx_add_range_direct\f[R]() return 0.
Otherwise, the stage is changed to \f[B]TX_STAGE_ONABORT\f[R],
\f[B]errno\f[R] is set appropriately and transaction is aborted.
.PP
On success, \f[B]pmemobj_tx_xadd_range\f[R]() and
\f[B]pmemobj_tx_xadd_range_direct\f[R]() returns 0.
Otherwise, the error number is returned, \f[B]errno\f[R] is set and when
flags do not contain \f[B]POBJ_XADD_NO_ABORT\f[R], the transaction is
aborted.
.SH SEE ALSO
.PP
\f[B]pmemobj_tx_alloc\f[R](3), \f[B]pmemobj_tx_begin\f[R](3),
\f[B]libpmemobj\f[R](7) and \f[B]<https://pmem.io>\f[R]