.\" Automatically generated by Pandoc 1.16.0.2
.\"
.TH "PMEMOBJ_CTL_GET" "3" "2017-12-22" "PMDK - pmemobj API version 2.2" "PMDK Programmer's Manual"
.hy
.\" Copyright 2014-2017, Intel Corporation
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" * Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\"
.\" * Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in
.\" the documentation and/or other materials provided with the
.\" distribution.
.\"
.\" * Neither the name of the copyright holder nor the names of its
.\" contributors may be used to endorse or promote products derived
.\" from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
.\" OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
.\" OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.SH NAME
.PP
\f[B]pmemobj_ctl_get\f[](), \f[B]pmemobj_ctl_set\f[](),
\f[B]pmemobj_ctl_exec\f[]() \-\- Query and modify libpmemobj internal
behavior
.SH SYNOPSIS
.IP
.nf
\f[C]
#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)
\f[]
.fi
.SH DESCRIPTION
.PP
The \f[B]pmemobj_ctl_get\f[](), \f[B]pmemobj_ctl_set\f[]() and
\f[B]pmemobj_ctl_exec\f[]() functions provide a uniform interface for
querying and modifying the internal behavior of \f[B]libpmemobj\f[]
through the control (CTL) namespace.
.PP
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: \f[I]named\f[] and \f[I]indexed\f[].
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.
.PP
The \f[I]name\f[] argument specifies an entry point as defined in the
CTL namespace specification.
The entry point description specifies whether the extra \f[I]arg\f[] is
required.
Those two parameters together create a CTL query.
The \f[I]pop\f[] argument is optional if the entry point resides in a
global namespace (i.e., is shared for all the pools).
The functions and the entry points are thread\-safe unless indicated
otherwise below.
If there are special conditions for calling an entry point, they are
explicitly stated in its description.
The functions propagate the return value of the entry point.
If either \f[I]name\f[] or \f[I]arg\f[] is invalid, \-1 is returned.
.PP
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.
.PP
The entry points are listed in the following format:
.PP
name | r(ead)w(rite)x(ecute) | global/\- | read argument type | write
argument type | exec argument type | config argument type
.PP
description...
.SH CTL NAMESPACE
.PP
prefault.at_create | rw | global | int | int | \- | boolean
.PP
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 \f[B]pmemobj_create\f[]() function.
.PP
Always returns 0.
.PP
prefault.at_open | rw | global | int | int | \- | boolean
.PP
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 \f[B]pmemobj_open\f[]() function.
.PP
Always returns 0.
.PP
tx.debug.skip_expensive_checks | rw | \- | int | int | \- | boolean
.PP
Turns off some expensive checks performed by the transaction module in
"debug" builds.
Ignored in "release" builds.
.PP
tx.cache.size | rw | \- | long long | long long | \- | integer
.PP
Size in bytes of the transaction snapshot cache.
In a larger cache the frequency of persistent allocations is lower, but
with higher fixed cost.
.PP
This should be set to roughly the sum of sizes of the snapshotted
regions in an average transaction in the pool.
.PP
This value must be a in a range between 0 and
\f[B]PMEMOBJ_MAX_ALLOC_SIZE\f[].
If the current threshold is larger than the new cache size, the
threshold will be made equal to the new size.
.PP
This entry point is not thread safe and should not be modified if there
are any transactions currently running.
.PP
Returns 0 if successful, \-1 otherwise.
.PP
tx.cache.threshold | rw | \- | long long | long long | \- | integer
.PP
Threshold in bytes, below which snapshots will use the cache.
All larger snapshots will trigger a persistent allocation.
.PP
This value must be a in a range between 0 and \f[B]tx.cache.size\f[].
.PP
This entry point is not thread safe and should not be modified if there
are any transactions currently running.
.PP
Returns 0 if successful, \-1 otherwise.
.PP
tx.post_commit.queue_depth | rw | \- | int | int | \- | integer
.PP
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.
.PP
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.
.PP
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.
.PP
The queue depth value must also be a power of two.
.PP
This entry point is not thread\-safe and must be called when no
transactions are currently being executed.
.PP
Returns 0 if successful, \-1 otherwise.
.PP
tx.post_commit.worker | r\- | \- | void * | \- | \- | \-
.PP
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.
.PP
Always returns 0.
.PP
tx.post_commit.stop | r\- | \- | void * | \- | \- | \-
.PP
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.
.PP
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.
.PP
This entry point must be called when no transactions are currently being
executed.
.PP
Always returns 0.
.PP
heap.alloc_class.[class_id].desc | rw | \- |
\f[C]struct\ pobj_alloc_class_desc\f[] |
\f[C]struct\ pobj_alloc_class_desc\f[] | \- | integer, integer, string
.PP
Describes an allocation class.
Allows one to create or view the internal data structures of the
allocator.
.PP
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.
.PP
The \f[C][class_id]\f[] is an index field.
Only values between 0\-254 are valid.
If setting an allocation class, but the \f[C]class_id\f[] 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.
.PP
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.
.PP
This entry point takes a complex argument.
.IP
.nf
\f[C]
struct\ pobj_alloc_class_desc\ {
\ \ \ \ size_t\ unit_size;
\ \ \ \ unsigned\ units_per_block;
\ \ \ \ enum\ pobj_header_type\ header_type;
\ \ \ \ unsigned\ class_id;
};
\f[]
.fi
.PP
The first field, \f[C]unit_size\f[], is an 8\-byte unsigned integer that
defines the allocation class size.
While theoretically limited only by \f[B]PMEMOBJ_MAX_ALLOC_SIZE\f[], for
most workloads this value should be between 8 bytes and 2 megabytes.
.PP
The \f[C]units_per_block\f[] field defines how many units a single block
of memory contains.
This value will be rounded up to match the internal size of the block
(256 kilobytes or a multiple thereof).
For example, given a class with a \f[C]unit_size\f[] of 512 bytes and a
\f[C]units_per_block\f[] 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.
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.
.PP
The \f[C]header_type\f[] field defines the header of objects from the
allocation class.
There are three types:
.IP \[bu] 2
\f[B]POBJ_HEADER_LEGACY\f[], string value: \f[C]legacy\f[].
Used for allocation classes prior to version 1.3 of the library.
Not recommended for use.
Incurs a 64 byte metadata overhead for every object.
Fully supports all features.
.IP \[bu] 2
\f[B]POBJ_HEADER_COMPACT\f[], string value: \f[C]compact\f[].
Used as default for all predefined allocation classes.
Incurs a 16 byte metadata overhead for every object.
Fully supports all features.
.IP \[bu] 2
\f[B]POBJ_HEADER_NONE\f[], string value: \f[C]none\f[].
Header type that incurs no metadata overhead beyond a single bitmap
entry.
Can be used for very small allocation classes or when objects must be
adjacent to each other.
This header type does not support type numbers (type number is always
.RS 2
.IP "0)" 3
or allocations that span more than one unit.
.RE
.PP
The \f[C]class_id\f[] field is an optional, runtime\-only variable that
allows the user to retrieve the identifier of the class.
This will be equivalent to the provided \f[C][class_id]\f[].
This field cannot be set from a config file.
.PP
The allocation classes are a runtime state of the library and must be
created after every open.
It is highly recommended to use the configuration file to store the
classes.
.PP
This structure is declared in the \f[C]libpmemobj/ctl.h\f[] header file.
Please refer to this file for an in\-depth explanation of the allocation
classes and relevant algorithms.
.PP
Allocation classes constructed in this way can be leveraged by
explicitly specifying the class using \f[B]POBJ_CLASS_ID(id)\f[] flag in
\f[B]pmemobj_tx_xalloc\f[]()/\f[B]pmemobj_xalloc\f[]() functions.
.PP
Example of a valid alloc class query string:
.IP
.nf
\f[C]
heap.alloc_class.128.desc=500,1000,compact
\f[]
.fi
.PP
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.
.PP
For reading, function returns 0 if successful, if the allocation class
does not exist it sets the errno to \f[B]ENOENT\f[] and returns \-1;
.PP
For writing, function returns 0 if the allocation class has been
successfully created, \-1 otherwise.
.PP
heap.alloc_class.new.desc | \-w | \- | \- |
\f[C]struct\ pobj_alloc_class_desc\f[] | \- | integer, integer, string
.PP
Same as \f[C]heap.alloc_class.[class_id].desc\f[], but instead of
requiring the user to provide the class_id, it automatically creates the
allocation class with the first available identifier.
.PP
This should be used when it\[aq]s impossible to guarantee unique
allocation class naming in the application (e.g.
when writing a library that uses libpmemobj).
.PP
The required class identifier will be stored in the \f[C]class_id\f[]
field of the \f[C]struct\ pobj_alloc_class_desc\f[].
.PP
This function returns 0 if the allocation class has been successfully
created, \-1 otherwise.
.PP
stats.enabled | rw | \- | int | int | \- | boolean
.PP
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.
.PP
Statistics are disabled by default.
Enabling them may have non\-trivial performance impact.
.PP
Always returns 0.
.PP
stats.heap.allocated_curr | r\- | \- | int | \- | \- | \-
.PP
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.
.PP
heap.size.granularity | rw\- | \- | uint64_t | uint64_t | \- | long long
.PP
Reads or modifies the granularity with which the heap grows when OOM.
Valid only if the poolset has been defined with directories.
.PP
A granularity of 0 specifies that the pool will not grow automatically.
.PP
This function returns 0 if the granularity value is 0, or is larger than
\f[I]PMEMOBJ_MIN_PART\f[], \-1 otherwise.
.PP
heap.size.extend | \-\-x | \- | \- | \- | uint64_t | \-
.PP
Extends the heap by the given size.
Must be larger than \f[I]PMEMOBJ_MIN_PART\f[].
.PP
This function returns 0 if successful, \-1 otherwise.
.SH CTL EXTERNAL CONFIGURATION
.PP
In addition to direct function call, each write entry point can also be
set using two alternative methods.
.PP
The first method is to load a configuration directly from the
\f[B]PMEMOBJ_CONF\f[] environment variable.
A properly formatted ctl config string is a single\-line sequence of
queries separated by \[aq];\[aq]:
.IP
.nf
\f[C]
query0;query1;...;queryN
\f[]
.fi
.PP
A single query is constructed from the name of the ctl write entry point
and the argument, separated by \[aq]=\[aq]:
.IP
.nf
\f[C]
entry_point=entry_point_argument
\f[]
.fi
.PP
The entry point argument type is defined by the entry point itself, but
there are three predefined primitives:
.IP
.nf
\f[C]
*)\ 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.
\f[]
.fi
.PP
There are also complex argument types that are formed from the
primitives separated by a \[aq],\[aq]:
.IP
.nf
\f[C]
first_arg,second_arg
\f[]
.fi
.PP
In summary, a full configuration sequence looks like this:
.IP
.nf
\f[C]
(first_entry_point)=(arguments,\ ...);...;(last_entry_point)=(arguments,\ ...);
\f[]
.fi
.PP
As an example, to set both prefault at_open and at_create variables:
.IP
.nf
\f[C]
PMEMOBJ_CONF="prefault.at_open=1;prefault.at_create=1"
\f[]
.fi
.PP
The second method of loading an external configuration is to set the
\f[B]PMEMOBJ_CONF_FILE\f[] 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.
.PP
To create a comment, simply use \[aq]#\[aq] anywhere in a line and
everything afterwards, until a new line \[aq]\[aq], will be ignored.
.PP
An example configuration file:
.IP
.nf
\f[C]
#########################
#\ 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\[aq]t\ prefault\ when\ it\[aq]s\ created
#\ Per\-pool\ settings:
#\ ...
\f[]
.fi
.SH SEE ALSO
.PP
\f[B]libpmemobj\f[](7) and \f[B]<http://pmem.io>\f[]