POBJ_FIRST(3)

💖 pmemobj_first(3) — pmemobj container operations 💖

okay bestie, sit down, hydrate, because we're about to talk about the PMDK Programmer's Manual and specifically the whole little family of container-iteration functions and macros that live in libpmemobj. this one's the one that walks through your persistent memory pool like it's scrolling your fyp ✨

---

🌸 NAME 🌸

pmemobj_first(), pmemobj_next(), POBJ_FIRST(), POBJ_FIRST_TYPE_NUM(), POBJ_NEXT(), POBJ_NEXT_TYPE_NUM(), POBJ_FOREACH(), POBJ_FOREACH_SAFE(), POBJ_FOREACH_TYPE(), POBJ_FOREACH_SAFE_TYPE() — pmemobj container operations 🫶

---

✨ SYNOPSIS ✨

#include <libpmemobj.h>

PMEMoid pmemobj_first(PMEMobjpool *pop);
PMEMoid pmemobj_next(PMEMoid oid);

POBJ_FIRST(PMEMobjpool *pop, TYPE)
POBJ_FIRST_TYPE_NUM(PMEMobjpool *pop, uint64_t type_num)
POBJ_NEXT(TOID oid)
POBJ_NEXT_TYPE_NUM(PMEMoid oid)

POBJ_FOREACH(PMEMobjpool *pop, PMEMoid varoid)
POBJ_FOREACH_SAFE(PMEMobjpool *pop, PMEMoid varoid, PMEMoid nvaroid)
POBJ_FOREACH_TYPE(PMEMobjpool *pop, TOID var)
POBJ_FOREACH_SAFE_TYPE(PMEMobjpool *pop, TOID var, TOID nvar)

like, yes, that's a lot of names, but they're all just different flavours of "walk the list, bestie" 💅

---

🦋 DESCRIPTION 🦋

so libpmemobj(7) container operations are the mechanism that lets you iterate through the internal object collection — either hunting down one specific object, or doing a specific operation on every single object of a given type. it's giving "for you page but for persistent memory".

⚠️ real talk: software should not make any assumptions about the order of the objects in the internal object containers. the order is not yours to predict, no cap. 🙈

okay now the individual ones:

• pmemobj_first() — returns the first object from the pool.
• POBJ_FIRST() — macro, returns the first object from the pool of the type specified by TYPE.
• POBJ_FIRST_TYPE_NUM() — macro, returns the first object from the pool of the type specified by type_num.
• pmemobj_next() — returns the next object from the pool.
• POBJ_NEXT() — macro, returns the next object of the same type as the object referenced by oid.
• POBJ_NEXT_TYPE_NUM() — macro, returns the next object of the same type number as the object referenced by oid.

---

🎀 the four iteration macros 🎀

the following four macros are the glow-up: a way more convenient way to iterate through the internal collections while performing a specific operation on each object. main character energy fr fr.

• POBJ_FOREACH() — performs a specific operation on each allocated object stored in the persistent memory pool pop. it traverses the internal collection of all the objects, assigning a handle to each element in turn to varoid.
• POBJ_FOREACH_TYPE() — performs a specific operation on each allocated object stored in the persistent memory pool pop that has the same type as var. it traverses the internal collection of all the objects of the specified type, assigning a handle to each element in turn to var.
• POBJ_FOREACH_SAFE() and POBJ_FOREACH_SAFE_TYPE() — these work in a similar fashion as POBJ_FOREACH() and POBJ_FOREACH_TYPE(), except that prior to performing the operation on the object, they preserve a handle to the next object in the collection by assigning it to nvaroid or nvar, respectively. this is the one that lets you safely delete selected objects while iterating through the collection. iconic behavior, truly. 🔥

---

👑 RETURN VALUE 👑

• pmemobj_first() returns the first object from the pool, or, if the pool is empty, OID_NULL.
• pmemobj_next() returns the next object from the pool. if the object referenced by oid is the last object in the collection, or if oid is OID_NULL, pmemobj_next() returns OID_NULL.

💀 so like, if you're getting OID_NULL back, either you hit the end or you started at nothing. vibe check accordingly.

---

🌈 SEE ALSO 🌈

• libpmemobj(7)
• https://pmem.io

---

and that's the whole page, bestie!! 🧚💜 this was brought to you by the PMDK fam, dated 2025-07-24, straight from the PMDK Programmer's Manual. go forth and iterate responsibly. periodt. ✨🎀🍓