.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "" "" "2023-05-31" "PMDK - " "PMDK Programmer's Manual"
.hy
.\" SPDX-License-Identifier: BSD-3-Clause
.\" Copyright 2017-2018, Intel Corporation
.SH NAME
.PP
\f[B]pmemobj_root\f[R](), \f[B]pmemobj_root_construct\f[R]()
\f[B]POBJ_ROOT\f[R](), \f[B]pmemobj_root_size\f[R]() - root object
management
.SH SYNOPSIS
.IP
.nf
\f[C]
#include <libpmemobj.h>

PMEMoid pmemobj_root(PMEMobjpool *pop, size_t size);
PMEMoid pmemobj_root_construct(PMEMobjpool *pop, size_t size,
    pmemobj_constr constructor, void *arg);
POBJ_ROOT(PMEMobjpool *pop, TYPE)
size_t pmemobj_root_size(PMEMobjpool *pop);
\f[R]
.fi
.SH DESCRIPTION
.PP
The root object of a persistent memory pool is an entry point for all
other persistent objects allocated using the \f[B]libpmemobj\f[R] API.
In other words, every object stored in the persistent memory pool has
the root object at the end of its reference path.
It may be assumed that for each persistent memory pool the root object
always exists, and there is exactly one root object in each pool.
.PP
The \f[B]pmemobj_root\f[R]() function creates or resizes the root object
for the persistent memory pool \f[I]pop\f[R].
If this is the first call to \f[B]pmemobj_root\f[R](), the requested
\f[I]size\f[R] is greater than zero and the root object does not exist,
it is implicitly allocated in a thread-safe manner, so the function may
be called by more than one thread simultaneously (as long as all threads
use the identical \f[I]size\f[R] value).
The size of the root object is guaranteed to be not less than the
requested \f[I]size\f[R].
If the requested size is larger than the current size, the root object
is automatically resized.
In such case, the old data is preserved and the extra space is zeroed.
If the requested size is equal to or smaller than the current size, the
root object remains unchanged.
If the requested \f[I]size\f[R] is equal to zero, the root object is not
allocated.
.PP
\f[B]pmemobj_root_construct\f[R]() performs the same actions as
\f[B]pmemobj_root\f[R](), but instead of zeroing the newly allocated
object a \f[I]constructor\f[R] function is called to initialize the
object.
The constructor is also called on reallocations.
.PP
The \f[B]POBJ_ROOT\f[R]() macro works the same way as the
\f[B]pmemobj_root\f[R]() function except it returns a typed
\f[I]OID\f[R] value.
.PP
The \f[B]pmemobj_root_size\f[R]() function returns the current size of
the root object associated with the persistent memory pool
\f[I]pop\f[R].
.SH RETURN VALUE
.PP
Upon success, \f[B]pmemobj_root\f[R]() returns a handle to the root
object associated with the persistent memory pool \f[I]pop\f[R].
The same root object handle is returned in all the threads.
If the requested object size is larger than the maximum allocation size
supported for the pool, or if there is not enough free space in the pool
to satisfy a reallocation request, \f[B]pmemobj_root\f[R]() returns
\f[B]OID_NULL\f[R] and sets \f[I]errno\f[R] to ENOMEM.
If the \f[I]size\f[R] was equal to zero and the root object has not been
allocated, \f[B]pmemobj_root\f[R]() returns \f[B]OID_NULL\f[R] and sets
\f[I]errno\f[R] to EINVAL.
.PP
If the \f[B]pmemobj_root_construct\f[R]() constructor fails, the
allocation is canceled, \f[B]pmemobj_root_construct\f[R]() returns
\f[I]OID_NULL\f[R], and \f[I]errno\f[R] is set to \f[B]ECANCELED\f[R].
\f[B]pmemobj_root_size\f[R]() can be used in the constructor to check
whether this is the first call to the constructor.
.PP
\f[B]POBJ_ROOT\f[R]() returns a typed \f[I]OID\f[R] of type
\f[I]TYPE\f[R] instead of the \f[I]PMEMoid\f[R] returned by
\f[B]pmemobj_root\f[R]().
.PP
The \f[B]pmemobj_root_size\f[R]() function returns the current size of
the root object associated with the persistent memory pool
\f[I]pop\f[R].
The returned size is the largest value requested by any of the earlier
\f[B]pmemobj_root\f[R]() calls.
If the root object has not been allocated yet,
\f[B]pmemobj_root_size\f[R]() returns 0.
.SH SEE ALSO
.PP
\f[B]libpmemobj\f[R](7) and \f[B]<https://pmem.io>\f[R]