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-transaction‐
10 al 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);
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 object (equivalent of pmemobj_zalloc())
90 · POBJ_CLASS_ID(class_id) - allocate the object from allocation class
92 class_id. The class id cannot be 0.
93 The pmemobj_zalloc() function allocates a new zeroed object from the
95 persistent memory heap associated with memory pool pop. The PMEMoid of
96 the allocated object is stored in oidp. If oidp is NULL, then the new‐
97 ly allocated object may be accessed only by iterating objects in the
98 object container associated with the type number type_num, as described
99 in POBJ_FOREACH(3). If oidp points to a memory location from the pmem‐
100 obj heap, oidp is modified atomically. size can be any non-zero value;
101 however, due to internal padding and object metadata, the actual size
102 of the allocation will differ from the requested one by at least 64
103 bytes. For this reason, making allocations of a size less than 64
104 bytes is extremely inefficient and discouraged. The allocated object
105 is added to the internal container associated with type_num.
106 The pmemobj_free() function frees the memory space represented by oidp,
108 which must have been allocated by a previous call to pmemobj_alloc(),
109 pmemobj_xalloc(), pmemobj_zalloc(), pmemobj_realloc(), or pmemobj_zre‐
110 alloc(). pmemobj_free() provides the same semantics as free(3), but
111 instead of operating on the process heap supplied by the system, it op‐
112 erates on the persistent memory heap. If oidp is OID_NULL, no opera‐
113 tion is performed. If oidp is NULL or if it points to the root ob‐
114 ject's OID, the behavior of pmemobj_free() is undefined. oidp is set
115 to OID_NULL after the memory is freed. If oidp points to a memory lo‐
116 cation from the pmemobj heap, oidp is modified atomically.
117 The pmemobj_realloc() function changes the size of the object repre‐
119 sented by oidp to size bytes. pmemobj_realloc() provides similar se‐
120 mantics to realloc(3), but operates on the persistent memory heap asso‐
121 ciated with memory pool pop. The resized object is also added or moved
122 to the internal container associated with type number type_num. The
123 contents will be unchanged in the range from the start of the region up
124 to the minimum of the old and new sizes. If the new size is larger
125 than the old size, the added memory will not be initialized. If oidp
126 is OID_NULL, then the call is equivalent to pmemobj_alloc(pop, size,
127 type_num). If size is equal to zero, and oidp is not OID_NULL, then
128 the call is equivalent to pmemobj_free(oid). Unless oidp is OID_NULL,
129 it must have been allocated by an earlier call to pmemobj_alloc(),
130 pmemobj_xalloc(), pmemobj_zalloc(), pmemobj_realloc(), or pmemobj_zre‐
131 alloc(). Note that the object handle value may change as a result of
132 reallocation. If the object was moved, the memory space represented by
133 oid is reclaimed. If oidp points to a memory location from the pmemobj
134 heap, oidp is modified atomically. If oidp is NULL or if it points to
135 the root object's OID, the behavior of pmemobj_realloc() is undefined.
136 pmemobj_zrealloc() is equivalent to pmemobj_realloc(), except that if
138 the new size is larger than the old size, the added memory will be ze‐
139 roed.
140 The pmemobj_strdup() function stores a handle to a new object in oidp
142 which is a duplicate of the string s. pmemobj_strdup() provides the
143 same semantics as strdup(3), but operates on the persistent memory heap
144 associated with memory pool pop. If oidp is NULL, then the newly allo‐
145 cated object may be accessed only by iterating objects in the object
146 container associated with type number type_num, as described in
147 POBJ_FOREACH(3). If oidp points to a memory location from the pmemobj
148 heap, oidp is modified atomically. The allocated string object is also
149 added to the internal container associated with type number type_num.
150 Memory for the new string is obtained with pmemobj_alloc(), on the giv‐
151 en memory pool, and can be freed with pmemobj_free() on the same memory
152 pool.
153 pmemobj_wcsdup() is equivalent to pmemobj_strdup(), but operates on a
155 wide character string (wchar_t) rather than a standard character
156 string.
157 The pmemobj_alloc_usable_size() function provides the same semantics as
159 malloc_usable_size(3), but instead of the process heap supplied by the
160 system, it operates on the persistent memory heap.
161 The POBJ_NEW() macro is a wrapper around the pmemobj_alloc() function.
163 Instead of taking a pointer to PMEMoid, it takes a pointer to the typed
164 OID of type name TYPE, and passes the size and type number from the
165 typed OID to pmemobj_alloc().
166 The POBJ_ALLOC() macro is equivalent to POBJ_NEW, except that instead
168 of using the size of the typed OID, passes size to pmemobj_alloc().
169 The POBJ_ZNEW() macro is a wrapper around the pmemobj_zalloc() func‐
171 tion. Instead of taking a pointer to PMEMoid, it takes a pointer to
172 the typed OID of type name TYPE, and passes the size and type number
173 from the typed OID to pmemobj_zalloc().
174 The POBJ_ZALLOC() macro is equivalent to POBJ_ZNEW, except that instead
176 of using the size of the typed OID, passes size to pmemobj_zalloc().
177 The POBJ_REALLOC() macro is a wrapper around the pmemobj_realloc()
179 function. Instead of taking a pointer to PMEMoid, it takes a pointer
180 to the typed OID of type name TYPE, and passes the type number from the
181 typed OID to pmemobj_realloc().
182 The POBJ_ZREALLOC() macro is a wrapper around the pmemobj_zrealloc()
184 function. Instead of taking a pointer to PMEMoid, it takes a pointer
185 to the typed OID of type name TYPE, and passes the type number from the
186 typed OID to pmemobj_zrealloc().
187 The POBJ_FREE() macro is a wrapper around the pmemobj_free() function
189 which takes a pointer to the typed OID instead of to PMEMoid.
190
192 On success, pmemobj_alloc() and pmemobj_xalloc return 0. If oidp is
193 not NULL, the PMEMoid of the newly allocated object is stored in oidp.
194 If the allocation fails, -1 is returned and errno is set appropriately.
195 If the constructor returns a non-zero value, the allocation is can‐
196 celed, -1 is returned, and errno is set to ECANCELED. If size equals
197 0, or the flags for pmemobj_xalloc are invalid, -1 is returned, errno
198 is set to EINVAL, and oidp is left untouched.
199 On success, pmemobj_zalloc() returns 0. If oidp is not NULL, the PMEM‐
201 oid of the newly allocated object is stored in oidp. If the allocation
202 fails, it returns -1 and sets errno appropriately. If size equals 0,
203 it returns -1, sets errno to EINVAL, and leaves oidp untouched.
204 The pmemobj_free() function returns no value.
206 On success, pmemobj_realloc() and pmemobj_zrealloc() return 0 and up‐
208 date oidp if necessary. On error, they return -1 and set errno appro‐
209 priately.
210 On success, pmemobj_strdup() and pmemobj_wcsdup() return 0. If oidp is
212 not NULL, the PMEMoid of the duplicated string object is stored in
213 oidp. If s is NULL, they return -1, set errno to EINVAL, and leave
214 oidp untouched. On other errors, they return -1 and set errno appro‐
215 priately.
216 The pmemobj_alloc_usable_size() function returns the number of usable
218 bytes in the object represented by oid. If oid is OID_NULL, it returns
219 0.
220
222 free(3), POBJ_FOREACH(3), realloc(3), strdup(3), wcsdup(3), libpmemo‐
223 bj(7) and <http://pmem.io>
224PMDK - pmemobj API version 2.3 2018-03-13 PMEMOBJ_ALLOC(3)