POBJ_LAYOUT_TOID(3)

💖 POBJ_LAYOUT_BEGIN(3) — the PMDK Programmer's Manual, bestie edition 💖

okay so you opened the POBJ_LAYOUT_BEGIN(3) page, which lives in the PMDK Programmer's Manual, and babes, it's literally all about setting up your persistent memory transactional object store layout. no cap. let's get into it 🫶

---

✨ NAME ✨

POBJ_LAYOUT_BEGIN(), POBJ_LAYOUT_TOID(), POBJ_LAYOUT_ROOT(), POBJ_LAYOUT_NAME(), POBJ_LAYOUT_END(), POBJ_LAYOUT_TYPES_NUM() — that's the whole girl squad, and together they handle the persistent memory transactional object store layout. 👑

---

🌸 SYNOPSIS 🌸

#include <libpmemobj.h>

POBJ_LAYOUT_BEGIN(layout)
POBJ_LAYOUT_TOID(layout, TYPE)
POBJ_LAYOUT_ROOT(layout, ROOT_TYPE)
POBJ_LAYOUT_NAME(layout)
POBJ_LAYOUT_END(layout)
POBJ_LAYOUT_TYPES_NUM(layout)

---

💅 DESCRIPTION 💅

so libpmemobj(7) gives you a whole little set of macros for conveniently declaring a pool's layout. it's giving ✨organized✨. the layout declaration is made up of declarations of however many types you're using, and those declared types get assigned consecutive type numbers. you can then use the declared types together with the type safety macros (peep TOID_DECLARE(3) for that tea 🍓).

⚠️ okay this part is serious, listen up: once you've created the layout declaration, you must not change it unless you're adding brand new types at the end of the existing layout declaration. modifying any existing declaration may lead to changes in the type numbers of declared types, which in consequence may cause data corruption. and we do NOT do data corruption in this house. 😭💀

now the individual macros, one by one:

• POBJ_LAYOUT_BEGIN() — this one indicates the begin of declaration of the layout. the LAYOUT argument is the name of the layout, and bestie, that argument has to be passed to all the macros related to the declaration of layout. no skipping. 🙈
• POBJ_LAYOUT_TOID() — declares a typed OID for the type passed as the TYPE argument, inside the declaration of layout. all types declared using this macro get assigned consecutive type numbers. this macro must be used between the POBJ_LAYOUT_BEGIN() and POBJ_LAYOUT_END() macros, with the same name passed as the LAYOUT argument. periodt.
• POBJ_LAYOUT_ROOT() — declares a typed OID for the type passed as the ROOT_TYPE argument inside the declaration of layout. that typed OID will be assigned the type number for the root object, POBJ_ROOT_TYPE_NUM. it's giving main character energy fr fr.
• POBJ_LAYOUT_END() — ends the declaration of layout. that's it, that's the girl. bye 👋
• POBJ_LAYOUT_NAME() — returns the name of the layout as a null-terminated string. iconic.
• POBJ_LAYOUT_TYPES_NUM() — returns the number of types declared using the POBJ_LAYOUT_TOID() macro within the layout declaration. so like, how many TOIDs did you declare? it knows. 🧚

---

🌈 EXAMPLE 🌈

here's a layout declaration, serving looks:

POBJ_LAYOUT_BEGIN(mylayout);
POBJ_LAYOUT_ROOT(mylayout, struct root);
POBJ_LAYOUT_TOID(mylayout, struct node);
POBJ_LAYOUT_TOID(mylayout, struct foo);
POBJ_LAYOUT_END(mylayout);

struct root
{
    TOID(struct node) node;
};

struct node
{
    TOID(struct node) next;
    TOID(struct foo) foo;
};

and the name of the layout plus the number of declared types can be retrieved using this code right here:

const char *layout_name = POBJ_LAYOUT_NAME(mylayout);
int num_of_types = POBJ_LAYOUT_TYPES_NUM(mylayout);

look at you go. ate that. 💅✨

---

🦋 SEE ALSO 🦋

• TOID_DECLARE(3)
• libpmemobj(7)
• and https://pmem.io — go, click, slay 💜

---

okay that's the whole page bestie, we made it 🎀 this one's from PMDK, dated 2025-07-24, and you can find it chilling in the PMDK Programmer's Manual. now go declare some types (at the end only!!) and have the best day. mwah 💖🫶🌸