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

NAME

6       pmemobj_tx_alloc(),  pmemobj_tx_zalloc(),  pmemobj_tx_xalloc(),  pmemo‐
7       bj_tx_realloc(),  pmemobj_tx_zrealloc(),  pmemobj_tx_strdup(),   pmemo‐
8       bj_tx_xstrdup(),   pmemobj_tx_wcsdup(),   pmemobj_tx_xwcsdup(),  pmemo‐
9       bj_tx_free(), pmemobj_tx_xfree()
10
11       TX_NEW(), TX_ALLOC(),  TX_ZNEW(),  TX_ZALLOC(),  TX_XALLOC(),  TX_REAL‐
12       LOC(),  TX_ZREALLOC(), TX_STRDUP(), TX_XSTRDUP(), TX_WCSDUP(), TX_XWCS‐
13       DUP(), TX_FREE(), TX_XFREE() - transactional object manipulation
14

SYNOPSIS

16              #include <libpmemobj.h>
17
18              PMEMoid pmemobj_tx_alloc(size_t size, uint64_t type_num);
19              PMEMoid pmemobj_tx_zalloc(size_t size, uint64_t type_num);
20              PMEMoid pmemobj_tx_xalloc(size_t size, uint64_t type_num, uint64_t flags);
21              PMEMoid pmemobj_tx_realloc(PMEMoid oid, size_t size, uint64_t type_num);
22              PMEMoid pmemobj_tx_zrealloc(PMEMoid oid, size_t size, uint64_t type_num);
23              PMEMoid pmemobj_tx_strdup(const char *s, uint64_t type_num);
24              PMEMoid pmemobj_tx_wcsdup(const wchar_t *s, uint64_t type_num);
25              int pmemobj_tx_free(PMEMoid oid);
26              int pmemobj_tx_xfree(PMEMoid oid, uint64_t flags);
27
28              TX_NEW(TYPE)
29              TX_ALLOC(TYPE, size_t size)
30              TX_ZNEW(TYPE)
31              TX_ZALLOC(TYPE, size_t size)
32              TX_XALLOC(TYPE, size_t size, uint64_t flags)
33              TX_REALLOC(TOID o, size_t size)
34              TX_ZREALLOC(TOID o, size_t size)
35              TX_STRDUP(const char *s, uint64_t type_num)
36              TX_WCSDUP(const wchar_t *s, uint64_t type_num)
37              TX_FREE(TOID o)
38              TX_XFREE(TOID o, uint64_t flags)
39

DESCRIPTION

