PMEMOBJ_CTL_GET(3)

🦋 NAME 🦋

pmemobj_ctl_get(), pmemobj_ctl_set(), pmemobj_ctl_exec() — query and modify libpmemobj internal behavior (EXPERIMENTAL)

okay so bestie, this is the PMDK Programmer's Manual and today we're doing the control-plane girlies 💅 these three functions are literally the remote control for libpmemobj's insides. and yes, they're EXPERIMENTAL, which means the API said "I'm still growing, don't get too attached" 😭

---

✨ SYNOPSIS ✨

#include <libpmemobj.h>

int pmemobj_ctl_get(PMEMobjpool *pop, const char *name, void *arg); (EXPERIMENTAL)
int pmemobj_ctl_set(PMEMobjpool *pop, const char *name, void *arg); (EXPERIMENTAL)
int pmemobj_ctl_exec(PMEMobjpool *pop, const char *name, void *arg); (EXPERIMENTAL)

---

💖 DESCRIPTION 💖

so the way that pmemobj_ctl_get(), pmemobj_ctl_set() and pmemobj_ctl_exec() work is they give you one uniform interface for querying and modifying the internal behavior of libpmemobj(7) through the control (CTL) namespace. it's giving "one door, whole house" energy 🏠✨

the name argument specifies an entry point, as defined in the CTL namespace specification. the entry point description is the one that tells you whether the extra arg is required or not. those two parameters together? that's your CTL query boo 🎀

the functions and the entry points are thread-safe unless stated otherwise below. if there are special conditions for calling an entry point, they're explicitly stated in its description, no cap. the functions propagate the return value of the entry point. if either name or arg is invalid, -1 is returned. periodt.

if the ctl query you provided is valid, the CTL functions will always return 0 on success and -1 on failure, unless otherwise specified in the entry point description. iconic behavior honestly 💅

See more in pmem_ctl(5) man page.

---

🎀 CTL NAMESPACE 🎀

okay so here comes the whole menu, every single entry point, no skips, no cuts 🫶

• prefault.at_create — prefault.at_create | rw | global | int | int | - | boolean

If set, every page of the pool will be touched and written to when the pool is created, in order to trigger page allocation and minimize the performance impact of pagefaults. Affects only the pmemobj_create() function.

• prefault.at_open — prefault.at_open | rw | global | int | int | - | boolean

If set, every page of the pool will be touched and written to when the pool is opened, in order to trigger page allocation and minimize the performance impact of pagefaults. Affects only the pmemobj_open() function.

• sds.at_create — sds.at_create | rw | global | int | int | - | boolean

If set, force-enables or force-disables the SDS feature during pool creation. Affects only the pmemobj_create() function. See pmempool_feature_query(3) for information about the SDS (SHUTDOWN_STATE) feature.

• copy_on_write.at_open — copy_on_write.at_open | rw | global | int | int | - | boolean

If set, the pool is mapped in such a way that modifications don't reach the underlying medium. From the user's perspective this means that when the pool is closed all changes are reverted. This feature is not supported for pools located on Device DAX. 😭

• tx.debug.skip_expensive_checks — tx.debug.skip_expensive_checks | rw | - | int | int | - | boolean

Turns off some expensive checks performed by the transaction module in "debug" builds. Ignored in "release" builds. it's giving "only in debug bestie" energy 🙈

• tx.debug.verify_user_buffers — tx.debug.verify_user_buffers | rw | - | int | int | - | boolean

Enables verification of user buffers provided by the pmemobj_tx_log_append_buffer(3) API. For now the only verified aspect is whether the same buffer is used simultaneously in 2 or more transactions or more than once in the same transaction. This value should not be modified at runtime if any transaction for the current pool is in progress.

• tx.cache.size — tx.cache.size | rw | - | long long | long long | - | integer

Size in bytes of the transaction snapshot cache. In a larger cache the frequency of persistent allocations is lower, but with higher fixed cost.

This should be set to roughly the sum of sizes of the snapshotted regions in an average transaction in the pool.

This entry point is not thread safe and should not be modified if there are any transactions currently running.

