1PMEMOBJ_TX_ADD_RANGE(3)    PMDK Programmer's Manual    PMEMOBJ_TX_ADD_RANGE(3)
2
3
4

NAME

6       pmemobj_tx_add_range(),      pmemobj_tx_add_range_direct(),      pmemo‐
7       bj_tx_xadd_range(), pmemobj_tx_xadd_range_direct()
8
9       TX_ADD(), TX_ADD_FIELD(), TX_ADD_DIRECT(), TX_ADD_FIELD_DIRECT(),
10
11       TX_XADD(), TX_XADD_FIELD(), TX_XADD_DIRECT(), TX_XADD_FIELD_DIRECT(),
12
13       TX_SET(), TX_SET_DIRECT(), TX_MEMCPY(), TX_MEMSET() - transactional ob‐
14       ject manipulation
15

SYNOPSIS

17              #include <libpmemobj.h>
18
19              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
24              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
29              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
34              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

DESCRIPTION

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
48       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
52       · POBJ_XADD_NO_FLUSH  -  skip  flush  on commit (when application deals
53         with flushing or uses pmemobj_memcpy_persist)
54
55       · 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
59       · 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
63       · POBJ_XADD_NO_ABORT - if the function does not  end  successfully,  do
64         not abort the transaction.
65
66       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
77       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
81       · POBJ_XADD_NO_FLUSH - skip flush on  commit  (when  application  deals
82         with flushing or uses pmemobj_memcpy_persist)
83
84       · 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
88       · 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
92       · POBJ_XADD_NO_ABORT  -  if  the function does not end successfully, do
93         not abort the transaction.
94
95       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
102       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
107       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
111       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
117       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
121       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
126       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
130       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
136       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
140       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
145       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
150       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
155       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

RETURN VALUE

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
165       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

SEE ALSO

171       pmemobj_tx_alloc(3),     pmemobj_tx_begin(3),     libpmemobj(7)     and
172       <https://pmem.io>
173
174
175
176PMDK - pmemobj API version 2.3    2020-01-31           PMEMOBJ_TX_ADD_RANGE(3)
Impressum