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(),  POBJ_NEW(),  POBJ_ALLOC(),  POBJ_ZNEW(),  POBJ_ZAL‐
9       LOC(), POBJ_REALLOC(), POBJ_ZREALLOC(), POBJ_FREE() -- non-transaction‐
10       al 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);
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
34              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

DESCRIPTION

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
54       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
60       The allocations are always aligned to a cache-line boundary.
61
62       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
67       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
86       pmemobj_xalloc() is equivalent to pmemobj_alloc(), but  with  an  addi‐
87       tional flags argument that is a bitmask of the following values:
88
89       · POBJ_XALLOC_ZERO - zero the object (equivalent of pmemobj_zalloc())
90
91       · POBJ_CLASS_ID(class_id)  -  allocate the object from allocation class
92         class_id.  The class id cannot be 0.
93
94       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
107       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
118       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
137       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
141       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
154       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
158       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
162       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
167       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
170       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
175       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
178       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
183       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
188       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

RETURN VALUE

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
200       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
205       The pmemobj_free() function returns no value.
206
207       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
211       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
217       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

SEE ALSO

222       free(3), POBJ_FOREACH(3), realloc(3), strdup(3),  wcsdup(3),  libpmemo‐
223       bj(7) and <http://pmem.io>
224
225
226
227PMDK - pmemobj API version 2.3    2018-03-13                  PMEMOBJ_ALLOC(3)
Impressum