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 name‐
22 space 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 information 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.debug.verify_user_buffers | rw | - | int | int | - | boolean
70 Enables verification of user buffers provided by pmemobj_tx_log_ap‐
72 pend_buffer(3) API. For now the only verified aspect is whether the
73 same buffer is used simultaneously in 2 or more transactions or more
74 than once in the same transaction. This value should not be modified
75 at runtime if any transaction for the current pool is in progress.
76 tx.cache.size | rw | - | long long | long long | - | integer
78 Size in bytes of the transaction snapshot cache. In a larger cache the
80 frequency of persistent allocations is lower, but with higher fixed
81 cost.
82 This should be set to roughly the sum of sizes of the snapshotted re‐
84 gions in an average transaction in the pool.
85 This entry point is not thread safe and should not be modified if there
87 are any transactions currently running.
88 This value must be a in a range between 0 and PMEMOBJ_MAX_ALLOC_SIZE,
90 otherwise this entry point will fail.
91 tx.cache.threshold | rw | - | long long | long long | - | integer
93 This entry point is deprecated. All snapshots, regardless of the size,
95 use the transactional cache.
96 tx.post_commit.queue_depth | rw | - | int | int | - | integer
98 This entry point is deprecated.
100 tx.post_commit.worker | r- | - | void * | - | - | -
102 This entry point is deprecated.
104 tx.post_commit.stop | r- | - | void * | - | - | -
106 This entry point is deprecated.
108 heap.narenas.automatic | r- | - | unsigned | - | - | -
110 Reads the number of arenas used in automatic scheduling of memory oper‐
112 ations for threads. By default, this value is equal to the number of
113 available processors. An arena is a memory management structure which
114 enables concurrency by taking exclusive ownership of parts of the heap
115 and allowing associated threads to allocate without contention.
116 heap.narenas.total | r- | - | unsigned | - | - | -
118 Reads the number of all created arenas. It includes automatic arenas
120 created by default and arenas created using heap.arena.create CTL.
121 heap.narenas.max | rw- | - | unsigned | unsigned | - | -
123 Reads or writes the maximum number of arenas that can be created. This
125 entry point is not thread-safe with regards to heap operations (alloca‐
126 tions, frees, reallocs).
127 heap.arena.[arena_id].size | r- | - | uint64_t | - | - | -
129 Reads the total amount of memory in bytes which is currently exclusive‐
131 ly owned by the arena. Large differences in this value between arenas
132 might indicate an uneven scheduling of memory resources. The arena id
133 cannot be 0.
134 heap.thread.arena_id | rw- | - | unsigned | unsigned | - | -
136 Reads the index of the arena assigned to the current thread or assigns
138 arena with specific id to the current thread. The arena id cannot be
139 0.
140 heap.arena.create | –x | - | - | - | unsigned | -
142 Creates and initializes one new arena in the heap. This entry point
144 reads an id of the new created arena.
145 Newly created arenas by this CTL are inactive, which means that the
147 arena will not be used in the automatic scheduling of memory requests.
148 To activate the new arena, use heap.arena.[arena_id].automatic CTL.
149 Arena created using this CTL can be used for allocation by explicitly
151 specifying the arena_id for POBJ_ARENA_ID(id) flag in pmemobj_tx_xal‐
152 loc()/pmemobj_xalloc()/pmemobj_xreserve() functions.
153 By default, the number of arenas is limited to 1024.
155 heap.arena.[arena_id].automatic | rw- | - | boolean | boolean | - | -
157 Reads or modifies the state of the arena. If set, the arena is used in
159 automatic scheduling of memory operations for threads. This should be
160 set to false if the application wants to manually manage allocator
161 scalability through explicitly assigning arenas to threads by using
162 heap.thread.arena_id. The arena id cannot be 0 and at least one auto‐
163 matic arena must exist.
164 heap.alloc_class.[class_id].desc | rw | - | struct pobj_alloc_class_de‐
166 sc | struct pobj_alloc_class_desc | - | integer, integer, integer,
167 string
168 Describes an allocation class. Allows one to create or view the inter‐
170 nal data structures of the allocator.
171 Creating custom allocation classes can be beneficial for both raw allo‐
173 cation throughput, scalability and, most importantly, fragmentation.
174 By carefully constructing allocation classes that match the application
175 workload, one can entirely eliminate external and internal fragmenta‐
176 tion. For example, it is possible to easily construct a slab-like al‐
177 location mechanism for any data structure.
178 The [class_id] is an index field. Only values between 0-254 are valid.
180 If setting an allocation class, but the class_id is already taken, the
181 function will return -1. The values between 0-127 are reserved for the
182 default allocation classes of the library and can be used only for
183 reading.
184 The recommended method for retrieving information about all allocation
186 classes is to call this entry point for all class ids between 0 and 254
187 and discard those results for which the function returns an error.
188 This entry point takes a complex argument.
190 struct pobj_alloc_class_desc {
192 size_t unit_size;
193 size_t alignment;
194 unsigned units_per_block;
195 enum pobj_header_type header_type;
196 unsigned class_id;
197 };
198 The first field, unit_size, is an 8-byte unsigned integer that defines
200 the allocation class size. While theoretically limited only by PMEMO‐
201 BJ_MAX_ALLOC_SIZE, for most workloads this value should be between 8
202 bytes and 2 megabytes.
203 The alignment field specifies the user data alignment of objects allo‐
205 cated using the class. If set, must be a power of two and an even di‐
206 visor of unit size. Alignment is limited to maximum of 2 megabytes.
207 All objects have default alignment of 64 bytes, but the user data
208 alignment is affected by the size of the chosen header.
209 The units_per_block field defines how many units a single block of mem‐
211 ory contains. This value will be adjusted to match the internal size
212 of the block (256 kilobytes or a multiple thereof). For example, given
213 a class with a unit_size of 512 bytes and a units_per_block of 1000, a
214 single block of memory for that class will have 512 kilobytes. This is
215 relevant because the bigger the block size, the less frequently blocks
216 need to be fetched, resulting in lower contention on global heap state.
217 If the CTL call is being done at runtime, the units_per_block variable
218 of the provided alloc class structure is modified to match the actual
219 value.
220 The header_type field defines the header of objects from the allocation
222 class. There are three types:
223 • POBJ_HEADER_LEGACY, string value: legacy. Used for allocation class‐
225 es prior to version 1.3 of the library. Not recommended for use.
226 Incurs a 64 byte metadata overhead for every object. Fully supports
227 all features.
228 • POBJ_HEADER_COMPACT, string value: compact. Used as default for all
230 predefined allocation classes. Incurs a 16 byte metadata overhead
231 for every object. Fully supports all features.
232 • POBJ_HEADER_NONE, string value: none. Header type that incurs no
234 metadata overhead beyond a single bitmap entry. Can be used for very
235 small allocation classes or when objects must be adjacent to each
236 other. This header type does not support type numbers (type number
237 is always
238 0) or allocations that span more than one unit.
240 The class_id field is an optional, runtime-only variable that allows
242 the user to retrieve the identifier of the class. This will be equiva‐
243 lent to the provided [class_id]. This field cannot be set from a con‐
244 fig file.
245 The allocation classes are a runtime state of the library and must be
247 created after every open. It is highly recommended to use the configu‐
248 ration file to store the classes.
249 This structure is declared in the libpmemobj/ctl.h header file. Please
251 refer to this file for an in-depth explanation of the allocation class‐
252 es and relevant algorithms.
253 Allocation classes constructed in this way can be leveraged by explic‐
255 itly specifying the class using POBJ_CLASS_ID(id) flag in pmemo‐
256 bj_tx_xalloc()/pmemobj_xalloc() functions.
257 Example of a valid alloc class query string:
259 heap.alloc_class.128.desc=500,0,1000,compact
261 This query, if executed, will create an allocation class with an id of
263 128 that has a unit size of 500 bytes, has at least 1000 units per
264 block and uses a compact header.
265 For reading, function returns 0 if successful, if the allocation class
267 does not exist it sets the errno to ENOENT and returns -1;
268 This entry point can fail if any of the parameters of the allocation
270 class is invalid or if exactly the same class already exists.
271 heap.alloc_class.new.desc | -w | - | - | struct pobj_alloc_class_desc |
273 - | integer, integer, integer, string
274 Same as heap.alloc_class.[class_id].desc, but instead of requiring the
276 user to provide the class_id, it automatically creates the allocation
277 class with the first available identifier.
278 This should be used when it’s impossible to guarantee unique allocation
280 class naming in the application (e.g. when writing a library that uses
281 libpmemobj).
282 The required class identifier will be stored in the class_id field of
284 the struct pobj_alloc_class_desc.
285 stats.enabled | rw | - | enum pobj_stats_enabled | enum pobj_stats_en‐
287 abled | - | string
288 Enables or disables runtime collection of statistics. There are two
290 types of statistics: persistent and transient ones. Persistent statis‐
291 tics survive pool restarts, whereas transient ones don’t. Statistics
292 are not recalculated after enabling; any operations that occur between
293 disabling and re-enabling will not be reflected in subsequent values.
294 Only transient statistics are enabled by default. Enabling persistent
296 statistics may have non-trivial performance impact.
297 stats.heap.curr_allocated | r- | - | uint64_t | - | - | -
299 Reads the number of bytes currently allocated in the heap. If statis‐
301 tics were disabled at any time in the lifetime of the heap, this value
302 may be inaccurate.
303 This is a persistent statistic.
305 stats.heap.run_allocated | r- | - | uint64_t | - | - | -
307 Reads the number of bytes currently allocated using run-based alloca‐
309 tion classes, i.e., huge allocations are not accounted for in this
310 statistic. This is useful for comparison against stats.heap.run_active
311 to estimate the ratio between active and allocated memory.
312 This is a transient statistic and is rebuilt every time the pool is
314 opened.
315 stats.heap.run_active | r- | - | uint64_t | - | - | -
317 Reads the number of bytes currently occupied by all run memory blocks,
319 including both allocated and free space, i.e., this is all the all
320 space that’s not occupied by huge allocations.
321 This value is a sum of all allocated and free run memory. In systems
323 where memory is efficiently used, run_active should closely track
324 run_allocated, and the amount of active, but free, memory should be
325 minimal.
326 A large relative difference between active memory and allocated memory
328 is indicative of heap fragmentation. This information can be used to
329 make a decision to call pmemobj_defrag()[22m(3) if the fragmentation looks
330 to be high.
331 However, for small heaps run_active might be disproportionately higher
333 than run_allocated because the allocator typically activates a signifi‐
334 cantly larger amount of memory than is required to satisfy a single re‐
335 quest in the anticipation of future needs. For example, the first al‐
336 location of 100 bytes in a heap will trigger activation of 256 kilo‐
337 bytes of space.
338 This is a transient statistic and is rebuilt lazily every time the pool
340 is opened.
341 heap.size.granularity | rw- | - | uint64_t | uint64_t | - | long long
343 Reads or modifies the granularity with which the heap grows when OOM.
345 Valid only if the poolset has been defined with directories.
346 A granularity of 0 specifies that the pool will not grow automatically.
348 This entry point can fail if the granularity value is non-zero and
350 smaller than PMEMOBJ_MIN_PART.
351 heap.size.extend | –x | - | - | - | uint64_t | -
353 Extends the heap by the given size. Must be larger than PMEMO‐
355 BJ_MIN_PART.
356 This entry point can fail if the pool does not support extend function‐
358 ality or if there’s not enough space left on the device.
359 debug.heap.alloc_pattern | rw | - | int | int | - | -
361 Single byte pattern that is used to fill new uninitialized memory allo‐
363 cation. If the value is negative, no pattern is written. This is in‐
364 tended for debugging, and is disabled by default.
365
367 In addition to direct function call, each write entry point can also be
368 set using two alternative methods.
369 The first method is to load a configuration directly from the PMEMO‐
371 BJ_CONF environment variable.
372 The second method of loading an external configuration is to set the
374 PMEMOBJ_CONF_FILE environment variable to point to a file that contains
375 a sequence of ctl queries.
376 See more in pmem_ctl(5) man page.
378
380 libpmemobj(7), pmem_ctl(5) and <https://pmem.io>
381PMDK - pmemobj API version 2.3 2020-10-28 PMEMOBJ_CTL_GET(3)