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

NAME

6       pmemobj_root(),     pmemobj_root_construct()     POBJ_ROOT(),    pmemo‐
7       bj_root_size() - root object management
8

SYNOPSIS

10              #include <libpmemobj.h>
11
12              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

DESCRIPTION

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
26       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
39       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
44       The POBJ_ROOT() macro works the same way as the pmemobj_root() function
45       except it returns a typed OID value.
46
47       The pmemobj_root_size() function returns the current size of  the  root
48       object associated with the persistent memory pool pop.
49

RETURN VALUE

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
60       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
65       POBJ_ROOT() returns a typed OID of type TYPE instead of the PMEMoid re‐
66       turned by pmemobj_root().
67
68       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

SEE ALSO

75       libpmemobj(7) and <https://pmem.io>
76
77
78
79PMDK - pmemobj API version 2.3    2022-08-25                   PMEMOBJ_ROOT(3)
Impressum