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