1PMEMOBJ_TX_ADD_RANGE(3) PMDK Programmer's Manual PMEMOBJ_TX_ADD_RANGE(3)
2
6 pmemobj_tx_add_range(), pmemobj_tx_add_range_direct(), pmemo‐
7 bj_tx_xadd_range(), pmemobj_tx_xadd_range_direct()
8 TX_ADD(), TX_ADD_FIELD(), TX_ADD_DIRECT(), TX_ADD_FIELD_DIRECT(),
10 TX_XADD(), TX_XADD_FIELD(), TX_XADD_DIRECT(), TX_XADD_FIELD_DIRECT(),
12 TX_SET(), TX_SET_DIRECT(), TX_MEMCPY(), TX_MEMSET() - transactional ob‐
14 ject manipulation
15
17 #include <libpmemobj.h>
18 int pmemobj_tx_add_range(PMEMoid oid, uint64_t off, size_t size);
20 int pmemobj_tx_add_range_direct(const void *ptr, size_t size);
21 int pmemobj_tx_xadd_range(PMEMoid oid, uint64_t off, size_t size, uint64_t flags);
22 int pmemobj_tx_xadd_range_direct(const void *ptr, size_t size, uint64_t flags);
23 TX_ADD(TOID o)
25 TX_ADD_FIELD(TOID o, FIELD)
26 TX_ADD_DIRECT(TYPE *p)
27 TX_ADD_FIELD_DIRECT(TYPE *p, FIELD)
28 TX_XADD(TOID o, uint64_t flags)
30 TX_XADD_FIELD(TOID o, FIELD, uint64_t flags)
31 TX_XADD_DIRECT(TYPE *p, uint64_t flags)
32 TX_XADD_FIELD_DIRECT(TYPE *p, FIELD, uint64_t flags)
33 TX_SET(TOID o, FIELD, VALUE)
35 TX_SET_DIRECT(TYPE *p, FIELD, VALUE)
36 TX_MEMCPY(void *dest, const void *src, size_t num)
37 TX_MEMSET(void *dest, int c, size_t num)
38
40 pmemobj_tx_add_range() takes a “snapshot” of the memory block of given
41 size, located at given offset off in the object specified by oid, and
42 saves it to the undo log. The application is then free to directly
43 modify the object in that memory range. In case of a failure or abort,
44 all the changes within this range will be rolled back. The supplied
45 block of memory has to be within the pool registered in the transac‐
46 tion. This function must be called during TX_STAGE_WORK.
47 The pmemobj_tx_xadd_range() function behaves exactly the same as pmemo‐
49 bj_tx_add_range() when flags equals zero. flags is a bitmask of the
50 following values:
51 • POBJ_XADD_NO_FLUSH - skip flush on commit (when application deals
53 with flushing or uses pmemobj_memcpy_persist)
54 • POBJ_XADD_NO_SNAPSHOT - added range will not be “snapshotted”,
56 i.e. any changes made within it during the transaction will not be
57 rolled backed after abort
58 • POBJ_XADD_ASSUME_INITIALIZED - added range is assumed to be initial‐
60 ized. If this flag is not specified, passing uninitialized memory
61 will result in an error when run under Valgrind memcheck.
62 • POBJ_XADD_NO_ABORT - if the function does not end successfully, do
64 not abort the transaction.
65 pmemobj_tx_add_range_direct() behaves the same as pmemo‐
67 bj_tx_add_range() with the exception that it operates on virtual memory
68 addresses and not persistent memory objects. It takes a “snapshot” of
69 a persistent memory block of given size, located at the given address
70 ptr in the virtual memory space and saves it to the undo log. The ap‐
71 plication is then free to directly modify the object in that memory
72 range. In case of a failure or abort, all the changes within this
73 range will be rolled back. The supplied block of memory has to be
74 within the pool registered in the transaction. This function must be
75 called during TX_STAGE_WORK.
76 The pmemobj_tx_xadd_range_direct() function behaves exactly the same as
78 pmemobj_tx_add_range_direct() when flags equals zero. flags is a bit‐
79 mask of the following values:
80 • POBJ_XADD_NO_FLUSH - skip flush on commit (when application deals
82 with flushing or uses pmemobj_memcpy_persist)
83 • POBJ_XADD_NO_SNAPSHOT - added range will not be “snapshotted”,
85 i.e. any changes made within it during the transaction will not be
86 rolled backed after abort
87 • POBJ_XADD_ASSUME_INITIALIZED - added range is assumed to be initial‐
89 ized. If this flag is not specified, passing uninitialized memory
90 will result in an error when run under Valgrind memcheck.
91 • POBJ_XADD_NO_ABORT - if the function does not end successfully, do
93 not abort the transaction.
94 Similarly to the macros controlling the transaction flow, libpmemobj
96 defines a set of macros that simplify the transactional operations on
97 persistent objects. Note that those macros operate on typed object
98 handles, thus eliminating the need to specify the size of the object,
99 or the size and offset of the field in the user-defined structure that
100 is to be modified.
101 The TX_ADD_FIELD() macro saves the current value of given FIELD of the
103 object referenced by a handle o in the undo log. The application is
104 then free to directly modify the specified FIELD. In case of a failure
105 or abort, the saved value will be restored.
106 The TX_XADD_FIELD() macro works exactly like TX_ADD_FIELD when flags
108 equals 0. The flags argument is a bitmask of values described in pmem‐
109 obj_tx_xadd_range, above.
110 The TX_ADD() macro takes a “snapshot” of the entire object referenced
112 by object handle o and saves it in the undo log. The object size is
113 determined from its TYPE. The application is then free to directly
114 modify the object. In case of a failure or abort, all the changes
115 within the object will be rolled back.
116 The TX_XADD() macro works exactly like TX_ADD when flags equals 0. The
118 flags argument is a bitmask of values as described in pmemo‐
119 bj_tx_xadd_range, above.
120 The TX_ADD_FIELD_DIRECT() macro saves the current value of the given
122 FIELD of the object referenced by (direct) pointer p in the undo log.
123 The application is then free to directly modify the specified FIELD.
124 In case of a failure or abort, the saved value will be restored.
125 The TX_XADD_FIELD_DIRECT() macro works exactly like TX_ADD_FIELD_DIRECT
127 when flags equals 0. The flags argument is a bitmask of values as de‐
128 scribed in pmemobj_tx_xadd_range_direct, above.
129 The TX_ADD_DIRECT() macro takes a “snapshot” of the entire object ref‐
131 erenced by (direct) pointer p and saves it in the undo log. The object
132 size is determined from its TYPE. The application is then free to di‐
133 rectly modify the object. In case of a failure or abort, all the
134 changes within the object will be rolled back.
135 The TX_XADD_DIRECT() macro works exactly like TX_ADD_DIRECT when flags
137 equals 0. The flags argument is a bitmask of values as described in
138 pmemobj_tx_xadd_range_direct, above.
139 The TX_SET() macro saves the current value of the given FIELD of the
141 object referenced by handle o in the undo log, and then sets its new
142 VALUE. In case of a failure or abort, the saved value will be re‐
143 stored.
144 The TX_SET_DIRECT() macro saves in the undo log the current value of
146 given FIELD of the object referenced by (direct) pointer p, and then
147 set its new VALUE. In case of a failure or abort, the saved value will
148 be restored.
149 The TX_MEMCPY() macro saves in the undo log the current content of dest
151 buffer and then overwrites the first num bytes of its memory area with
152 the data copied from the buffer pointed by src. In case of a failure
153 or abort, the saved value will be restored.
154 The TX_MEMSET() macro saves the current content of the dest buffer in
156 the undo log and then fills the first num bytes of its memory area with
157 the constant byte c. In case of a failure or abort, the saved value
158 will be restored.
159
161 On success, pmemobj_tx_add_range() and pmemobj_tx_add_range_direct()
162 return 0. Otherwise, the stage is changed to TX_STAGE_ONABORT, errno
163 is set appropriately and transaction is aborted.
164 On success, pmemobj_tx_xadd_range() and pmemobj_tx_xadd_range_direct()
166 returns 0. Otherwise, the error number is returned, errno is set and
167 when flags do not contain POBJ_XADD_NO_ABORT, the transaction is abort‐
168 ed.
169
171 pmemobj_tx_alloc(3), pmemobj_tx_begin(3), libpmemobj(7) and
172 <https://pmem.io>
173PMDK - pmemobj API version 2.3 2021-09-24 PMEMOBJ_TX_ADD_RANGE(3)