PMEM2_GET_PERSIST_FN(3)

💾 PMEM2_GET_PERSIST_FN(3) — bestie edition 💾

okay so you're in the PMDK Programmer's Manual section 3, and today's main character is pmem2_get_persist_fn() — the little function that hands you the function that makes your data stay. no cap. 🫶

---

✨ NAME ✨

pmem2_get_persist_fn() — get a persist function 💅

---

🌸 SYNOPSIS 🌸

#include <libpmem2.h>

typedef void (*pmem2_persist_fn)(const void *ptr, size_t size);

struct pmem2_map;

pmem2_persist_fn pmem2_get_persist_fn(struct pmem2_map *map);

---

🦋 DESCRIPTION 🦋

so like, pmem2_get_persist_fn() returns a pointer to a function that's responsible for efficiently persisting data in the range owned by the map. it's giving personal assistant but for memory. ✨

persisting data using pmem2_persist_fn guarantees that the data is stored durably by the time it returns. like, by the time it comes back, it's done, fr fr. 🔥

there are no alignment restrictions on the range described by ptr and size, but lowkey pmem2_persist_fn may expand the range as necessary to meet platform alignment requirements. it's flexible like that. 💁‍♀️

there is nothing atomic or transactional about pmem2_persist_fn. any unwritten stores in the given range will be written, but some stores may have already been written by virtue of normal cache eviction/replacement policies. correctly written code must not depend on stores waiting until pmem2_persist_fn is called to become persistent — they can become persistent at any time before pmem2_persist_fn is called. so like, do nottt build your whole logic on that assumption bestie, that's a trap. 😭

if two (or more) mappings share the same pmem2_persist_fn and they are adjacent to each other, it is safe to call this function for a range spanning those mappings. adjacent maps being besties? iconic. 👑

internally, pmem2_persist_fn performs two operations:

• memory flush (pmem2_get_flush_fn(3)), which can be reordered by the CPU with other flushes
• drain (pmem2_get_drain_fn(3)), which makes sure that the flushes before this operation won't be reordered after it

so this code:

pmem2_persist_fn persist_fn = pmem2_get_persist_fn(map);
persist_fn(addr, len);

is equivalent of:

pmem2_flush_fn flush_fn = pmem2_get_flush_fn(map);
pmem2_drain_fn drain_fn = pmem2_get_drain_fn(map);

flush_fn(addr, len);
drain_fn();

like, same energy, different outfit. 💅

advanced applications may want to flush multiple discontiguous regions and perform the drain operation only once. that's the pro move, the main character energy move. 🌈

---

⭐ RETURN VALUE ⭐

the pmem2_get_persist_fn() function never returns NULL. never ever. not a single time. 🎀

the pmem2_get_persist_fn() for the same map always returns the same function. this means that it's safe to cache its return value. however, this function is very cheap (because it returns a precomputed value), so caching may not be necessary. so like, you can cache it, but honestly? not that deep. 🙈

---

🔍 SEE ALSO 🔍

pmem2_get_drain_fn(3), pmem2_get_flush_fn(3), pmem2_map_new(3), libpmem2(7) and https://pmem.io

---

and that's the whole vibe check bestie — this page came straight out of the PMDK collection, dated 2025-07-24. go forth and persist your data durably, you absolute legend. 💖✨🦋