POBJ_ROOT(3)

💖 PMEMOBJ_ROOT 💖

okay bestie, so this is from the PMDK Programmer's Manual (that's the persistent memory dev kit, iykyk) and it's about pmemobj_root(3) — the root object management girlies. let's get into it 🎀

---

✨ NAME ✨

pmemobj_root(), pmemobj_root_construct(), POBJ_ROOT(), pmemobj_root_size() — root object management. that's the whole vibe. 💅

---

🦋 SYNOPSIS 🦋

#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);

---

🌸 DESCRIPTION 🌸

okay so the root object of a persistent memory pool is basically THE entry point for literally every other persistent object you allocate with the libpmemobj API. like, think of it as the main character of the pool ✨. every object stored in the persistent memory pool has the root object sitting at the end of its reference path. and here's the thing: for each persistent memory pool, you can just assume the root object always exists, and there is exactly one root object per pool. no cap. 👑

The pmemobj_root() function creates or resizes the root object for the persistent memory pool pop. if this is the first call to pmemobj_root(), and the requested size is greater than zero, and the root object doesn't exist yet, then it gets implicitly allocated in a thread-safe manner — meaning yes bestie, more than one thread can call this at the same time, as long as all the threads use the identical size value 🙌. the size of the root object is guaranteed to be not less than the requested size. if the requested size is bigger than the current size, the root object gets automatically resized. when that happens, the old data is preserved and the extra space is zeroed out. if the requested size is equal to or smaller than the current size, the root object just stays unchanged, like, it's not doing extra work for no reason 💅. and if the requested size is equal to zero? the root object is not allocated. periodt.

pmemobj_root_construct() does the same exact actions as pmemobj_root(), except instead of zeroing the newly allocated object, a constructor function gets called to initialize the object 🧚. and the constructor is also called on reallocations. she's thorough.

The POBJ_ROOT() macro works the same way as the pmemobj_root() function except it returns a typed</> OID value.

The pmemobj_root_size() function returns the current size of the root object associated with the persistent memory pool pop. that's it, that's her job 🌈.

---

⭐ RETURN VALUE ⭐

upon success, pmemobj_root() returns a handle to the root object associated with the persistent memory pool pop. and the same root object handle is returned in all the threads — everyone gets the same one, no drama 🫶.

now for the sad part 😭:

• 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, pmemobj_root() returns OID_NULL and sets errno to ENOMEM.
• if the size was equal to zero and the root object has not been allocated, pmemobj_root() returns OID_NULL and sets errno to EINVAL.

💀 heads up: if the pmemobj_root_construct() constructor fails, the allocation is canceled, pmemobj_root_construct() returns OID_NULL, and errno is set to ECANCELED. also, pmemobj_root_size() can be used inside the constructor to check whether this is the first call to the constructor. very useful, very iconic.

POBJ_ROOT() returns a typed OID of type TYPE instead of the PMEMoid returned by pmemobj_root().

The pmemobj_root_size() function returns the current size of the root object associated with the persistent memory pool pop. the returned size is the largest value requested by any of the earlier pmemobj_root() calls — she remembers the biggest one, queen behavior 👑. and if the root object has not been allocated yet, pmemobj_root_size() returns 0.

---

💜 SEE ALSO 💜

libpmemobj(7) and https://pmem.io — go read those too bestie, i'm obsessed.

---

that's the whole page fr fr 💖 this was PMDK, dated 2025-07-24 — written by the PMDK girlies, brought to you with love, zero cap, and an unreasonable amount of root object enthusiasm. slay. 💅✨🎀🦋🌸