.\" Automatically generated by Pandoc 2.2.1 .\" .TH "PMEMOBJ_CTL_GET" "3" "2019-02-19" "PMDK - pmemobj API version 2.3" "PMDK Programmer's Manual" .hy .\" Copyright 2014-2019, 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 (EXPERIMENTAL) .SH SYNOPSIS .IP .nf \f[C] #include\ 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[](7) through the control (CTL) namespace. .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 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 If the provided ctl query is valid, the CTL functions will always return 0 on success and \-1 on failure, unless otherwise specified in the entry point description. .PP See more in \f[B]pmem_ctl\f[](5) man page. .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 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 sds.at_create | rw | global | int | int | \- | boolean .PP If set, force\-enables or force\-disables SDS feature during pool creation. Affects only the \f[B]pmemobj_create\f[]() function. See \f[B]pmempool_feature_query\f[](3) for informations about SDS (SHUTDOWN_STATE) feature. .PP tx.debug.skip_expensive_checks | rw | \- | int | int | \- | boolean .PP Turns off some expensive checks performed by the transaction module in \[lq]debug\[rq] builds. Ignored in \[lq]release\[rq] 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 entry point is not thread safe and should not be modified if there are any transactions currently running. .PP This value must be a in a range between 0 and \f[B]PMEMOBJ_MAX_ALLOC_SIZE\f[], otherwise this entry point will fail. .PP tx.cache.threshold | rw | \- | long long | long long | \- | integer .PP This entry point is deprecated. All snapshots, regardless of the size, use the transactional cache. .PP tx.post_commit.queue_depth | rw | \- | int | int | \- | integer .PP This entry point is deprecated. .PP tx.post_commit.worker | r\- | \- | void * | \- | \- | \- .PP This entry point is deprecated. .PP tx.post_commit.stop | r\- | \- | void * | \- | \- | \- .PP This entry point is deprecated. .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, 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; \ \ \ \ size_t\ alignment; \ \ \ \ 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]alignment\f[] 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. .PP The \f[C]units_per_block\f[] 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 \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. If the CTL call is being done at runtime, the \f[C]units_per_block\f[] variable of the provided alloc class structure is modified to match the actual value. .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,0,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 This entry point can fail if any of the parameters of the allocation class is invalid or if exactly the same class already exists. .PP heap.alloc_class.new.desc | \-w | \- | \- | \f[C]struct\ pobj_alloc_class_desc\f[] | \- | integer, 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'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 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 stats.heap.curr_allocated | r\- | \- | int | \- | \- | \- .PP 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. .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 entry point can fail if the granularity value is non\-zero and smaller than \f[I]PMEMOBJ_MIN_PART\f[]. .PP heap.size.extend | \[en]x | \- | \- | \- | uint64_t | \- .PP Extends the heap by the given size. Must be larger than \f[I]PMEMOBJ_MIN_PART\f[]. .PP This entry point can fail if the pool does not support extend functionality or if there's not enough space left on the device. .PP debug.heap.alloc_pattern | rw | \- | int | int | \- | \- .PP 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. .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. .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. .PP See more in \f[B]pmem_ctl\f[](5) man page. .SH SEE ALSO .PP \f[B]libpmemobj\f[](7), \f[B]pmem_ctl\f[](5) and \f[B]\f[]