1PMEMOBJ_TX_ALLOC(3) PMDK Programmer's Manual PMEMOBJ_TX_ALLOC(3)
2
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 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
16 #include <libpmemobj.h>
17 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 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
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 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 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 · POBJ_XALLOC_ZERO - zero the allocated object (equivalent of pmemo‐
57 bj_tx_zalloc)
58 · POBJ_XALLOC_NO_FLUSH - skip flush on commit (when application deals
60 with flushing or uses pmemobj_memcpy_persist)
61 · POBJ_CLASS_ID(class_id) - allocate an object from the allocation
63 class with id equal to class_id
64 · POBJ_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 · POBJ_XALLOC_NO_ABORT - if the function does not end successfully, do
71 not abort the transaction.
72 This function must be called during TX_STAGE_WORK.
74 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 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 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 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 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 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 The pmemobj_tx_free() function transactionally frees an existing object
105 referenced by oid. This function must be called during TX_STAGE_WORK.
106 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 · POBJ_XFREE_NO_ABORT - if the function does not end successfully, do
112 not abort the transaction.
113 This function must be called during TX_STAGE_WORK.
115 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 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 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 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 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 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 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 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 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 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 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 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 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
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 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 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 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 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
235 pmemobj_tx_add_range(3), pmemobj_tx_begin(3), libpmemobj(7) and
236 <https://pmem.io>
237PMDK - pmemobj API version 2.3 2020-07-03 PMEMOBJ_TX_ALLOC(3)