This value must be a in a range between 0 and PMEMOBJ_MAX_ALLOC_SIZE, otherwise this entry point will fail.

• tx.cache.threshold — tx.cache.threshold | rw | - | long long | long long | - | integer

This entry point is deprecated. All snapshots, regardless of the size, use the transactional cache.

• tx.post_commit.queue_depth — tx.post_commit.queue_depth | rw | - | int | int | - | integer

This entry point is deprecated.

• tx.post_commit.worker — tx.post_commit.worker | r- | - | void * | - | - | -

This entry point is deprecated.

• tx.post_commit.stop — tx.post_commit.stop | r- | - | void * | - | - | -

This entry point is deprecated.

• heap.narenas.automatic — heap.narenas.automatic | r- | - | unsigned | - | - | -

Reads the number of arenas used in automatic scheduling of memory operations for threads. By default, this value is equal to the number of available processors. An arena is a memory management structure which enables concurrency by taking exclusive ownership of parts of the heap and allowing associated threads to allocate without contention.

• heap.narenas.total — heap.narenas.total | r- | - | unsigned | - | - | -

Reads the number of all created arenas. It includes automatic arenas created by default and arenas created using the heap.arena.create CTL.

• heap.narenas.max — heap.narenas.max | rw- | - | unsigned | unsigned | - | -

Reads or writes the maximum number of arenas that can be created. This entry point is not thread-safe with regards to heap operations (allocations, frees, reallocs).

• heap.arena.[arena_id].size — heap.arena.[arena_id].size | r- | - | uint64_t | - | - | -

Reads the total amount of memory in bytes which is currently exclusively owned by the arena. Large differences in this value between arenas might indicate an uneven scheduling of memory resources. The arena id cannot be 0.

• heap.thread.arena_id — heap.thread.arena_id | rw- | - | unsigned | unsigned | - | -

Reads the index of the arena assigned to the current thread or assigns arena with specific id to the current thread. The arena id cannot be 0.

• heap.arena.create — heap.arena.create | –x | - | - | - | unsigned | -

Creates and initializes one new arena in the heap. This entry point reads an id of the new created arena.

Newly created arenas by this CTL are inactive, which means that the arena will not be used in the automatic scheduling of memory requests. To activate the new arena, use the heap.arena.[arena_id].automatic CTL.

Arena created using this CTL can be used for allocation by explicitly specifying the arena_id for the POBJ_ARENA_ID(id) flag in pmemobj_tx_xalloc()/pmemobj_xalloc()/pmemobj_xreserve() functions.

By default, the number of arenas is limited to 1024.

• heap.arena.[arena_id].automatic — heap.arena.[arena_id].automatic | rw- | - | boolean | boolean | - | -

Reads or modifies the state of the arena. If set, the arena is used in automatic scheduling of memory operations for threads. This should be set to false if the application wants to manually manage allocator scalability through explicitly assigning arenas to threads by using heap.thread.arena_id. The arena id cannot be 0 and at least one automatic arena must exist.

• heap.arenas_assignment_type — heap.arenas_assignment_type | rw | global | enum pobj_arenas_assignment_type | enum pobj_arenas_assignment_type | - | string

Reads or modifies the behavior of arenas assignment for threads. By default, each thread is assigned its own arena from the pool of automatic arenas (described earlier). This consumes one TLS key from the OS for every open pool. Applications that wish to avoid this behavior can instead rely on one global arena assignment per pool. This might limits scalability if not using arenas explicitly.

The argument for this CTL is an enum with the following types:

• POBJ_ARENAS_ASSIGNMENT_THREAD_KEY, string value: thread. Default, threads use individually assigned arenas.
• POBJ_ARENAS_ASSIGNMENT_GLOBAL, string value: global. Threads use one global arena.

Changing this value has no impact on already open pools. It should typically be set at the beginning of the application, before any pools are opened or created.

• heap.arenas_default_max — heap.arenas_default_max | rw- | global | unsigned | unsigned | - | integer

Reads or writes the number of arenas that are created by default on startup of the heap's runtime state. This value by default is equal to the number of online CPUs available on the platform, but can be decreased or increased depending on application's scalability requirements.

