1PMEMOBJ_TX_ALLOC(3) PMDK Programmer's Manual PMEMOBJ_TX_ALLOC(3)
2
3
4
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_wcsdup(), pmemobj_tx_free(),
9
10 TX_NEW(), TX_ALLOC(), TX_ZNEW(), TX_ZALLOC(), TX_XALLOC(), TX_REAL‐
11 LOC(), TX_ZREALLOC(), TX_STRDUP(), TX_WCSDUP(), TX_FREE() - transac‐
12 tional object manipulation
13
15 #include <libpmemobj.h>
16
17 PMEMoid pmemobj_tx_alloc(size_t size, uint64_t type_num);
18 PMEMoid pmemobj_tx_zalloc(size_t size, uint64_t type_num);
19 PMEMoid pmemobj_tx_xalloc(size_t size, uint64_t type_num, uint64_t flags);
20 PMEMoid pmemobj_tx_realloc(PMEMoid oid, size_t size, uint64_t type_num);
21 PMEMoid pmemobj_tx_zrealloc(PMEMoid oid, size_t size, uint64_t type_num);
22 PMEMoid pmemobj_tx_strdup(const char *s, uint64_t type_num);
23 PMEMoid pmemobj_tx_wcsdup(const wchar_t *s, uint64_t type_num);
24 int pmemobj_tx_free(PMEMoid oid);
25
26 TX_NEW(TYPE)
27 TX_ALLOC(TYPE, size_t size)
28 TX_ZNEW(TYPE)
29 TX_ZALLOC(TYPE, size_t size)
30 TX_XALLOC(TYPE, size_t size, uint64_t flags)
31 TX_REALLOC(TOID o, size_t size)
32 TX_ZREALLOC(TOID o, size_t size)
33 TX_STRDUP(const char *s, uint64_t type_num)
34 TX_WCSDUP(const wchar_t *s, uint64_t type_num)
35 TX_FREE(TOID o)
36
38 The pmemobj_tx_alloc() function transactionally allocates a new object
39 of given size and type_num. In contrast to the non-transactional allo‐
40 cations, the objects are added to the internal object containers of
41 given type_num only after the transaction is committed, making the ob‐
42 jects visible to the POBJ_FOREACH_*() macros. This function must be
43 called during TX_STAGE_WORK.
44
45 The pmemobj_tx_zalloc() function transactionally allocates a new zeroed
46 object of given size and type_num. This function must be called during
47 TX_STAGE_WORK.
48
49 The pmemobj_tx_xalloc() function transactionally allocates a new object
50 of given size and type_num. The flags argument is a bitmask of the
51 following values:
52
53 · POBJ_XALLOC_ZERO - zero the allocated object (equivalent of pmemo‐
54 bj_tx_zalloc)
55
56 · POBJ_XALLOC_NO_FLUSH - skip flush on commit (when application deals
57 with flushing or uses pmemobj_memcpy_persist)
58
59 · POBJ_CLASS_ID(class_id) - allocate an object from the allocation
60 class with id equal to class_id
61
62 · POBJ_ARENA_ID(arena_id) - allocate an object from the arena specified
63 by arena_id. The arena must exist, otherwise, the behavior is unde‐
64 fined. If arena_id is equal 0, then arena assigned to the current
65 thread will be used.
66
67 This function must be called during TX_STAGE_WORK.
68
69 The pmemobj_tx_realloc() function transactionally resizes an existing
70 object to the given size and changes its type to type_num. If oid is
71 OID_NULL, then the call is equivalent to pmemobj_tx_alloc(pop, size,
72 type_num). If size is equal to zero and oid is not OID_NULL, then the
73 call is equivalent to pmemobj_tx_free(oid). If the new size is larger
74 than the old size, the added memory will not be initialized. This
75 function must be called during TX_STAGE_WORK.
76
77 The pmemobj_tx_zrealloc() function transactionally resizes an existing
78 object to the given size and changes its type to type_num. If the new
79 size is larger than the old size, the extended new space is zeroed.
80 This function must be called during TX_STAGE_WORK.
81
82 The pmemobj_tx_strdup() function transactionally allocates a new object
83 containing a duplicate of the string s and assigns it a type type_num.
84 This function must be called during TX_STAGE_WORK.
85
86 The pmemobj_tx_wcsdup() function transactionally allocates a new object
87 containing a duplicate of the wide character string s and assigns it a
88 type type_num. This function must be called during TX_STAGE_WORK.
89
90 The pmemobj_tx_free() function transactionally frees an existing object
91 referenced by oid. This function must be called during TX_STAGE_WORK.
92
93 The TX_NEW() macro transactionally allocates a new object of given TYPE
94 and assigns it a type number read from the typed OID. The allocation
95 size is determined from the size of the user-defined structure TYPE.
96 If successful and called during TX_STAGE_WORK it returns a handle to
97 the newly allocated object. Otherwise, the stage is changed to
98 TX_STAGE_ONABORT, OID_NULL is returned, and errno is set appropriately.
99
100 The TX_ALLOC() macro transactionally allocates a new object of given
101 TYPE and assigns it a type number read from the typed OID. The alloca‐
102 tion size is passed by size parameter. If successful and called during
103 TX_STAGE_WORK it returns a handle to the newly allocated object. Oth‐
104 erwise, the stage is set to TX_STAGE_ONABORT, OID_NULL is returned, and
105 errno is set appropriately.
106
107 The TX_ZNEW() macro transactionally allocates a new zeroed object of
108 given TYPE and assigns it a type number read from the typed OID. The
109 allocation size is determined from the size of the user-defined struc‐
110 ture TYPE. If successful and called during TX_STAGE_WORK it returns a
111 handle to the newly allocated object. Otherwise, stage changes to
112 TX_STAGE_ONABORT, OID_NULL is returned, and errno is set appropriately.
113
114 The TX_ZALLOC() macro transactionally allocates a new zeroed object of
115 given TYPE and assigns it a type number read from the typed OID. The
116 allocation size is passed by size argument. If successful and called
117 during TX_STAGE_WORK it returns a handle to the newly allocated object.
118 Otherwise, the stage is changed to TX_STAGE_ONABORT, OID_NULL is re‐
119 turned, and errno is set appropriately.
120
121 The TX_XALLOC() macro transactionally allocates a new object of given
122 TYPE and assigns it a type number read from the typed OID. The alloca‐
123 tion size is passed by size argument. The flags argument is a bitmask
124 of values described in pmemobj_tx_xalloc section. If successful and
125 called during TX_STAGE_WORK it returns a handle to the newly allocated
126 object. Otherwise, the stage is changed to TX_STAGE_ONABORT, OID_NULL
127 is returned, and errno is set appropriately.
128
129 The TX_REALLOC() macro transactionally resizes an existing object ref‐
130 erenced by a handle o to the given size. If successful and called dur‐
131 ing TX_STAGE_WORK it returns a handle to the reallocated object. Oth‐
132 erwise, the stage is changed to TX_STAGE_ONABORT, OID_NULL is returned,
133 and errno is set appropriately.
134
135 The TX_ZREALLOC() macro transactionally resizes an existing object ref‐
136 erenced by a handle o to the given size. If the new size is larger
137 than the old size, the extended new space is zeroed. If successful and
138 called during TX_STAGE_WORK it returns a handle to the reallocated ob‐
139 ject. Otherwise, the stage is changed to TX_STAGE_ONABORT, OID_NULL is
140 returned, and errno is set appropriately.
141
142 The TX_STRDUP() macro transactionally allocates a new object containing
143 a duplicate of the string s and assigns it type type_num. If success‐
144 ful and called during TX_STAGE_WORK it returns a handle to the newly
145 allocated object. Otherwise, the stage is changed to TX_STAGE_ONABORT,
146 OID_NULL is returned, and errno is set appropriately.
147
148 The TX_WCSDUP() macro transactionally allocates a new object containing
149 a duplicate of the wide character string s and assigns it a type
150 type_num. If successful and called during TX_STAGE_WORK, it returns a
151 handle to the newly allocated object. Otherwise, the stage is changed
152 to TX_STAGE_ONABORT, OID_NULL is returned, and errno is set appropri‐
153 ately.
154
155 The TX_FREE() macro transactionally frees the memory space represented
156 by an object handle o. If o is OID_NULL, no operation is performed.
157 If successful and called during TX_STAGE_WORK, TX_FREE() returns 0.
158 Otherwise, the stage is changed to TX_STAGE_ONABORT and an error number
159 is returned.
160
162 On success, the pmemobj_tx_alloc() ,pmemobj_tx_zalloc(), pmemo‐
163 bj_tx_xalloc(), pmemobj_tx_strdup() and pmemobj_tx_wcsdup() functions
164 return a handle to the newly allocated object. Otherwise, the stage is
165 changed to TX_STAGE_ONABORT, OID_NULL is returned, and errno is set ap‐
166 propriately. If size equals 0, OID_NULL is returned and errno is set
167 appropriately.
168
169 On success, pmemobj_tx_realloc() and pmemobj_tx_zrealloc() return a
170 handle to the resized object. Otherwise, the stage is changed to
171 TX_STAGE_ONABORT, OID_NULL is returned, and errno is set appropriately.
172 Note that the object handle value may change as a result of realloca‐
173 tion.
174
175 On success, pmemobj_tx_free() returns 0. Otherwise, the stage is set
176 to TX_STAGE_ONABORT and an error number is returned.
177
179 pmemobj_tx_add_range(3), **pmemobj_tx_begin*(3), libpmemobj(7) and
180 <http://pmem.io>
181
182
183
184PMDK - pmemobj API version 2.3 2019-07-10 PMEMOBJ_TX_ALLOC(3)