
CTL NAMESPACE
CTL EXTERNAL CONFIGURATION
SEE ALSO
pmemobj_ctl_get(), pmemobj_ctl_set(), pmemobj_ctl_exec()
)
The pmemobj_ctl_get(), pmemobj_ctl_set() and pmemobj_ctl_exec() functions provide a uniform interface for querying and modifying the internal behavior of libpmemobj through the control (CTL) namespace.
The CTL namespace is organized in a tree structure. Starting from the root, each node can be either internal, containing other elements, or a leaf. Internal nodes themselves can only contain other nodes and cannot be entry points. There are two types of those nodes: named and indexed. Named nodes have string identifiers. Indexed nodes represent an abstract array index and have an associated string identifier. The index itself is provided by the user. A collection of indexes present on the path of an entry point is provided to the handler functions as name and index pairs.
The name argument specifies an entry point as defined in the CTL namespace specification. The entry point description specifies whether the extra arg is required. Those two parameters together create a CTL query. The pop argument is optional if the entry point resides in a global namespace (i.e., is shared for all the pools)..
Entry points are the leaves of the CTL namespace structure. Each entry point can read from the internal state, write to the internal state, exec a function or a combination of these operations.
The entry points are listed in the following format:
name | r(ead)w(rite)x(ecute) | global/- | read argument type | write argument type | exec argument type | config argument type
description….
Always returns 0.
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. value must be a in a range between 0 and PMEMOBJ_MAX_ALLOC_SIZE. If the current threshold is larger than the new cache size, the threshold will be made equal to the new size.
This entry point is not thread safe and should not be modified if there are any transactions currently running.
Returns 0 if successful, -1 otherwise.
tx.cache.threshold | rw | - | long long | long long | - | integer
Threshold in bytes, below which snapshots will use the cache. All larger snapshots will trigger a persistent allocation.
This value must be a in a range between 0 and tx.cache.size.
This entry point is not thread safe and should not be modified if there are any transactions currently running.
Returns 0 if successful, -1 otherwise.
tx.post_commit.queue_depth | rw | - | int | int | - | integer
Controls the depth of the post-commit tasks queue. A post-commit task is the collection of work items that need to be performed on the persistent state after a successfully completed transaction. This includes freeing no longer needed objects and cleaning up various caches. By default, this queue does not exist and the post-commit task is executed synchronously in the same thread that ran the transaction. By changing this parameter, one can offload this task to a separate worker. If the queue is full, the algorithm, instead of waiting, performs the post-commit in the current thread.
The task is performed on a finite resource (lanes, of which there are 1024), and if the worker threads that process this queue are unable to keep up with the demand, regular threads might start to block waiting for that resource. This will happen if the queue depth value is too large.
As a general rule, this value should be set to approximately 1024 minus the average number of threads in the application (not counting the post-commit workers); however, this may vary from workload to workload.
The queue depth value must also be a power of two.
This entry point is not thread-safe and must be called when no transactions are currently being executed.
Returns 0 if successful, -1 otherwise.
tx.post_commit.worker | r- | - | void * | - | - | -
The worker function launched in a thread to perform asynchronous processing of post-commit tasks. This function returns only after a stop entry point is called. There may be many worker threads at a time. If there is no work to be done, this function sleeps instead of polling.
Always returns 0.
tx.post_commit.stop | r- | - | void * | - | - | -
This function forces all the post-commit worker functions to exit and return control back to the calling thread. This should be called before the application terminates and the post commit worker threads need to be shutdown.
After the invocation of this entry point, the post-commit task queue can no longer be used. If worker threads must be restarted after a stop, the tx.post_commit.queue_depth needs to be set again.
This entry point must be called when no transactions are currently being executed.
Always returns 0. is currently unsupported and must be set to 0. 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 rounded up.
Keep in mind that object allocation is tracked in a bitmap with a limited
number of entries, making it inefficient to create allocation classes smaller
than 128 bytes..;
For writing, function returns 0 if the allocation class has been successfully created, -1 otherwise..
This function returns 0 if the allocation class has been successfully created, -1 otherwise.
stats.enabled | rw | - | int | int | - | boolean
Enables or disables runtime collection of statistics. Statistics are not recalculated after enabling; any operations that occur between disabling and re-enabling will not be reflected in subsequent values.
Statistics are disabled by default. Enabling them may have non-trivial performance impact.
Always returns 0.
stats.heap.curr_allocated | r- | - | int | - | - | -
Returns 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. function returns 0 if the granularity value is 0, or is larger than PMEMOBJ_MIN_PART, -1 otherwise.
heap.size.extend | –x | - | - | - | uint64_t | -
Extends the heap by the given size. Must be larger than PMEMOBJ_MIN_PART.
This function returns 0 if successful, -1 otherwise.
In addition to direct function call, each write entry point can also be set using two alternative methods.
The first method is to load a configuration directly from the PMEMOBJ_CONF environment variable. A properly formatted ctl config string is a single-line sequence of queries separated by ‘;':
query0;query1;...;queryN
A single query is constructed from the name of the ctl write entry point and the argument, separated by ‘=':
entry_point=entry_point_argument
The entry point argument type is defined by the entry point itself, but there are three predefined primitives:
*) integer: represented by a sequence of [0-9] characters that form a single number. *) boolean: represented by a single character: y/n/Y/N/0/1, each corresponds to true or false. If the argument contains any trailing characters, they are ignored. *) string: a simple sequence of characters.
There are also complex argument types that are formed from the primitives separated by a ‘,':
first_arg,second_arg
In summary, a full configuration sequence looks like this:
(first_entry_point)=(arguments, ...);...;(last_entry_point)=(arguments, ...);
As an example, to set both prefault at_open and at_create variables:
PMEMOBJ_CONF="prefault.at_open=1;prefault.at_create=1"
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. The parsing rules are all the same, but the file can also contain white-spaces and comments.
To create a comment, simply use ‘#’ anywhere in a line and everything afterwards, until a new line ‘\n’, will be ignored.
An example configuration file:
######################### # My pmemobj configuration ######################### # # Global settings: prefault. # modify the behavior of pre-faulting at_open = 1; # prefault when the pool is opened prefault. at_create = 0; # but don't prefault when it's created # Per-pool settings: # ...
libpmemobj(7) and
The contents of this web site and the associated GitHub repositories are BSD-licensed open source.