.\" Automatically generated by Pandoc 2.1.3
.\"
.TH "PMEMOBJ_TX_ADD_RANGE" "3" "2018-07-18" "PMDK - pmemobj API version 2.3" "PMDK Programmer's Manual"
.hy
.\" Copyright 2014-2018, Intel Corporation
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" * Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\"
.\" * Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in
.\" the documentation and/or other materials provided with the
.\" distribution.
.\"
.\" * Neither the name of the copyright holder nor the names of its
.\" contributors may be used to endorse or promote products derived
.\" from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
.\" OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.SH NAME
.PP
\f[B]pmemobj_tx_add_range\f[](), \f[B]pmemobj_tx_add_range_direct\f[](),
\f[B]pmemobj_tx_xadd_range\f[](),
\f[B]pmemobj_tx_xadd_range_direct\f[]()
.PP
\f[B]TX_ADD\f[](), \f[B]TX_ADD_FIELD\f[](), \f[B]TX_ADD_DIRECT\f[](),
\f[B]TX_ADD_FIELD_DIRECT\f[](),
.PP
\f[B]TX_XADD\f[](), \f[B]TX_XADD_FIELD\f[](), \f[B]TX_XADD_DIRECT\f[](),
\f[B]TX_XADD_FIELD_DIRECT\f[](),
.PP
\f[B]TX_SET\f[](), \f[B]TX_SET_DIRECT\f[](), \f[B]TX_MEMCPY\f[](),
\f[B]TX_MEMSET\f[]() \- 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[]
.fi
.SH DESCRIPTION
.PP
\f[B]pmemobj_tx_add_range\f[]() takes a \[lq]snapshot\[rq] of the memory
block of given \f[I]size\f[], located at given offset \f[I]off\f[] in
the object specified by \f[I]oid\f[], 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[].
.PP
The \f[B]pmemobj_tx_xadd_range\f[]() function behaves exactly the same
as \f[B]pmemobj_tx_add_range\f[]() when \f[I]flags\f[] equals zero.
\f[I]flags\f[] is a bitmask of the following values:
.IP \[bu] 2
\f[B]POBJ_XADD_NO_FLUSH\f[] \- skip flush on commit when application
deals with flushing or uses pmemobj_memcpy_persist)
.PP
\f[B]pmemobj_tx_add_range_direct\f[]() behaves the same as
\f[B]pmemobj_tx_add_range\f[]() 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[], located at the given address \f[I]ptr\f[] 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[].
.PP
The \f[B]pmemobj_tx_xadd_range_direct\f[]() function behaves exactly the
same as \f[B]pmemobj_tx_add_range_direct\f[]() when \f[I]flags\f[]
equals zero.
\f[I]flags\f[] is a bitmask of the following values:
.IP \[bu] 2
\f[B]POBJ_XADD_NO_FLUSH\f[] \- skip flush on commit (when application
deals with flushing or uses pmemobj_memcpy_persist)
.PP
Similarly to the macros controlling the transaction flow,
\f[B]libpmemobj\f[] 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[]() macro saves the current value of given
\f[I]FIELD\f[] of the object referenced by a handle \f[I]o\f[] in the
undo log.
The application is then free to directly modify the specified
\f[I]FIELD\f[].
In case of a failure or abort, the saved value will be restored.
.PP
The \f[B]TX_XADD_FIELD\f[]() macro works exactly like
\f[B]TX_ADD_FIELD\f[] when \f[I]flags\f[] equals 0.
The \f[I]flags\f[] argument is a bitmask of values described in
\f[B]pmemobj_tx_xadd_range\f[], above.
.PP
The \f[B]TX_ADD\f[]() macro takes a \[lq]snapshot\[rq] of the entire
object referenced by object handle \f[I]o\f[] and saves it in the undo
log.
The object size is determined from its \f[I]TYPE\f[].
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[]() macro works exactly like \f[B]TX_ADD\f[] when
\f[I]flags\f[] equals 0.
The \f[I]flags\f[] argument is a bitmask of values as described in
\f[B]pmemobj_tx_xadd_range\f[], above.
.PP
The \f[B]TX_ADD_FIELD_DIRECT\f[]() macro saves the current value of the
given \f[I]FIELD\f[] of the object referenced by (direct) pointer
\f[I]p\f[] in the undo log.
The application is then free to directly modify the specified
\f[I]FIELD\f[].
In case of a failure or abort, the saved value will be restored.
.PP
The \f[B]TX_XADD_FIELD_DIRECT\f[]() macro works exactly like
\f[B]TX_ADD_FIELD_DIRECT\f[] when \f[I]flags\f[] equals 0.
The \f[I]flags\f[] argument is a bitmask of values as described in
\f[B]pmemobj_tx_xadd_range_direct\f[], above.
.PP
The \f[B]TX_ADD_DIRECT\f[]() macro takes a \[lq]snapshot\[rq] of the
entire object referenced by (direct) pointer \f[I]p\f[] and saves it in
the undo log.
The object size is determined from its \f[I]TYPE\f[].
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[]() macro works exactly like
\f[B]TX_ADD_DIRECT\f[] when \f[I]flags\f[] equals 0.
The \f[I]flags\f[] argument is a bitmask of values as described in
\f[B]pmemobj_tx_xadd_range_direct\f[], above.
.PP
The \f[B]TX_SET\f[]() macro saves the current value of the given
\f[I]FIELD\f[] of the object referenced by handle \f[I]o\f[] in the undo
log, and then sets its new \f[I]VALUE\f[].
In case of a failure or abort, the saved value will be restored.
.PP
The \f[B]TX_SET_DIRECT\f[]() macro saves in the undo log the current
value of given \f[I]FIELD\f[] of the object referenced by (direct)
pointer \f[I]p\f[], and then set its new \f[I]VALUE\f[].
In case of a failure or abort, the saved value will be restored.
.PP
The \f[B]TX_MEMCPY\f[]() macro saves in the undo log the current content
of \f[I]dest\f[] buffer and then overwrites the first \f[I]num\f[] bytes
of its memory area with the data copied from the buffer pointed by
\f[I]src\f[].
In case of a failure or abort, the saved value will be restored.
.PP
The \f[B]TX_MEMSET\f[]() macro saves the current content of the
\f[I]dest\f[] buffer in the undo log and then fills the first
\f[I]num\f[] bytes of its memory area with the constant byte \f[I]c\f[].
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[](),
\f[B]pmemobj_tx_xadd_range\f[](), \f[B]pmemobj_tx_add_range_direct\f[]()
and \f[B]pmemobj_tx_xadd_range_direct\f[]() return 0.
Otherwise, the stage is changed to \f[B]TX_STAGE_ONABORT\f[] and an
error number is returned.
.SH SEE ALSO
.PP
\f[B]pmemobj_tx_alloc\f[](3), \f[B]pmemobj_tx_begin\f[](3),
\f[B]libpmemobj\f[](7) and \f[B]<http://pmem.io>\f[]