41       The pmemobj_tx_alloc() function transactionally allocates a new  object
42       of given size and type_num.  In contrast to the non-transactional allo‐
43       cations, the objects are added to the  internal  object  containers  of
44       given  type_num only after the transaction is committed, making the ob‐
45       jects visible to the POBJ_FOREACH_*() macros.  This  function  must  be
46       called during TX_STAGE_WORK.
47
48       The pmemobj_tx_zalloc() function transactionally allocates a new zeroed
49       object of given size and type_num.  This function must be called during
50       TX_STAGE_WORK.
51
52       The pmemobj_tx_xalloc() function transactionally allocates a new object
53       of given size and type_num.  The flags argument is  a  bitmask  of  the
54       following values:
55
56POBJ_XALLOC_ZERO  -  zero  the allocated object (equivalent of pmemo‐
57         bj_tx_zalloc)
58
59POBJ_XALLOC_NO_FLUSH - skip flush on commit (when  application  deals
60         with flushing or uses pmemobj_memcpy_persist)
61
62POBJ_CLASS_ID(class_id)  -  allocate  an  object  from the allocation
63         class with id equal to class_id
64
65POBJ_ARENA_ID(arena_id) - allocate an object from the arena specified
66         by  arena_id.  The arena must exist, otherwise, the behavior is unde‐
67         fined.  If arena_id is equal 0, then arena assigned  to  the  current
68         thread will be used.
69
70POBJ_XALLOC_NO_ABORT  - if the function does not end successfully, do
71         not abort the transaction.
72
73       This function must be called during TX_STAGE_WORK.
74
75       The pmemobj_tx_realloc() function transactionally resizes  an  existing
76       object  to  the given size and changes its type to type_num.  If oid is
77       OID_NULL, then the call is equivalent  to  pmemobj_tx_alloc(pop,  size,
78       type_num).   If size is equal to zero and oid is not OID_NULL, then the
79       call is equivalent to pmemobj_tx_free(oid).  If the new size is  larger
80       than  the  old  size,  the  added memory will not be initialized.  This
81       function must be called during TX_STAGE_WORK.
82
83       The pmemobj_tx_zrealloc() function transactionally resizes an  existing
84       object  to the given size and changes its type to type_num.  If the new
85       size is larger than the old size, the extended  new  space  is  zeroed.
86       This function must be called during TX_STAGE_WORK.
87
88       The pmemobj_tx_strdup() function transactionally allocates a new object
89       containing a duplicate of the string s and assigns it a type  type_num.
90       This function must be called during TX_STAGE_WORK.
91
92       The  pmemobj_tx_xstrdup()  function  behaves exactly the same as pmemo‐
93       bj_tx_strdup() when flags equals zero.  The flags argument is a bitmask
94       of values described in pmemobj_tx_xalloc section.
95
96       The pmemobj_tx_wcsdup() function transactionally allocates a new object
97       containing a duplicate of the wide character string s and assigns it  a
98       type type_num.  This function must be called during TX_STAGE_WORK.
99
100       The  pmemobj_tx_xwcsdup()  function  behaves exactly the same as pmemo‐
101       bj_tx_wcsdup() when flags equals zero.  The flags argument is a bitmask
102       of values described in pmemobj_tx_xalloc section.
103
104       The pmemobj_tx_free() function transactionally frees an existing object
105       referenced by oid.  This function must be called during TX_STAGE_WORK.
106
107       The pmemobj_tx_xfree() function behaves  exactly  the  same  as  pmemo‐
108       bj_tx_free() when flags equals zero.  flags is a bitmask of the follow‐
109       ing value:
110
111POBJ_XFREE_NO_ABORT - if the function does not end  successfully,  do
112         not abort the transaction.
113
114       This function must be called during TX_STAGE_WORK.
115
116       The TX_NEW() macro transactionally allocates a new object of given TYPE
117       and assigns it a type number read from the typed OID.   The  allocation
118       size  is  determined  from the size of the user-defined structure TYPE.
119       If successful and called during TX_STAGE_WORK it returns  a  handle  to
120       the  newly  allocated  object.   Otherwise,  the  stage  is  changed to
121       TX_STAGE_ONABORT, OID_NULL is returned, and errno is set appropriately.
122
123       The TX_ALLOC() macro transactionally allocates a new  object  of  given
124       TYPE and assigns it a type number read from the typed OID.  The alloca‐
125       tion size is passed by size parameter.  If successful and called during
126       TX_STAGE_WORK  it returns a handle to the newly allocated object.  Oth‐
127       erwise, the stage is set to TX_STAGE_ONABORT, OID_NULL is returned, and
128       errno is set appropriately.
129
130       The  TX_ZNEW()  macro  transactionally allocates a new zeroed object of
131       given TYPE and assigns it a type number read from the typed  OID.   The
132       allocation  size is determined from the size of the user-defined struc‐
133       ture TYPE.  If successful and called during TX_STAGE_WORK it returns  a
134       handle  to  the  newly  allocated  object.  Otherwise, stage changes to
135       TX_STAGE_ONABORT, OID_NULL is returned, and errno is set appropriately.
136
137       The TX_ZALLOC() macro transactionally allocates a new zeroed object  of
138       given  TYPE  and assigns it a type number read from the typed OID.  The
139       allocation size is passed by size argument.  If successful  and  called
140       during TX_STAGE_WORK it returns a handle to the newly allocated object.
141       Otherwise, the stage is changed to TX_STAGE_ONABORT,  OID_NULL  is  re‐
142       turned, and errno is set appropriately.
143
144       The  TX_XALLOC()  macro transactionally allocates a new object of given
145       TYPE and assigns it a type number read from the typed OID.  The alloca‐
146       tion  size is passed by size argument.  The flags argument is a bitmask
147       of values described in pmemobj_tx_xalloc section.   If  successful  and
148       called  during TX_STAGE_WORK it returns a handle to the newly allocated
149       object.  Otherwise, the OID_NULL is returned, errno  is  set  and  when
150       flags do not contain POBJ_XALLOC_NO_ABORT, the transaction is aborted.
151
152       The  TX_REALLOC() macro transactionally resizes an existing object ref‐
153       erenced by a handle o to the given size.  If successful and called dur‐
154       ing  TX_STAGE_WORK it returns a handle to the reallocated object.  Oth‐
155       erwise, the stage is changed to TX_STAGE_ONABORT, OID_NULL is returned,
156       and errno is set appropriately.
157
158       The TX_ZREALLOC() macro transactionally resizes an existing object ref‐
159       erenced by a handle o to the given size.  If the  new  size  is  larger
160       than the old size, the extended new space is zeroed.  If successful and
161       called during TX_STAGE_WORK it returns a handle to the reallocated  ob‐
162       ject.  Otherwise, the stage is changed to TX_STAGE_ONABORT, OID_NULL is
163       returned, and errno is set appropriately.
164
165       The TX_STRDUP() macro transactionally allocates a new object containing
166       a  duplicate of the string s and assigns it type type_num.  If success‐
167       ful and called during TX_STAGE_WORK it returns a handle  to  the  newly
168       allocated object.  Otherwise, the stage is changed to TX_STAGE_ONABORT,
169       OID_NULL is returned, and errno is set appropriately.
170
171       The TX_XSTRDUP() macro transactionally allocates a new object  contain‐
172       ing  a  duplicate  of  the  string s and assigns it type type_num.  The
173       flags argument is a bitmask of values  described  in  pmemobj_tx_xalloc
174       section.   If  successful  and called during TX_STAGE_WORK it returns a
175       handle to the newly allocated object.  Otherwise, the OID_NULL  is  re‐
176       turned,   errno  is  set  and  when  flags  do  not  contain  POBJ_XAL‐
177       LOC_NO_ABORT, the transaction is aborted.
178
179       The TX_WCSDUP() macro transactionally allocates a new object containing
180       a  duplicate  of  the  wide  character  string  s and assigns it a type
181       type_num.  If successful and called during TX_STAGE_WORK, it returns  a
182       handle  to the newly allocated object.  Otherwise, the stage is changed
183       to TX_STAGE_ONABORT, OID_NULL is returned, and errno is  set  appropri‐
184       ately.
185
186       The  TX_XWCSDUP() macro transactionally allocates a new object contain‐
187       ing a duplicate of the wide character string s and assigns  it  a  type
188       type_num.  The flags argument is a bitmask of values described in pmem‐
189       obj_tx_xalloc section.  If successful and called  during  TX_STAGE_WORK
190       it  returns  a  handle  to  the newly allocated object.  Otherwise, the
191       OID_NULL is returned, errno is  set  and  when  flags  do  not  contain
192       POBJ_XALLOC_NO_ABORT, the transaction is aborted.
193
194       The  TX_FREE() macro transactionally frees the memory space represented
195       by an object handle o.  If o is OID_NULL, no  operation  is  performed.
196       If  successful  and  called  during TX_STAGE_WORK, TX_FREE() returns 0.
197       Otherwise, the stage is changed to TX_STAGE_ONABORT and  errno  is  set
198       appropriately.
199
200       The TX_XFREE() macro transactionally frees the memory space represented
201       by an object handle o.  If o is OID_NULL, no  operation  is  performed.
202       The flags argument is a bitmask of values described in pmemobj_tx_xfree
203       section.  If successful and called during TX_STAGE_WORK, TX_FREE()  re‐
204       turns  0.   Otherwise,  the  error number is returned, errno is set and
205       when flags do  not  contain  POBJ_XFREE_NO_ABORT,  the  transaction  is
206       aborted.
207

