.\" Automatically generated by Pandoc 2.2.1 .\" .TH "PMEMOBJ_TX_ADD_RANGE" "3" "2019-02-19" "PMDK - pmemobj API version 2.3" "PMDK Programmer's Manual" .hy .\" Copyright 2014-2019, 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\ 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]\f[]