TX_FREE(3)

📦
version 2.1.0 · 6 versions
, in fedora 43

pmemobj_tx_alloc(3) — transactional object manipulation 💅✨

PMDK Programmer's Manual

okay bestie, sit down, hydrate, because this is the page where all your transactional memory dreams live. it's giving "allocate, resize, duplicate, free — but make it atomic." 🦋

✨ NAME ✨

pmemobj_tx_alloc(), pmemobj_tx_zalloc(), pmemobj_tx_xalloc(), pmemobj_tx_realloc(), pmemobj_tx_zrealloc(), pmemobj_tx_strdup(), pmemobj_tx_xstrdup(), pmemobj_tx_wcsdup(), pmemobj_tx_xwcsdup(), pmemobj_tx_free(), pmemobj_tx_xfree()

TX_NEW(), TX_ALLOC(), TX_ZNEW(), TX_ZALLOC(), TX_XALLOC(), TX_REALLOC(), TX_ZREALLOC(), TX_STRDUP(), TX_XSTRDUP(), TX_WCSDUP(), TX_XWCSDUP(), TX_FREE(), TX_XFREE() — transactional object manipulation 🌸

✨ SYNOPSIS ✨

#include <libpmemobj.h>

PMEMoid pmemobj_tx_alloc(size_t size, uint64_t type_num);
PMEMoid pmemobj_tx_zalloc(size_t size, uint64_t type_num);
PMEMoid pmemobj_tx_xalloc(size_t size, uint64_t type_num, uint64_t flags);
PMEMoid pmemobj_tx_realloc(PMEMoid oid, size_t size, uint64_t type_num);
PMEMoid pmemobj_tx_zrealloc(PMEMoid oid, size_t size, uint64_t type_num);
PMEMoid pmemobj_tx_strdup(const char *s, uint64_t type_num);
PMEMoid pmemobj_tx_wcsdup(const wchar_t *s, uint64_t type_num);
int pmemobj_tx_free(PMEMoid oid);
int pmemobj_tx_xfree(PMEMoid oid, uint64_t flags);

TX_NEW(TYPE)
TX_ALLOC(TYPE, size_t size)
TX_ZNEW(TYPE)
TX_ZALLOC(TYPE, size_t size)
TX_XALLOC(TYPE, size_t size, uint64_t flags)
TX_REALLOC(TOID o, size_t size)
TX_ZREALLOC(TOID o, size_t size)
TX_STRDUP(const char *s, uint64_t type_num)
TX_WCSDUP(const wchar_t *s, uint64_t type_num)
TX_FREE(TOID o)
TX_XFREE(TOID o, uint64_t flags)

✨ DESCRIPTION ✨

🎀 the plain functions (no macros, just vibes)

pmemobj_tx_alloc() transactionally allocates a brand new object of the given size and type_num. here's the ✨special sauce✨ that separates it from the non-transactional allocations: the objects only get added to the internal object containers of the given type_num after the transaction is committed, which is what makes them visible to the POBJ_FOREACH_*() macros. no cap. this function must be called during TX_STAGE_WORK. 💖

pmemobj_tx_zalloc() transactionally allocates a new zeroed object of the given size and type_num. yes, zeroed. pristine. untouched. must be called during TX_STAGE_WORK. 🧚