RETURN VALUE

209       On   success,   the   pmemobj_tx_alloc(),  pmemobj_tx_zalloc(),  pmemo‐
210       bj_tx_strdup() and pmemobj_tx_wcsdup() functions return a handle to the
211       newly   allocated   object.    Otherwise,   the  stage  is  changed  to
212       TX_STAGE_ONABORT, OID_NULL is returned, and errno is set appropriately.
213       If size equals 0, OID_NULL is returned and errno is set appropriately.
214
215       On  success,  the  pmemobj_tx_xalloc(), pmemobj_tx_xstrdup() and pmemo‐
216       bj_tx_xwcsdup() functions return a handle to the  newly  allocated  ob‐
217       ject.  Otherwise, the OID_NULL is returned, errno is set and when flags
218       do not contain POBJ_XALLOC_NO_ABORT, the transaction is aborted.
219
220       On success, pmemobj_tx_realloc()  and  pmemobj_tx_zrealloc()  return  a
221       handle  to  the  resized  object.   Otherwise,  the stage is changed to
222       TX_STAGE_ONABORT, OID_NULL is returned, and errno is set appropriately.
223       Note  that  the object handle value may change as a result of realloca‐
224       tion.
225
226       On success, pmemobj_tx_free()  returns  0.   Otherwise,  the  stage  is
227       changed to TX_STAGE_ONABORT, errno is set appropriately and transaction
228       is aborted
229
230       On success pmemobj_tx_xfree() returns 0.  Otherwise, the  error  number
231       is   returned,   errno   is   set   and   when  flags  do  not  contain
232       POBJ_XFREE_NO_ABORT, the transaction is aborted.
233

SEE ALSO

235       pmemobj_tx_add_range(3),   pmemobj_tx_begin(3),    libpmemobj(7)    and
236       <https://pmem.io>
237
238
239
240PMDK - pmemobj API version 2.3    2022-08-25               PMEMOBJ_TX_ALLOC(3)
Impressum