pmemobj_root_construct(3)

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  zero,  the
36       root object is not allocated.
37
38       pmemobj_root_construct()  performs  the same actions as pmemobj_root(),
39       but instead of zeroing the newly allocated object a  constructor  func‐
40       tion  is  called  to  initialize  the  object.  The constructor is also
41       called on reallocations.
42
43       The POBJ_ROOT() macro works the same way as the pmemobj_root() function
44       except it returns a typed OID value.
45
46       The  pmemobj_root_size()  function returns the current size of the root
47       object associated with the persistent memory pool pop.
48

RETURN VALUE

50       Upon success, pmemobj_root() returns a handle to the root object  asso‐
51       ciated  with the persistent memory pool pop.  The same root object han‐
52       dle is returned in all the threads.  If the requested  object  size  is
53       larger  than  the maximum allocation size supported for the pool, or if
54       there is not enough free space in the pool to  satisfy  a  reallocation
55       request,  pmemobj_root() returns OID_NULL and sets errno appropriately.
56       If the size was equal to zero and the root object has not been allocat‐
57       ed, pmemobj_root() returns OID_NULL.
58
59       If  the  pmemobj_root_construct()  constructor fails, the allocation is
60       canceled, pmemobj_root_construct() returns OID_NULL, and errno  is  set
61       to  ECANCELED.   pmemobj_root_size()  can be used in the constructor to
62       check whether this is the first call to the constructor.
63
64       POBJ_ROOT() returns a typed OID of type TYPE instead of the PMEMoid re‐
65       turned by pmemobj_root().
66
67       The  pmemobj_root_size()  function returns the current size of the root
68       object associated with the persistent memory pool  pop.   The  returned
69       size  is  the  largest  value  requested  by  any of the earlier pmemo‐
70       bj_root() calls.  If the root object has not been allocated yet, pmemo‐
71       bj_root_size() returns 0.
72

NAME

SYNOPSIS

DESCRIPTION

RETURN VALUE

SEE ALSO