pmemobj_tx_xalloc() transactionally allocates a new object of the given size and type_num. the flags argument is a bitmask, and here's what you can put in it:

  • POBJ_XALLOC_ZERO — zero the allocated object (it's the equivalent of pmemobj_tx_zalloc, so basically the glow-up version)
  • POBJ_XALLOC_NO_FLUSH — skip flush on commit (do this when your application handles the flushing itself, or when it uses pmemobj_memcpy_persist)
  • POBJ_CLASS_ID(class_id) — allocate an object from the allocation class with id equal to class_id
  • POBJ_ARENA_ID(arena_id) — allocate an object from the arena specified by arena_id. the arena must exist, otherwise the behavior is undefined (!!). if arena_id is equal 0, then the arena assigned to the current thread will be used.
  • POBJ_XALLOC_NO_ABORT — if the function does not end successfully, do not abort the transaction.

this function must be called during TX_STAGE_WORK. 👑

pmemobj_tx_realloc() transactionally resizes an existing object to the given size and changes its type to type_num. a couple of gotchas to keep in your notes app:

  • if oid is OID_NULL, then the call is equivalent to pmemobj_tx_alloc(pop, size, type_num).
  • if size is equal to zero and oid is not OID_NULL, then the call is equivalent to pmemobj_tx_free(oid).
  • if the new size is larger than the old size, the added memory will not be initialized. (so it's giving chaos unless you handle it 🙈)

this function must be called during TX_STAGE_WORK. 💜

pmemobj_tx_zrealloc() transactionally resizes an existing object to the given size and changes its type to type_num. if the new size is larger than the old size, the extended new space is zeroed — that's the difference, that's the "z", bestie. must be called during TX_STAGE_WORK. ✨

pmemobj_tx_strdup() transactionally allocates a new object containing a duplicate of the string s and assigns it a type type_num. must be called during TX_STAGE_WORK. 🍓

pmemobj_tx_xstrdup() behaves exactly the same as pmemobj_tx_strdup() when flags equals zero. the flags argument is a bitmask of values described in the pmemobj_tx_xalloc section above. 👆

pmemobj_tx_wcsdup() transactionally allocates a new object containing a duplicate of the wide character string s and assigns it a type type_num. must be called during TX_STAGE_WORK. 🌈

pmemobj_tx_xwcsdup() behaves exactly the same as pmemobj_tx_wcsdup() when flags equals zero. the flags argument is a bitmask of values described in the pmemobj_tx_xalloc section above. 👆

pmemobj_tx_free() transactionally frees an existing object referenced by oid. must be called during TX_STAGE_WORK. 🦋

pmemobj_tx_xfree() behaves exactly the same as pmemobj_tx_free() when flags equals zero. flags is a bitmask of the following value:

  • POBJ_XFREE_NO_ABORT — if the function does not end successfully, do not abort the transaction.

this function must be called during TX_STAGE_WORK. 💅

🦋 the macros (the shortcuts your fave devs actually type)

TX_NEW() macro transactionally allocates a new object of the given TYPE and assigns it a type number read from the typed OID. the allocation size is determined from the size of the user-defined structure TYPE. if it's successful and called during TX_STAGE_WORK, it returns a handle to the newly allocated object. otherwise, the stage is changed to TX_STAGE_ONABORT, OID_NULL is returned, and errno is set appropriately. 😭

TX_ALLOC() macro transactionally allocates a new object of the given TYPE and assigns it a type number read from the typed OID. the allocation size is passed by the size parameter. if successful and called during TX_STAGE_WORK, it returns a handle to the newly allocated object. otherwise, the stage is set to TX_STAGE_ONABORT, OID_NULL is returned, and errno is set appropriately. 💖

TX_ZNEW() macro transactionally allocates a new zeroed object of the given TYPE and assigns it a type number read from the typed OID. the allocation size is determined from the size of the user-defined structure TYPE. if successful and called during TX_STAGE_WORK, it returns a handle to the newly allocated object. otherwise, the stage changes to TX_STAGE_ONABORT, OID_NULL is returned, and errno is set appropriately. ✨

TX_ZALLOC() macro transactionally allocates a new zeroed object of the given TYPE and assigns it a type number read from the typed OID. the allocation size is passed by the size argument. if successful and called during TX_STAGE_WORK, it returns a handle to the newly allocated object. otherwise, the stage is changed to TX_STAGE_ONABORT, OID_NULL is returned, and errno is set appropriately. 🧚

TX_XALLOC() macro transactionally allocates a new object of the given TYPE and assigns it a type number read from the typed OID. the allocation size is passed by the size argument. the flags argument is a bitmask of values described in the pmemobj_tx_xalloc section. if successful and called during TX_STAGE_WORK, it returns a handle to the newly allocated object. otherwise, OID_NULL is returned, errno is set, and when flags do not contain POBJ_XALLOC_NO_ABORT, the transaction is aborted. 💀

TX_REALLOC() macro transactionally resizes an existing object referenced by a handle o to the given size. if successful and called during TX_STAGE_WORK, it returns a handle to the reallocated object. otherwise, the stage is changed to TX_STAGE_ONABORT, OID_NULL is returned, and errno is set appropriately. 🌸

TX_ZREALLOC() macro transactionally resizes an existing object referenced by a handle o to the given size. if the new size is larger than the old size, the extended new space is zeroed. if successful and called during TX_STAGE_WORK, it returns a handle to the reallocated object. otherwise, the stage is changed to TX_STAGE_ONABORT, OID_NULL is returned, and errno is set appropriately. ✨

TX_STRDUP() macro transactionally allocates a new object containing a duplicate of the string s and assigns it type type_num. if successful and called during TX_STAGE_WORK, it returns a handle to the newly allocated object. otherwise, the stage is changed to TX_STAGE_ONABORT, OID_NULL is returned, and errno is set appropriately. 🍓

TX_XSTRDUP() macro transactionally allocates a new object containing a duplicate of the string s and assigns it type type_num. the flags argument is a bitmask of values described in the pmemobj_tx_xalloc section. if successful and called during TX_STAGE_WORK, it returns a handle to the newly allocated object. otherwise, OID_NULL is returned, errno is set, and when flags do not contain POBJ_XALLOC_NO_ABORT, the transaction is aborted. 💀

TX_WCSDUP() macro transactionally allocates a new object containing a duplicate of the wide character string s and assigns it a type type_num. if successful and called during TX_STAGE_WORK, it returns a handle to the newly allocated object. otherwise, the stage is changed to TX_STAGE_ONABORT, OID_NULL is returned, and errno is set appropriately. 🌈

TX_XWCSDUP() macro transactionally allocates a new object containing a duplicate of the wide character string s and assigns it a type type_num. the flags argument is a bitmask of values described in the pmemobj_tx_xalloc section. if successful and called during TX_STAGE_WORK, it returns a handle to the newly allocated object. otherwise, OID_NULL is returned, errno is set, and when flags do not contain POBJ_XALLOC_NO_ABORT, the transaction is aborted. 💀

TX_FREE() macro transactionally frees the memory space represented by an object handle o. if o is OID_NULL, no operation is performed. if successful and called during TX_STAGE_WORK, TX_FREE() returns 0. otherwise, the stage is changed to TX_STAGE_ONABORT and errno is set appropriately. 🦋

TX_XFREE() macro transactionally frees the memory space represented by an object handle o. if o is OID_NULL, no operation is performed. the flags argument is a bitmask of values described in the pmemobj_tx_xfree section. if successful and called during TX_STAGE_WORK, TX_FREE() returns 0. otherwise, the error number is returned, errno is set, and when flags do not contain POBJ_XFREE_NO_ABORT, the transaction is aborted. 💅

okay that's the whole front half, bestie — more parts are coming so don't you dare close the tab 💖

💖 RETURN VALUE 💖

okay bestie, here's the tea on what these functions hand back to you 🫶

✨ the regular alloc crew ✨

  • pmemobj_tx_alloc(), pmemobj_tx_zalloc(), pmemobj_tx_strdup(), pmemobj_tx_wcsdup() — when they slay (success 💅), they hand you back a handle to the brand-new object you just made. when they don't slay, the stage gets switched to TX_STAGE_ONABORT, you get OID_NULL back, and errno gets set to something appropriate. and if size equals 0?? yeah you get OID_NULL and errno set appropriately. no object for you, sorry babe 😭

✨ the x-tra special alloc crew ✨

  • pmemobj_tx_xalloc(), pmemobj_tx_xstrdup(), pmemobj_tx_xwcsdup() — success means a handle to the shiny new object, periodt 👑. but if things go sideways, you get OID_NULL, errno is set, and — here's the important bit — when flags do not contain POBJ_XALLOC_NO_ABORT, the whole transaction gets aborted. so like, the x versions are out here catching strays, not aborting unless you didn't ask them not to 🫠

🌸 the realloc girlies 🌸

  • pmemobj_tx_realloc() and pmemobj_tx_zrealloc() — on success they return a handle to the resized object, iconic. otherwise the stage changes to TX_STAGE_ONABORT, OID_NULL is returned, and errno is set appropriately.
🚨 bestie WARNING 🚨 note that the object handle value may change as a result of reallocation. so like, don't be out here holding onto the old handle like it's your emotional support OID, because it might not be the same one anymore. the way that reallocation just... reshapes your whole life 😭💀

🎀 freeing the girlies 🎀

  • pmemobj_tx_free() — on success, returns 0. otherwise the stage changes to TX_STAGE_ONABORT, errno is set appropriately, and the transaction is aborted. she's dramatic like that 💅
  • pmemobj_tx_xfree() — on success, returns 0. otherwise the error number is returned, errno is set, and when flags do not contain POBJ_XFREE_NO_ABORT, the transaction is aborted. lowkey the same energy but with ✨ options ✨

🌈 SEE ALSO 🌈

like, go read these next, iykyk:

and that's a wrap on this page bestie!! this one's from the PMDK collection, dated 2025-07-24. go forth and allocate responsibly, mwah 💖💅🎀

📦 where this page comes from