1PMEMOBJ_CTL_GET(3)         PMDK Programmer's Manual         PMEMOBJ_CTL_GET(3)
2
3
4

NAME

6       pmemobj_ctl_get(),  pmemobj_ctl_set(),  pmemobj_ctl_exec()  - Query and
7       modify libpmemobj internal behavior (EXPERIMENTAL)
8

SYNOPSIS

10              #include <libpmemobj.h>
11
12              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

DESCRIPTION

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
21       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
30       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
34       See more in pmem_ctl(5) man page.
35

CTL NAMESPACE

37       prefault.at_create | rw | global | int | int | - | boolean
38
39       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
44       prefault.at_open | rw | global | int | int | - | boolean
45
46       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
51       sds.at_create | rw | global | int | int | - | boolean
52
53       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
57       copy_on_write.at_open | rw | global | int | int | - | boolean
58
59       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
64       tx.debug.skip_expensive_checks | rw | - | int | int | - | boolean
65
66       Turns off some expensive checks performed by the transaction module  in
67       “debug” builds.  Ignored in “release” builds.
68
69       tx.debug.verify_user_buffers | rw | - | int | int | - | boolean
70
71       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
77       tx.cache.size | rw | - | long long | long long | - | integer
78
79       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
83       This  should  be set to roughly the sum of sizes of the snapshotted re‐
84       gions in an average transaction in the pool.
85
86       This entry point is not thread safe and should not be modified if there
87       are any transactions currently running.
88
89       This  value  must be a in a range between 0 and PMEMOBJ_MAX_ALLOC_SIZE,
90       otherwise this entry point will fail.
91
92       tx.cache.threshold | rw | - | long long | long long | - | integer
93
94       This entry point is deprecated.  All snapshots, regardless of the size,
95       use the transactional cache.
96
97       tx.post_commit.queue_depth | rw | - | int | int | - | integer
98
99       This entry point is deprecated.
100
101       tx.post_commit.worker | r- | - | void * | - | - | -
102
103       This entry point is deprecated.
104
105       tx.post_commit.stop | r- | - | void * | - | - | -
106
107       This entry point is deprecated.
108
109       heap.narenas.automatic | r- | - | unsigned | - | - | -
110
111       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
117       heap.narenas.total | r- | - | unsigned | - | - | -
118
119       Reads  the  number of all created arenas.  It includes automatic arenas
120       created by default and arenas created using heap.arena.create CTL.
121
122       heap.narenas.max | rw- | - | unsigned | unsigned | - | -
123
124       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
128       heap.arena.[arena_id].size | r- | - | uint64_t | - | - | -
129
130       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
135       heap.thread.arena_id | rw- | - | unsigned | unsigned | - | -
136
137       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
141       heap.arena.create | –x | - | - | - | unsigned | -
142
143       Creates  and  initializes  one new arena in the heap.  This entry point
144       reads an id of the new created arena.
145
146       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
150       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
154       By default, the number of arenas is limited to 1024.
155
156       heap.arena.[arena_id].automatic | rw- | - | boolean | boolean | - | -
157
158       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
165       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
169       Describes an allocation class.  Allows one to create or view the inter‐
170       nal data structures of the allocator.
171
172       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
179       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
185       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
189       This entry point takes a complex argument.
190
191              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
199       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
204       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
210       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
221       The header_type field defines the header of objects from the allocation
222       class.  There are three types:
223
224POBJ_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
229POBJ_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
233POBJ_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
239         0) or allocations that span more than one unit.
240
241       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
246       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
250       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
254       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
258       Example of a valid alloc class query string:
259
260              heap.alloc_class.128.desc=500,0,1000,compact
261
262       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
266       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
269       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
272       heap.alloc_class.new.desc | -w | - | - | struct pobj_alloc_class_desc |
273       - | integer, integer, integer, string
274
275       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
279       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
283       The  required  class identifier will be stored in the class_id field of
284       the struct pobj_alloc_class_desc.
285
286       stats.enabled | rw | - | enum pobj_stats_enabled | enum  pobj_stats_en‐
287       abled | - | string
288
289       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
295       Only  transient statistics are enabled by default.  Enabling persistent
296       statistics may have non-trivial performance impact.
297
298       stats.heap.curr_allocated | r- | - | uint64_t | - | - | -
299
300       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
304       This is a persistent statistic.
305
306       stats.heap.run_allocated | r- | - | uint64_t | - | - | -
307
308       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
313       This  is  a  transient  statistic and is rebuilt every time the pool is
314       opened.
315
316       stats.heap.run_active | r- | - | uint64_t | - | - | -
317
318       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
322       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
327       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()(3) if the fragmentation looks
330       to be high.
331
332       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
339       This is a transient statistic and is rebuilt lazily every time the pool
340       is opened.
341
342       heap.size.granularity | rw- | - | uint64_t | uint64_t | - | long long
343
344       Reads or modifies the granularity with which the heap grows  when  OOM.
345       Valid only if the poolset has been defined with directories.
346
347       A granularity of 0 specifies that the pool will not grow automatically.
348
349       This  entry  point  can  fail  if the granularity value is non-zero and
350       smaller than PMEMOBJ_MIN_PART.
351
352       heap.size.extend | –x | - | - | - | uint64_t | -
353
354       Extends the heap by  the  given  size.   Must  be  larger  than  PMEMO‐
355       BJ_MIN_PART.
356
357       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
360       debug.heap.alloc_pattern | rw | - | int | int | - | -
361
362       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

CTL EXTERNAL CONFIGURATION

367       In addition to direct function call, each write entry point can also be
368       set using two alternative methods.
369
370       The  first  method  is to load a configuration directly from the PMEMO‐
371       BJ_CONF environment variable.
372
373       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
377       See more in pmem_ctl(5) man page.
378

SEE ALSO

380       libpmemobj(7), pmem_ctl(5) and <https://pmem.io>
381
382
383
384PMDK - pmemobj API version 2.3    2020-10-28                PMEMOBJ_CTL_GET(3)
Impressum