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(), POBJ_NEW(), POBJ_ALLOC(), POBJ_ZNEW(), POBJ_ZAL‐
9 LOC(), POBJ_REALLOC(), POBJ_ZREALLOC(), POBJ_FREE() - non-transactional
10 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 POBJ_NEW(PMEMobjpool *pop, TOID *oidp, TYPE, pmemobj_constr constructor,
35 void *arg)
36 POBJ_ALLOC(PMEMobjpool *pop, TOID *oidp, TYPE, size_t size,
37 pmemobj_constr constructor, void *arg)
38 POBJ_ZNEW(PMEMobjpool *pop, TOID *oidp, TYPE)
39 POBJ_ZALLOC(PMEMobjpool *pop, TOID *oidp, TYPE, size_t size)
40 POBJ_REALLOC(PMEMobjpool *pop, TOID *oidp, TYPE, size_t size)
41 POBJ_ZREALLOC(PMEMobjpool *pop, TOID *oidp, TYPE, size_t size)
42 POBJ_FREE(TOID *oidp)
43
45 Functions described in this document provide the mechanism to allocate,
46 resize and free objects from the persistent memory pool in a
47 thread-safe and fail-safe manner. All the routines are atomic with re‐
48 spect to other threads and any power-fail interruptions. If any of
49 these operations is torn by program failure or system crash, on recov‐
50 ery they are guaranteed to be entirely completed or discarded, leaving
51 the persistent memory heap and internal object containers in a consis‐
52 tent state.
53 All these functions can be used outside transactions. Note that opera‐
55 tions performed using the non-transactional API are considered durable
56 after completion, even if executed within an open transaction. Such
57 non-transactional changes will not be rolled back if the transaction is
58 aborted or interrupted.
59 The allocations are always aligned to a cache-line boundary.
61 The pmemobj_constr type represents a constructor for atomic allocation
63 from the persistent memory heap associated with memory pool pop. ptr
64 is a pointer to the allocated memory area and arg is a user-defined ar‐
65 gument passed to the constructor.
66 The pmemobj_alloc() function allocates a new object from the persistent
68 memory heap associated with memory pool pop. The PMEMoid of the allo‐
69 cated object is stored in oidp. If oidp is NULL, then the newly allo‐
70 cated object may be accessed only by iterating objects in the object
71 container associated with the type number type_num, as described in
72 POBJ_FOREACH(3). If oidp points to a memory location from the pmemobj
73 heap, oidp is modified atomically. Before returning, pmemobj_alloc()
74 calls the constructor function, passing the pool handle pop, the point‐
75 er to the newly allocated object in ptr, and the arg argument. It is
76 guaranteed that the allocated object is either properly initialized, or
77 if the allocation is interrupted before the constructor completes, the
78 memory space reserved for the object is reclaimed. size can be any
79 non-zero value; however, due to internal padding and object metadata,
80 the actual size of the allocation will differ from the requested size
81 by at least 64 bytes. For this reason, making allocations of a size
82 less than 64 bytes is extremely inefficient and discouraged. The allo‐
83 cated object is added to the internal container associated with
84 type_num.
85 pmemobj_xalloc() is equivalent to pmemobj_alloc(), but with an addi‐
87 tional flags argument that is a bitmask of the following values:
88 · POBJ_XALLOC_ZERO - zero the allocated object (equivalent of pmemo‐
90 bj_zalloc())
91 · POBJ_CLASS_ID(class_id) - allocate an object from the allocation
93 class class_id. The class id cannot be 0.
94 · POBJ_ARENA_ID(arena_id) - allocate an object from the arena specified
96 by arena_id. The arena must exist, otherwise, the behavior is unde‐
97 fined. If arena_id is equal 0, then arena assigned to the current
98 thread will be used.
99 The pmemobj_zalloc() function allocates a new zeroed object from the
101 persistent memory heap associated with memory pool pop. The PMEMoid of
102 the allocated object is stored in oidp. If oidp is NULL, then the new‐
103 ly allocated object may be accessed only by iterating objects in the
104 object container associated with the type number type_num, as described
105 in POBJ_FOREACH(3). If oidp points to a memory location from the pmem‐
106 obj heap, oidp is modified atomically. size can be any non-zero value;
107 however, due to internal padding and object metadata, the actual size
108 of the allocation will differ from the requested one by at least 64
109 bytes. For this reason, making allocations of a size less than 64
110 bytes is extremely inefficient and discouraged. The allocated object
111 is added to the internal container associated with type_num.
112 The pmemobj_free() function frees the memory space represented by oidp,
114 which must have been allocated by a previous call to pmemobj_alloc(),
115 pmemobj_xalloc(), pmemobj_zalloc(), pmemobj_realloc(), or pmemobj_zre‐
116 alloc(). pmemobj_free() provides the same semantics as free(3), but
117 instead of operating on the process heap supplied by the system, it op‐
118 erates on the persistent memory heap. If oidp is OID_NULL, no opera‐
119 tion is performed. If oidp is NULL or if it points to the root ob‐
120 ject's OID, the behavior of pmemobj_free() is undefined. oidp is set
121 to OID_NULL after the memory is freed. If oidp points to a memory lo‐
122 cation from the pmemobj heap, oidp is modified atomically.
123 The pmemobj_realloc() function changes the size of the object repre‐
125 sented by oidp to size bytes. pmemobj_realloc() provides similar se‐
126 mantics to realloc(3), but operates on the persistent memory heap asso‐
127 ciated with memory pool pop. The resized object is also added or moved
128 to the internal container associated with type number type_num. The
129 contents will be unchanged in the range from the start of the region up
130 to the minimum of the old and new sizes. If the new size is larger
131 than the old size, the added memory will not be initialized. If oidp
132 is OID_NULL, then the call is equivalent to pmemobj_alloc(pop, size,
133 type_num). If size is equal to zero, and oidp is not OID_NULL, then
134 the call is equivalent to pmemobj_free(oid). Unless oidp is OID_NULL,
135 it must have been allocated by an earlier call to pmemobj_alloc(),
136 pmemobj_xalloc(), pmemobj_zalloc(), pmemobj_realloc(), or pmemobj_zre‐
137 alloc(). Note that the object handle value may change as a result of
138 reallocation. If the object was moved, the memory space represented by
139 oid is reclaimed. If oidp points to a memory location from the pmemobj
140 heap, oidp is modified atomically. If oidp is NULL or if it points to
141 the root object's OID, the behavior of pmemobj_realloc() is undefined.
142 pmemobj_zrealloc() is equivalent to pmemobj_realloc(), except that if
144 the new size is larger than the old size, the added memory will be ze‐
145 roed.
146 The pmemobj_strdup() function stores a handle to a new object in oidp
148 which is a duplicate of the string s. pmemobj_strdup() provides the
149 same semantics as strdup(3), but operates on the persistent memory heap
150 associated with memory pool pop. If oidp is NULL, then the newly allo‐
151 cated object may be accessed only by iterating objects in the object
152 container associated with type number type_num, as described in
153 POBJ_FOREACH(3). If oidp points to a memory location from the pmemobj
154 heap, oidp is modified atomically. The allocated string object is also
155 added to the internal container associated with type number type_num.
156 Memory for the new string is obtained with pmemobj_alloc(), on the giv‐
157 en memory pool, and can be freed with pmemobj_free() on the same memory
158 pool.
159 pmemobj_wcsdup() is equivalent to pmemobj_strdup(), but operates on a
161 wide character string (wchar_t) rather than a standard character
162 string.
163 The pmemobj_alloc_usable_size() function provides the same semantics as
165 malloc_usable_size(3), but instead of the process heap supplied by the
166 system, it operates on the persistent memory heap.
167 The POBJ_NEW() macro is a wrapper around the pmemobj_alloc() function.
169 Instead of taking a pointer to PMEMoid, it takes a pointer to the typed
170 OID of type name TYPE, and passes the size and type number from the
171 typed OID to pmemobj_alloc().
172 The POBJ_ALLOC() macro is equivalent to POBJ_NEW, except that instead
174 of using the size of the typed OID, passes size to pmemobj_alloc().
175 The POBJ_ZNEW() macro is a wrapper around the pmemobj_zalloc() func‐
177 tion. Instead of taking a pointer to PMEMoid, it takes a pointer to
178 the typed OID of type name TYPE, and passes the size and type number
179 from the typed OID to pmemobj_zalloc().
180 The POBJ_ZALLOC() macro is equivalent to POBJ_ZNEW, except that instead
182 of using the size of the typed OID, passes size to pmemobj_zalloc().
183 The POBJ_REALLOC() macro is a wrapper around the pmemobj_realloc()
185 function. Instead of taking a pointer to PMEMoid, it takes a pointer
186 to the typed OID of type name TYPE, and passes the type number from the
187 typed OID to pmemobj_realloc().
188 The POBJ_ZREALLOC() macro is a wrapper around the pmemobj_zrealloc()
190 function. Instead of taking a pointer to PMEMoid, it takes a pointer
191 to the typed OID of type name TYPE, and passes the type number from the
192 typed OID to pmemobj_zrealloc().
193 The POBJ_FREE() macro is a wrapper around the pmemobj_free() function
195 which takes a pointer to the typed OID instead of to PMEMoid.
196
198 On success, pmemobj_alloc() and pmemobj_xalloc return 0. If oidp is
199 not NULL, the PMEMoid of the newly allocated object is stored in oidp.
200 If the allocation fails, -1 is returned and errno is set appropriately.
201 If the constructor returns a non-zero value, the allocation is can‐
202 celed, -1 is returned, and errno is set to ECANCELED. If size equals
203 0, or the flags for pmemobj_xalloc are invalid, -1 is returned, errno
204 is set to EINVAL, and oidp is left untouched.
205 On success, pmemobj_zalloc() returns 0. If oidp is not NULL, the PMEM‐
207 oid of the newly allocated object is stored in oidp. If the allocation
208 fails, it returns -1 and sets errno appropriately. If size equals 0,
209 it returns -1, sets errno to EINVAL, and leaves oidp untouched.
210 The pmemobj_free() function returns no value.
212 On success, pmemobj_realloc() and pmemobj_zrealloc() return 0 and up‐
214 date oidp if necessary. On error, they return -1 and set errno appro‐
215 priately.
216 On success, pmemobj_strdup() and pmemobj_wcsdup() return 0. If oidp is
218 not NULL, the PMEMoid of the duplicated string object is stored in
219 oidp. If s is NULL, they return -1, set errno to EINVAL, and leave
220 oidp untouched. On other errors, they return -1 and set errno appro‐
221 priately.
222 The pmemobj_alloc_usable_size() function returns the number of usable
224 bytes in the object represented by oid. If oid is OID_NULL, it returns
225 0.
226
228 free(3), POBJ_FOREACH(3), realloc(3), strdup(3), wcsdup(3), libpmemo‐
229 bj(7) and <http://pmem.io>
230PMDK - pmemobj API version 2.3 2019-03-01 PMEMOBJ_ALLOC(3)