1PMEMOBJ_CTL_GET(3) PMDK Programmer's Manual PMEMOBJ_CTL_GET(3)
2
6 pmemobj_ctl_get(), pmemobj_ctl_set(), pmemobj_ctl_exec() - Query and
7 modify libpmemobj internal behavior (EXPERIMENTAL)
8
10 #include <libpmemobj.h>
11 int pmemobj_ctl_get(PMEMobjpool *pop, const char *name, void *arg); (EXPERIMENTAL)
13 int pmemobj_ctl_set(PMEMobjpool *pop, const char *name, void *arg); (EXPERIMENTAL)
14 int pmemobj_ctl_exec(PMEMobjpool *pop, const char *name, void *arg); (EXPERIMENTAL)
15
17 The pmemobj_ctl_get(), pmemobj_ctl_set() and pmemobj_ctl_exec() func‐
18 tions provide a uniform interface for querying and modifying the inter‐
19 nal behavior of libpmemobj(7) through the control (CTL) namespace.
20 The name argument specifies an entry point as defined in the CTL names‐
22 pace specification. The entry point description specifies whether the
23 extra arg is required. Those two parameters together create a CTL
24 query. The functions and the entry points are thread-safe unless indi‐
25 cated otherwise below. If there are special conditions for calling an
26 entry point, they are explicitly stated in its description. The func‐
27 tions propagate the return value of the entry point. If either name or
28 arg is invalid, -1 is returned.
29 If the provided ctl query is valid, the CTL functions will always re‐
31 turn 0 on success and -1 on failure, unless otherwise specified in the
32 entry point description.
33 See more in pmem_ctl(5) man page.
35
37 prefault.at_create | rw | global | int | int | - | boolean
38 If set, every page of the pool will be touched and written to when the
40 pool is created, in order to trigger page allocation and minimize the
41 performance impact of pagefaults. Affects only the pmemobj_create()
42 function.
43 prefault.at_open | rw | global | int | int | - | boolean
45 If set, every page of the pool will be touched and written to when the
47 pool is opened, in order to trigger page allocation and minimize the
48 performance impact of pagefaults. Affects only the pmemobj_open()
49 function.
50 sds.at_create | rw | global | int | int | - | boolean
52 If set, force-enables or force-disables SDS feature during pool cre‐
54 ation. Affects only the pmemobj_create() function. See pmempool_fea‐
55 ture_query(3) for informations about SDS (SHUTDOWN_STATE) feature.
56 copy_on_write.at_open | rw | global | int | int | - | boolean
58 If set, pool is mapped in such a way that modifications don't reach the
60 underlying medium. From the user's perspective this means that when
61 the pool is closed all changes are reverted. This feature is not sup‐
62 ported for pools located on Device DAX.
63 tx.debug.skip_expensive_checks | rw | - | int | int | - | boolean
65 Turns off some expensive checks performed by the transaction module in
67 “debug” builds. Ignored in “release” builds.
68 tx.cache.size | rw | - | long long | long long | - | integer
70 Size in bytes of the transaction snapshot cache. In a larger cache the
72 frequency of persistent allocations is lower, but with higher fixed
73 cost.
74 This should be set to roughly the sum of sizes of the snapshotted re‐
76 gions in an average transaction in the pool.
77 This entry point is not thread safe and should not be modified if there
79 are any transactions currently running.
80 This value must be a in a range between 0 and PMEMOBJ_MAX_ALLOC_SIZE,
82 otherwise this entry point will fail.
83 tx.cache.threshold | rw | - | long long | long long | - | integer
85 This entry point is deprecated. All snapshots, regardless of the size,
87 use the transactional cache.
88 tx.post_commit.queue_depth | rw | - | int | int | - | integer
90 This entry point is deprecated.
92 tx.post_commit.worker | r- | - | void * | - | - | -
94 This entry point is deprecated.
96 tx.post_commit.stop | r- | - | void * | - | - | -
98 This entry point is deprecated.
100 heap.narenas.automatic | r- | - | unsigned | - | - | -
102 Reads the number of arenas used in automatic scheduling of memory oper‐
104 ations for threads. By default, this value is equal to the number of
105 available processors. An arena is a memory management structure which
106 enables concurrency by taking exclusive ownership of parts of the heap
107 and allowing associated threads to allocate without contention.
108 heap.narenas.total | r- | - | unsigned | - | - | -
110 Reads the number of all created arenas. It includes automatic arenas
112 created by default and arenas created using heap.arena.create CTL.
113 heap.narenas.max | rw- | - | unsigned | unsigned | - | -
115 Reads or writes the maximum number of arenas that can be created. This
117 entry point is not thread-safe with regards to heap operations (alloca‐
118 tions, frees, reallocs).
119 heap.arena.[arena_id].size | r- | - | uint64_t | - | - | -
121 Reads the total amount of memory in bytes which is currently exclusive‐
123 ly owned by the arena. Large differences in this value between arenas
124 might indicate an uneven scheduling of memory resources. The arena id
125 cannot be 0.
126 heap.thread.arena_id | rw- | - | unsigned | unsigned | - | -
128 Reads the index of the arena assigned to the current thread or assigns
130 arena with specific id to the current thread. The arena id cannot be
131 0.
132 heap.arena.create | –x | - | - | - | unsigned | -
134 Creates and initializes one new arena in the heap. This entry point
136 reads an id of the new created arena.
137 Newly created arenas by this CTL are inactive, which means that the
139 arena will not be used in the automatic scheduling of memory requests.
140 To activate the new arena, use heap.arena.[arena_id].automatic CTL.
141 Arena created using this CTL can be used for allocation by explicitly
143 specifying the arena_id for POBJ_ARENA_ID(id) flag in pmemobj_tx_xal‐
144 loc()/pmemobj_xalloc()/pmemobj_xreserve() functions.
145 By default, the number of arenas is limited to 1024.
147 heap.arena.[arena_id].automatic | rw- | - | boolean | boolean | - | -
149 Reads or modifies the state of the arena. If set, the arena is used in
151 automatic scheduling of memory operations for threads. This should be
152 set to false if the application wants to manually manage allocator
153 scalability through explicitly assigning arenas to threads by using
154 heap.thread.arena_id. The arena id cannot be 0 and at least one auto‐
155 matic arena must exist.
156 heap.alloc_class.[class_id].desc | rw | - | struct pobj_alloc_class_de‐
158 sc | struct pobj_alloc_class_desc | - | integer, integer, integer,
159 string
160 Describes an allocation class. Allows one to create or view the inter‐
162 nal data structures of the allocator.
163 Creating custom allocation classes can be beneficial for both raw allo‐
165 cation throughput, scalability and, most importantly, fragmentation.
166 By carefully constructing allocation classes that match the application
167 workload, one can entirely eliminate external and internal fragmenta‐
168 tion. For example, it is possible to easily construct a slab-like al‐
169 location mechanism for any data structure.
170 The [class_id] is an index field. Only values between 0-254 are valid.
172 If setting an allocation class, but the class_id is already taken, the
173 function will return -1. The values between 0-127 are reserved for the
174 default allocation classes of the library and can be used only for
175 reading.
176 The recommended method for retrieving information about all allocation
178 classes is to call this entry point for all class ids between 0 and 254
179 and discard those results for which the function returns an error.
180 This entry point takes a complex argument.
182 struct pobj_alloc_class_desc {
184 size_t unit_size;
185 size_t alignment;
186 unsigned units_per_block;
187 enum pobj_header_type header_type;
188 unsigned class_id;
189 };
190 The first field, unit_size, is an 8-byte unsigned integer that defines
192 the allocation class size. While theoretically limited only by PMEMO‐
193 BJ_MAX_ALLOC_SIZE, for most workloads this value should be between 8
194 bytes and 2 megabytes.
195 The alignment field specifies the user data alignment of objects allo‐
197 cated using the class. If set, must be a power of two and an even di‐
198 visor of unit size. Alignment is limited to maximum of 2 megabytes.
199 All objects have default alignment of 64 bytes, but the user data
200 alignment is affected by the size of the chosen header.
201 The units_per_block field defines how many units a single block of mem‐
203 ory contains. This value will be adjusted to match the internal size
204 of the block (256 kilobytes or a multiple thereof). For example, given
205 a class with a unit_size of 512 bytes and a units_per_block of 1000, a
206 single block of memory for that class will have 512 kilobytes. This is
207 relevant because the bigger the block size, the less frequently blocks
208 need to be fetched, resulting in lower contention on global heap state.
209 If the CTL call is being done at runtime, the units_per_block variable
210 of the provided alloc class structure is modified to match the actual
211 value.
212 The header_type field defines the header of objects from the allocation
214 class. There are three types:
215 · POBJ_HEADER_LEGACY, string value: legacy. Used for allocation class‐
217 es prior to version 1.3 of the library. Not recommended for use.
218 Incurs a 64 byte metadata overhead for every object. Fully supports
219 all features.
220 · POBJ_HEADER_COMPACT, string value: compact. Used as default for all
222 predefined allocation classes. Incurs a 16 byte metadata overhead
223 for every object. Fully supports all features.
224 · POBJ_HEADER_NONE, string value: none. Header type that incurs no
226 metadata overhead beyond a single bitmap entry. Can be used for very
227 small allocation classes or when objects must be adjacent to each
228 other. This header type does not support type numbers (type number
229 is always
230 0) or allocations that span more than one unit.
232 The class_id field is an optional, runtime-only variable that allows
234 the user to retrieve the identifier of the class. This will be equiva‐
235 lent to the provided [class_id]. This field cannot be set from a con‐
236 fig file.
237 The allocation classes are a runtime state of the library and must be
239 created after every open. It is highly recommended to use the configu‐
240 ration file to store the classes.
241 This structure is declared in the libpmemobj/ctl.h header file. Please
243 refer to this file for an in-depth explanation of the allocation class‐
244 es and relevant algorithms.
245 Allocation classes constructed in this way can be leveraged by explic‐
247 itly specifying the class using POBJ_CLASS_ID(id) flag in pmemo‐
248 bj_tx_xalloc()/pmemobj_xalloc() functions.
249 Example of a valid alloc class query string:
251 heap.alloc_class.128.desc=500,0,1000,compact
253 This query, if executed, will create an allocation class with an id of
255 128 that has a unit size of 500 bytes, has at least 1000 units per
256 block and uses a compact header.
257 For reading, function returns 0 if successful, if the allocation class
259 does not exist it sets the errno to ENOENT and returns -1;
260 This entry point can fail if any of the parameters of the allocation
262 class is invalid or if exactly the same class already exists.
263 heap.alloc_class.new.desc | -w | - | - | struct pobj_alloc_class_desc |
265 - | integer, integer, integer, string
266 Same as heap.alloc_class.[class_id].desc, but instead of requiring the
268 user to provide the class_id, it automatically creates the allocation
269 class with the first available identifier.
270 This should be used when it's impossible to guarantee unique allocation
272 class naming in the application (e.g. when writing a library that uses
273 libpmemobj).
274 The required class identifier will be stored in the class_id field of
276 the struct pobj_alloc_class_desc.
277 stats.enabled | rw | - | int | int | - | boolean
279 Enables or disables runtime collection of statistics. Statistics are
281 not recalculated after enabling; any operations that occur between dis‐
282 abling and re-enabling will not be reflected in subsequent values.
283 Statistics are disabled by default. Enabling them may have non-trivial
285 performance impact.
286 stats.heap.curr_allocated | r- | - | int | - | - | -
288 Reads the number of bytes currently allocated in the heap. If statis‐
290 tics were disabled at any time in the lifetime of the heap, this value
291 may be inaccurate.
292 heap.size.granularity | rw- | - | uint64_t | uint64_t | - | long long
294 Reads or modifies the granularity with which the heap grows when OOM.
296 Valid only if the poolset has been defined with directories.
297 A granularity of 0 specifies that the pool will not grow automatically.
299 This entry point can fail if the granularity value is non-zero and
301 smaller than PMEMOBJ_MIN_PART.
302 heap.size.extend | –x | - | - | - | uint64_t | -
304 Extends the heap by the given size. Must be larger than PMEMO‐
306 BJ_MIN_PART.
307 This entry point can fail if the pool does not support extend function‐
309 ality or if there's not enough space left on the device.
310 debug.heap.alloc_pattern | rw | - | int | int | - | -
312 Single byte pattern that is used to fill new uninitialized memory allo‐
314 cation. If the value is negative, no pattern is written. This is in‐
315 tended for debugging, and is disabled by default.
316
318 In addition to direct function call, each write entry point can also be
319 set using two alternative methods.
320 The first method is to load a configuration directly from the PMEMO‐
322 BJ_CONF environment variable.
323 The second method of loading an external configuration is to set the
325 PMEMOBJ_CONF_FILE environment variable to point to a file that contains
326 a sequence of ctl queries.
327 See more in pmem_ctl(5) man page.
329
331 libpmemobj(7), pmem_ctl(5) and <http://pmem.io>
332PMDK - pmemobj API version 2.3 2019-03-01 PMEMOBJ_CTL_GET(3)