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 with
53         flushing or uses pmemobj_memcpy_persist)
54
55       pmemobj_tx_add_range_direct()    behaves    the    same    as    pmemo‐
56       bj_tx_add_range() with the exception that it operates on virtual memory
57       addresses and not persistent memory objects.  It takes a “snapshot”  of
58       a  persistent  memory block of given size, located at the given address
59       ptr in the virtual memory space and saves it to the undo log.  The  ap‐
60       plication  is  then  free  to directly modify the object in that memory
61       range.  In case of a failure or abort,  all  the  changes  within  this
62       range  will  be  rolled  back.   The supplied block of memory has to be
63       within the pool registered in the transaction.  This function  must  be
64       called during TX_STAGE_WORK.
65
66       The pmemobj_tx_xadd_range_direct() function behaves exactly the same as
67       pmemobj_tx_add_range_direct() when flags equals zero.  flags is a  bit‐
68       mask of the following values:
69
70       · POBJ_XADD_NO_FLUSH  -  skip  flush  on commit (when application deals
71         with flushing or uses pmemobj_memcpy_persist)
72
73       Similarly to the macros controlling the  transaction  flow,  libpmemobj
74       defines  a  set of macros that simplify the transactional operations on
75       persistent objects.  Note that those macros  operate  on  typed  object
76       handles,  thus  eliminating the need to specify the size of the object,
77       or the size and offset of the field in the user-defined structure  that
78       is to be modified.
79
80       The  TX_ADD_FIELD() macro saves the current value of given FIELD of the
81       object referenced by a handle o in the undo log.   The  application  is
82       then free to directly modify the specified FIELD.  In case of a failure
83       or abort, the saved value will be restored.
84
85       The TX_XADD_FIELD() macro works exactly like  TX_ADD_FIELD  when  flags
86       equals 0.  The flags argument is a bitmask of values described in pmem‐
87       obj_tx_xadd_range, above.
88
89       The TX_ADD() macro takes a “snapshot” of the entire  object  referenced
90       by  object  handle  o and saves it in the undo log.  The object size is
91       determined from its TYPE.  The application is  then  free  to  directly
92       modify  the  object.   In  case  of a failure or abort, all the changes
93       within the object will be rolled back.
94
95       The TX_XADD() macro works exactly like TX_ADD when flags equals 0.  The
96       flags   argument  is  a  bitmask  of  values  as  described  in  pmemo‐
97       bj_tx_xadd_range, above.
98
99       The TX_ADD_FIELD_DIRECT() macro saves the current value  of  the  given
100       FIELD  of  the object referenced by (direct) pointer p in the undo log.
101       The application is then free to directly modify  the  specified  FIELD.
102       In case of a failure or abort, the saved value will be restored.
103
104       The TX_XADD_FIELD_DIRECT() macro works exactly like TX_ADD_FIELD_DIRECT
105       when flags equals 0.  The flags argument is a bitmask of values as  de‐
106       scribed in pmemobj_tx_xadd_range_direct, above.
107
108       The  TX_ADD_DIRECT() macro takes a “snapshot” of the entire object ref‐
109       erenced by (direct) pointer p and saves it in the undo log.  The object
110       size  is determined from its TYPE.  The application is then free to di‐
111       rectly modify the object.  In case of  a  failure  or  abort,  all  the
112       changes within the object will be rolled back.
113
114       The  TX_XADD_DIRECT() macro works exactly like TX_ADD_DIRECT when flags
115       equals 0.  The flags argument is a bitmask of values  as  described  in
116       pmemobj_tx_xadd_range_direct, above.
117
118       The  TX_SET()  macro  saves the current value of the given FIELD of the
119       object referenced by handle o in the undo log, and then  sets  its  new
120       VALUE.   In  case  of  a  failure or abort, the saved value will be re‐
121       stored.
122
123       The TX_SET_DIRECT() macro saves in the undo log the  current  value  of
124       given  FIELD  of  the object referenced by (direct) pointer p, and then
125       set its new VALUE.  In case of a failure or abort, the saved value will
126       be restored.
127
128       The TX_MEMCPY() macro saves in the undo log the current content of dest
129       buffer and then overwrites the first num bytes of its memory area  with
130       the  data  copied from the buffer pointed by src.  In case of a failure
131       or abort, the saved value will be restored.
132
133       The TX_MEMSET() macro saves the current content of the dest  buffer  in
134       the undo log and then fills the first num bytes of its memory area with
135       the constant byte c.  In case of a failure or abort,  the  saved  value
136       will be restored.
137

RETURN VALUE

139       On  success,  pmemobj_tx_add_range(),  pmemobj_tx_xadd_range(),  pmemo‐
140       bj_tx_add_range_direct() and pmemobj_tx_xadd_range_direct()  return  0.
141       Otherwise, the stage is changed to TX_STAGE_ONABORT and an error number
142       is returned.
143

SEE ALSO

145       pmemobj_tx_alloc(3),     pmemobj_tx_begin(3),     libpmemobj(7)     and
146       <http://pmem.io>
147
148
149
150PMDK - pmemobj API version 2.3    2018-07-18           PMEMOBJ_TX_ADD_RANGE(3)
Impressum