1PMEMOBJ_ROOT(3) PMDK Programmer's Manual PMEMOBJ_ROOT(3)
2
6 pmemobj_root(), pmemobj_root_construct() POBJ_ROOT(), pmemo‐
7 bj_root_size() - root object management
8
10 #include <libpmemobj.h>
11 PMEMoid pmemobj_root(PMEMobjpool *pop, size_t size);
13 PMEMoid pmemobj_root_construct(PMEMobjpool *pop, size_t size,
14 pmemobj_constr constructor, void *arg);
15 POBJ_ROOT(PMEMobjpool *pop, TYPE)
16 size_t pmemobj_root_size(PMEMobjpool *pop);
17
19 The root object of a persistent memory pool is an entry point for all
20 other persistent objects allocated using the libpmemobj API. In other
21 words, every object stored in the persistent memory pool has the root
22 object at the end of its reference path. It may be assumed that for
23 each persistent memory pool the root object always exists, and there is
24 exactly one root object in each pool.
25 The pmemobj_root() function creates or resizes the root object for the
27 persistent memory pool pop. If this is the first call to pmemo‐
28 bj_root(), the requested size is greater than zero and the root object
29 does not exist, it is implicitly allocated in a thread-safe manner, so
30 the function may be called by more than one thread simultaneously (as
31 long as all threads use the identical size value). The size of the
32 root object is guaranteed to be not less than the requested size. If
33 the requested size is larger than the current size, the root object is
34 automatically resized. In such case, the old data is preserved and the
35 extra space is zeroed. If the requested size is equal to or smaller
36 than the current size, the root object remains unchanged. If the re‐
37 quested size is equal to zero, the root object is not allocated.
38 pmemobj_root_construct() performs the same actions as pmemobj_root(),
40 but instead of zeroing the newly allocated object a constructor func‐
41 tion is called to initialize the object. The constructor is also
42 called on reallocations.
43 The POBJ_ROOT() macro works the same way as the pmemobj_root() function
45 except it returns a typed OID value.
46 The pmemobj_root_size() function returns the current size of the root
48 object associated with the persistent memory pool pop.
49
51 Upon success, pmemobj_root() returns a handle to the root object asso‐
52 ciated with the persistent memory pool pop. The same root object han‐
53 dle is returned in all the threads. If the requested object size is
54 larger than the maximum allocation size supported for the pool, or if
55 there is not enough free space in the pool to satisfy a reallocation
56 request, pmemobj_root() returns OID_NULL and sets errno to ENOMEM. If
57 the size was equal to zero and the root object has not been allocated,
58 pmemobj_root() returns OID_NULL and sets errno to EINVAL.
59 If the pmemobj_root_construct() constructor fails, the allocation is
61 canceled, pmemobj_root_construct() returns OID_NULL, and errno is set
62 to ECANCELED. pmemobj_root_size() can be used in the constructor to
63 check whether this is the first call to the constructor.
64 POBJ_ROOT() returns a typed OID of type TYPE instead of the PMEMoid re‐
66 turned by pmemobj_root().
67 The pmemobj_root_size() function returns the current size of the root
69 object associated with the persistent memory pool pop. The returned
70 size is the largest value requested by any of the earlier pmemo‐
71 bj_root() calls. If the root object has not been allocated yet, pmemo‐
72 bj_root_size() returns 0.
73
75 libpmemobj(7) and <https://pmem.io>
76PMDK - pmemobj API version 2.3 2022-08-25 PMEMOBJ_ROOT(3)