• heap.alloc_class.[class_id].desc — heap.alloc_class.[class_id].desc | rw | - | struct pobj_alloc_class_desc | struct pobj_alloc_class_desc | - | integer, integer, integer, string

Describes an allocation class. Allows one to create or view the internal data structures of the allocator.

Creating custom allocation classes can be beneficial for both raw allocation throughput, scalability and, most importantly, fragmentation. By carefully constructing allocation classes that match the application workload, one can entirely eliminate external and internal fragmentation. For example, it is possible to easily construct a slab-like allocation mechanism for any data structure.

The [class_id] is an index field. Only values between 0-254 are valid. If setting an allocation class, but the class_id is already taken, the function will return -1. The values between 0-127 are reserved for the default allocation classes of the library and can be used only for reading.

The recommended method for retrieving information about all allocation classes is to call this entry point for all class ids between 0 and 254 and discard those results for which the function returns an error.

This entry point takes a complex argument 🎀

struct pobj_alloc_class_desc {
    size_t unit_size;
    size_t alignment;
    unsigned units_per_block;
    enum pobj_header_type header_type;
    unsigned class_id;
};

The first field, unit_size, is an 8-byte unsigned integer that defines the allocation class size. While theoretically limited only by PMEMOBJ_MAX_ALLOC_SIZE, for most workloads this value should be between 8 bytes and 2 megabytes.

The alignment field specifies the user data alignment of objects allocated using the class. If set, must be a power of two and an even divisor of unit_size. Alignment is limited to maximum of 2 megabytes. All objects have default alignment of 64 bytes, but the user data alignment is affected by the size of the chosen header.

The units_per_block field defines how many units a single block of memory contains. This value will be adjusted to match the internal size of the block (256 kilobytes or a multiple thereof). For example, given a class with a unit_size of 512 bytes and a units_per_block of 1000, a single block of memory for that class will have 512 kilobytes. This is relevant because the bigger the block size, the less frequently blocks need to be fetched, resulting in lower contention on global heap state. If the CTL call is being done at runtime, the units_per_block variable of the provided alloc class structure is modified to match the actual value.

The header_type field defines the header of objects from the allocation class. There are three types:

• POBJ_HEADER_LEGACY — string value: legacy. This is the header type for allocation classes from before version 1.3 of the library. Not recommended, bestie. It eats a 64 byte metadata overhead for every single object, but it fully supports all features.
• POBJ_HEADER_COMPACT — string value: compact. This is the default for all predefined allocation classes. Only a 16 byte metadata overhead for every object, and it fully supports all features. The people's champion 💅
• POBJ_HEADER_NONE — string value: none. This one has no metadata overhead beyond a single bitmap entry. Perfect for very small allocation classes or when objects literally must be adjacent to each other. But heads up: this header type does not support type numbers (type number is always 0) or allocations that span more than one unit. It's giving minimalist but make it limited 🫠

---

The class_id field is an optional, runtime-only variable that lets you retrieve the identifier of the class. It'll be equivalent to the [class_id] you provided. This field cannot be set from a config file — runtime only, no exceptions.

The allocation classes are a runtime state of the library, which means they have to be created again after every open. It is highly recommended to use the configuration file to store the classes so you're not out here rebuilding them every time. 😭

This structure is declared in the libpmemobj/ctl.h header file. Please refer to that file for an in-depth explanation of the allocation classes and the relevant algorithms — it's the lore, fr fr.

Allocation classes constructed this way can be leveraged by explicitly specifying the class using the POBJ_CLASS_ID(id) flag in the pmemobj_tx_xalloc()/pmemobj_xalloc() functions. ✨

Example of a valid alloc class query string:

heap.alloc_class.128.desc=500,0,1000,compact

This query, if executed, will create an allocation class with an id of 128 that has a unit size of 500 bytes, has at least 1000 units per block, and uses a compact header. Iconic. 👑

For reading, the function returns 0 if successful. If the allocation class does not exist it sets the errno to ENOENT and returns -1. 💀

This entry point can fail if any of the parameters of the allocation class is invalid, or if exactly the same class already exists. So no duplicates, bestie.

