1PMEMOBJ_ALLOC(3)           PMDK Programmer's Manual           PMEMOBJ_ALLOC(3)
2
3
4

NAME

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

SYNOPSIS

13              #include <libpmemobj.h>
14
15              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
36              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

DESCRIPTION

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
56       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
64       The allocations are always aligned to a cache-line boundary.
65
66       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
71       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
90       pmemobj_xalloc() is equivalent to pmemobj_alloc(), but  with  an  addi‐
91       tional flags argument that is a bitmask of the following values:
92
93       · POBJ_XALLOC_ZERO  -  zero  the allocated object (equivalent of pmemo‐
94         bj_zalloc())
95
96       · POBJ_CLASS_ID(class_id) - allocate  an  object  from  the  allocation
97         class class_id.  The class id cannot be 0.
98
99       · 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
104       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
117       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
128       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
147       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
151       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
164       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
168       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
172       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
177       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
180       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
185       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
188       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
193       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
198       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
201       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

RETURN VALUE

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
233       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
238       The pmemobj_free() function returns no value.
239
240       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
244       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
250       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
254       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

SEE ALSO

259       free(3),  POBJ_FOREACH(3),  realloc(3), strdup(3), wcsdup(3), libpmemo‐
260       bj(7) and <https://pmem.io>
261
262
263
264PMDK - pmemobj API version 2.3    2020-01-31                  PMEMOBJ_ALLOC(3)
Impressum