1PMEMOBJ_ALLOC(3) PMDK Programmer's Manual PMEMOBJ_ALLOC(3)
2
6 pmemobj_alloc(), pmemobj_xalloc(), pmemobj_zalloc(), pmemobj_realloc(),
7 pmemobj_zrealloc(), pmemobj_strdup(), pmemobj_wcsdup(), pmemobj_al‐
8 loc_usable_size(), pmemobj_defrag(), POBJ_NEW(), POBJ_ALLOC(),
9 POBJ_ZNEW(), POBJ_ZALLOC(), POBJ_REALLOC(), POBJ_ZREALLOC(),
10 POBJ_FREE() - non-transactional atomic allocations
11
13 #include <libpmemobj.h>
14 typedef int (*pmemobj_constr)(**PMEMobjpool *pop, void *ptr, void *arg);
16 int pmemobj_alloc(PMEMobjpool *pop, PMEMoid *oidp, size_t size,
17 uint64_t type_num, pmemobj_constr constructor, void *arg);
18 int pmemobj_xalloc(PMEMobjpool *pop, PMEMoid *oidp, size_t size,
19 uint64_t type_num, uint64_t flags, pmemobj_constr constructor,
20 void *arg); (EXPERIMENTAL)
21 int pmemobj_zalloc(PMEMobjpool *pop, PMEMoid *oidp, size_t size,
22 uint64_t type_num);
23 void pmemobj_free(PMEMoid *oidp);
24 int pmemobj_realloc(PMEMobjpool *pop, PMEMoid *oidp, size_t size,
25 uint64_t type_num);
26 int pmemobj_zrealloc(PMEMobjpool *pop, PMEMoid *oidp, size_t size,
27 uint64_t type_num);
28 int pmemobj_strdup(PMEMobjpool *pop, PMEMoid *oidp, const char *s,
29 uint64_t type_num);
30 int pmemobj_wcsdup(PMEMobjpool *pop, PMEMoid *oidp, const wchar_t *s,
31 uint64_t type_num);
32 size_t pmemobj_alloc_usable_size(PMEMoid oid);
33 int pmemobj_defrag(PMEMobjpool *pop, PMEMoid **oidv, size_t oidcnt,
34 struct pobj_defrag_result *result);
35 POBJ_NEW(PMEMobjpool *pop, TOID *oidp, TYPE, pmemobj_constr constructor,
37 void *arg)
38 POBJ_ALLOC(PMEMobjpool *pop, TOID *oidp, TYPE, size_t size,
39 pmemobj_constr constructor, void *arg)
40 POBJ_ZNEW(PMEMobjpool *pop, TOID *oidp, TYPE)
41 POBJ_ZALLOC(PMEMobjpool *pop, TOID *oidp, TYPE, size_t size)
42 POBJ_REALLOC(PMEMobjpool *pop, TOID *oidp, TYPE, size_t size)
43 POBJ_ZREALLOC(PMEMobjpool *pop, TOID *oidp, TYPE, size_t size)
44 POBJ_FREE(TOID *oidp)
45
47 Functions described in this document provide the mechanism to allocate,
48 resize and free objects from the persistent memory pool in a
49 thread-safe and fail-safe manner. All the routines are atomic with re‐
50 spect to other threads and any power-fail interruptions. If any of
51 these operations is torn by program failure or system crash, on recov‐
52 ery they are guaranteed to be entirely completed or discarded, leaving
53 the persistent memory heap and internal object containers in a consis‐
54 tent state.
55 All these functions should be used outside transactions. If executed
57 within an open transaction they are considered durable immediately af‐
58 ter completion. Changes made with these functions will not be rolled
59 back if the transaction is aborted or interrupted. They have no infor‐
60 mation about other changes made by transactional API, so if the same
61 data is modified in a single transaction using transactional and then
62 non-transactional API, transaction abort will likely corrupt the data.
63 The allocations are always aligned to a cache-line boundary.
65 The pmemobj_constr type represents a constructor for atomic allocation
67 from the persistent memory heap associated with memory pool pop. ptr
68 is a pointer to the allocated memory area and arg is a user-defined ar‐
69 gument passed to the constructor.
70 The pmemobj_alloc() function allocates a new object from the persistent
72 memory heap associated with memory pool pop. The PMEMoid of the allo‐
73 cated object is stored in oidp. If oidp is NULL, then the newly allo‐
74 cated object may be accessed only by iterating objects in the object
75 container associated with the type number type_num, as described in
76 POBJ_FOREACH(3). If oidp points to a memory location from the pmemobj
77 heap, oidp is modified atomically. Before returning, pmemobj_alloc()
78 calls the constructor function, passing the pool handle pop, the point‐
79 er to the newly allocated object in ptr, and the arg argument. It is
80 guaranteed that the allocated object is either properly initialized, or
81 if the allocation is interrupted before the constructor completes, the
82 memory space reserved for the object is reclaimed. size can be any
83 non-zero value; however, due to internal padding and object metadata,
84 the actual size of the allocation will differ from the requested size
85 by at least 64 bytes. For this reason, making allocations of a size
86 less than 64 bytes is extremely inefficient and discouraged. The allo‐
87 cated object is added to the internal container associated with
88 type_num.
89 pmemobj_xalloc() is equivalent to pmemobj_alloc(), but with an addi‐
91 tional flags argument that is a bitmask of the following values:
92 • POBJ_XALLOC_ZERO - zero the allocated object (equivalent of pmemo‐
94 bj_zalloc())
95 • POBJ_CLASS_ID(class_id) - allocate an object from the allocation
97 class class_id. The class id cannot be 0.
98 • POBJ_ARENA_ID(arena_id) - allocate an object from the arena specified
100 by arena_id. The arena must exist, otherwise, the behavior is unde‐
101 fined. If arena_id is equal 0, then arena assigned to the current
102 thread will be used.
103 The pmemobj_zalloc() function allocates a new zeroed object from the
105 persistent memory heap associated with memory pool pop. The PMEMoid of
106 the allocated object is stored in oidp. If oidp is NULL, then the new‐
107 ly allocated object may be accessed only by iterating objects in the
108 object container associated with the type number type_num, as described
109 in POBJ_FOREACH(3). If oidp points to a memory location from the pmem‐
110 obj heap, oidp is modified atomically. size can be any non-zero value;
111 however, due to internal padding and object metadata, the actual size
112 of the allocation will differ from the requested one by at least 64
113 bytes. For this reason, making allocations of a size less than 64
114 bytes is extremely inefficient and discouraged. The allocated object
115 is added to the internal container associated with type_num.
116 The pmemobj_free() function frees the memory space represented by oidp,
118 which must have been allocated by a previous call to pmemobj_alloc(),
119 pmemobj_xalloc(), pmemobj_zalloc(), pmemobj_realloc(), or pmemobj_zre‐
120 alloc(). pmemobj_free() provides the same semantics as free(3), but
121 instead of operating on the process heap supplied by the system, it op‐
122 erates on the persistent memory heap. If oidp is OID_NULL, no opera‐
123 tion is performed. If oidp is NULL or if it points to the root ob‐
124 ject's OID, the behavior of pmemobj_free() is undefined. oidp is set
125 to OID_NULL after the memory is freed. If oidp points to a memory lo‐
126 cation from the pmemobj heap, oidp is modified atomically.
127 The pmemobj_realloc() function changes the size of the object repre‐
129 sented by oidp to size bytes. pmemobj_realloc() provides similar se‐
130 mantics to realloc(3), but operates on the persistent memory heap asso‐
131 ciated with memory pool pop. The resized object is also added or moved
132 to the internal container associated with type number type_num. The
133 contents will be unchanged in the range from the start of the region up
134 to the minimum of the old and new sizes. If the new size is larger
135 than the old size, the added memory will not be initialized. If oidp
136 is OID_NULL, then the call is equivalent to pmemobj_alloc(pop, size,
137 type_num). If size is equal to zero, and oidp is not OID_NULL, then
138 the call is equivalent to pmemobj_free(oid). Unless oidp is OID_NULL,
139 it must have been allocated by an earlier call to pmemobj_alloc(),
140 pmemobj_xalloc(), pmemobj_zalloc(), pmemobj_realloc(), or pmemobj_zre‐
141 alloc(). Note that the object handle value may change as a result of
142 reallocation. If the object was moved, the memory space represented by
143 oid is reclaimed. If oidp points to a memory location from the pmemobj
144 heap, oidp is modified atomically. If oidp is NULL or if it points to
145 the root object's OID, the behavior of pmemobj_realloc() is undefined.
146 pmemobj_zrealloc() is equivalent to pmemobj_realloc(), except that if
148 the new size is larger than the old size, the added memory will be ze‐
149 roed.
150 The pmemobj_strdup() function stores a handle to a new object in oidp
152 which is a duplicate of the string s. pmemobj_strdup() provides the
153 same semantics as strdup(3), but operates on the persistent memory heap
154 associated with memory pool pop. If oidp is NULL, then the newly allo‐
155 cated object may be accessed only by iterating objects in the object
156 container associated with type number type_num, as described in
157 POBJ_FOREACH(3). If oidp points to a memory location from the pmemobj
158 heap, oidp is modified atomically. The allocated string object is also
159 added to the internal container associated with type number type_num.
160 Memory for the new string is obtained with pmemobj_alloc(), on the giv‐
161 en memory pool, and can be freed with pmemobj_free() on the same memory
162 pool.
163 pmemobj_wcsdup() is equivalent to pmemobj_strdup(), but operates on a
165 wide character string (wchar_t) rather than a standard character
166 string.
167 The pmemobj_alloc_usable_size() function provides the same semantics as
169 malloc_usable_size(3), but instead of the process heap supplied by the
170 system, it operates on the persistent memory heap.
171 The POBJ_NEW() macro is a wrapper around the pmemobj_alloc() function.
173 Instead of taking a pointer to PMEMoid, it takes a pointer to the typed
174 OID of type name TYPE, and passes the size and type number from the
175 typed OID to pmemobj_alloc().
176 The POBJ_ALLOC() macro is equivalent to POBJ_NEW, except that instead
178 of using the size of the typed OID, passes size to pmemobj_alloc().
179 The POBJ_ZNEW() macro is a wrapper around the pmemobj_zalloc() func‐
181 tion. Instead of taking a pointer to PMEMoid, it takes a pointer to
182 the typed OID of type name TYPE, and passes the size and type number
183 from the typed OID to pmemobj_zalloc().
184 The POBJ_ZALLOC() macro is equivalent to POBJ_ZNEW, except that instead
186 of using the size of the typed OID, passes size to pmemobj_zalloc().
187 The POBJ_REALLOC() macro is a wrapper around the pmemobj_realloc()
189 function. Instead of taking a pointer to PMEMoid, it takes a pointer
190 to the typed OID of type name TYPE, and passes the type number from the
191 typed OID to pmemobj_realloc().
192 The POBJ_ZREALLOC() macro is a wrapper around the pmemobj_zrealloc()
194 function. Instead of taking a pointer to PMEMoid, it takes a pointer
195 to the typed OID of type name TYPE, and passes the type number from the
196 typed OID to pmemobj_zrealloc().
197 The POBJ_FREE() macro is a wrapper around the pmemobj_free() function
199 which takes a pointer to the typed OID instead of to PMEMoid.
200 The pmemobj_defrag() function performs defragmentation on the objects
202 provided through the array of pointers to PMEMoids oidv with size oidc‐
203 nt. If an object from the provided array is selected to be moved to a
204 new location in the heap, it is reallocated and all provided pointers
205 to that object are atomically updated. To maintain data structure con‐
206 sistency, applications should always provide all pointers for an object
207 to pmemobj_defrag method. This ensures that, even in the presence of
208 failures, all pointers to the object will either point to the old or a
209 new location. All objects and pointers to objects should belong to the
210 pool pop or, in case of pointers, can also reside in volatile memory.
211 Defragmentation across pools is not supported. Objects in the array
212 that are OID_NULL are skipped over and no operation is performed on
213 them. All other objects must have been allocated by an earlier call to
214 pmemobj_alloc(), pmemobj_xalloc(), pmemobj_zalloc(), pmemobj_realloc(),
215 pmemobj_zrealloc(), pmemobj_strdup() or pmemobj_wcsdup(). The result
216 variable is an instance of struct pobj_defrag_result and, if not NULL,
217 can be used to read total, the number of objects found that were pro‐
218 cessed, and relocated, the number of objects that were relocated during
219 defragmentation. These variables are always initialized and can be
220 non-zero, even if the return value of pmemobj_defrag() indicated a
221 failure. This is because the failure might have occurred after some
222 objects were already processed.
223
225 On success, pmemobj_alloc() and pmemobj_xalloc return 0. If oidp is
226 not NULL, the PMEMoid of the newly allocated object is stored in oidp.
227 If the allocation fails, -1 is returned and errno is set appropriately.
228 If the constructor returns a non-zero value, the allocation is can‐
229 celed, -1 is returned, and errno is set to ECANCELED. If size equals
230 0, or the flags for pmemobj_xalloc are invalid, -1 is returned, errno
231 is set to EINVAL, and oidp is left untouched.
232 On success, pmemobj_zalloc() returns 0. If oidp is not NULL, the PMEM‐
234 oid of the newly allocated object is stored in oidp. If the allocation
235 fails, it returns -1 and sets errno appropriately. If size equals 0,
236 it returns -1, sets errno to EINVAL, and leaves oidp untouched.
237 The pmemobj_free() function returns no value.
239 On success, pmemobj_realloc() and pmemobj_zrealloc() return 0 and up‐
241 date oidp if necessary. On error, they return -1 and set errno appro‐
242 priately.
243 On success, pmemobj_strdup() and pmemobj_wcsdup() return 0. If oidp is
245 not NULL, the PMEMoid of the duplicated string object is stored in
246 oidp. If s is NULL, they return -1, set errno to EINVAL, and leave
247 oidp untouched. On other errors, they return -1 and set errno appro‐
248 priately.
249 The pmemobj_alloc_usable_size() function returns the number of usable
251 bytes in the object represented by oid. If oid is OID_NULL, it returns
252 0.
253 On success, pmemobj_defrag() returns 0. If defragmentation was unsuc‐
255 cessful or only partially successful (i.e. if it was aborted halfway
256 through due to lack of resources), -1 is returned.
257
259 free(3), POBJ_FOREACH(3), realloc(3), strdup(3), wcsdup(3), libpmemo‐
260 bj(7) and <https://pmem.io>
261PMDK - pmemobj API version 2.3 2022-08-25 PMEMOBJ_ALLOC(3)