• heap.alloc_class.new.desc | -w | - | - | struct pobj_alloc_class_desc | - | integer, integer, integer, string

Same as heap.alloc_class.[class_id].desc, except instead of making you hand over a class_id, it automatically creates the allocation class with the first available identifier. 🎀

Use this when it's impossible to guarantee unique allocation class naming in the application (e.g. when writing a library that uses libpmemobj). The required class identifier will be stored in the class_id field of the struct pobj_alloc_class_desc. Slay, it handles the naming for you.

• stats.enabled | rw | - | enum pobj_stats_enabled | enum pobj_stats_enabled | - | string

Enables or disables runtime collection of statistics. There are two types: persistent and transient. Persistent statistics survive pool restarts, transient ones don't. Statistics are not recalculated after enabling — any operations that happen between disabling and re-enabling will not show up in subsequent values. 🙈

Only transient statistics are enabled by default. Enabling persistent statistics may have a non-trivial performance impact. You've been warned.

• stats.heap.curr_allocated | r- | - | uint64_t | - | - | -

Reads the number of bytes currently allocated in the heap. If statistics were disabled at any time in the lifetime of the heap, this value may be inaccurate. ⚠️

This is a persistent statistic.

• stats.heap.run_allocated | r- | - | uint64_t | - | - | -

Reads the number of bytes currently allocated using run-based allocation classes — meaning huge allocations are not accounted for here. Useful for comparison against stats.heap.run_active to estimate the ratio between active and allocated memory. 🧚

This is a transient statistic and is rebuilt every time the pool is opened.

• stats.heap.run_active | r- | - | uint64_t | - | - | -

Reads the number of bytes currently occupied by all run memory blocks — both allocated and free space. So basically all the space that's not occupied by huge allocations.

This value is a sum of all allocated and free run memory. In systems where memory is efficiently used, run_active should closely track run_allocated, and the amount of active-but-free memory should be minimal. 🌸

A large relative difference between active memory and allocated memory is indicative of heap fragmentation. You can use that info to decide whether to call pmemobj_defrag()(3) if the fragmentation looks high.

However — and this is the plot twist — for small heaps, run_active might be disproportionately higher than run_allocated, because the allocator typically activates a significantly larger amount of memory than is required to satisfy a single request, anticipating future needs. For example, the first allocation of 100 bytes in a heap will trigger activation of 256 kilobytes of space. 😳

This is a transient statistic and is rebuilt lazily every time the pool is opened.

• heap.size.granularity | rw- | - | uint64_t | uint64_t | - | long long

Reads or modifies the granularity with which the heap grows when it's OOM. Valid only if the poolset has been defined with directories.

A granularity of 0 specifies that the pool will not grow automatically.

This entry point can fail if the granularity value is non-zero and smaller than PMEMOBJ_MIN_PART. Respect the minimum, bestie.

• heap.size.extend | –x | - | - | - | uint64_t | -

Extends the heap by the given size. Must be larger than PMEMOBJ_MIN_PART.

This entry point can fail if the pool does not support extend functionality, or if there's not enough space left on the device. 🫠

• debug.heap.alloc_pattern | rw | - | int | int | - | -

Single byte pattern that is used to fill new uninitialized memory allocation. If the value is negative, no pattern is written. This is intended for debugging, and is disabled by default. 🐛

---

🦋 CTL EXTERNAL CONFIGURATION 🦋

In addition to a direct function call, each write entry point can also be set using two alternative methods. Choose your fighter. ✨

1. The first method is to load a configuration directly from the PMEMOBJ_CONF environment variable.
2. The second method of loading an external configuration is to set the PMEMOBJ_CONF_FILE environment variable to point to a file that contains a sequence of ctl queries.

See more in the pmem_ctl(5) man page. iykyk 💜

---

🌈 SEE ALSO 🌈

libpmemobj(7), pmem_ctl(5) and https://pmem.io

---

And that's the whole page, bestie! 🎀 This one comes from the PMDK docs, dated 2025-07-24 — so if you're reading this way later, go vibe check the source in case anything shifted. Now go forth and manage your memory pool like the main character you are. 💅✨🫶