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       See more in pmem_ctl(5) man page.
22

CTL NAMESPACE

24       prefault.at_create | rw | global | int | int | - | boolean
25
26       If set, every page of the pool will be touched and written to when  the
27       pool  is  created, in order to trigger page allocation and minimize the
28       performance impact of pagefaults.  Affects  only  the  pmemobj_create()
29       function.
30
31       Always returns 0.
32
33       prefault.at_open | rw | global | int | int | - | boolean
34
35       If  set, every page of the pool will be touched and written to when the
36       pool is opened, in order to trigger page allocation  and  minimize  the
37       performance  impact  of  pagefaults.   Affects  only the pmemobj_open()
38       function.
39
40       Always returns 0.
41
42       sds.at_create | rw | global | int | int | - | boolean
43
44       If set, force-enables or force-disables SDS feature  during  pool  cre‐
45       ation.   Affects only the pmemobj_create() function.  See pmempool_fea‐
46       ture_query(3) for informations about SDS (SHUTDOWN_STATE) feature.
47
48       Always returns 0.
49
50       tx.debug.skip_expensive_checks | rw | - | int | int | - | boolean
51
52       Turns off some expensive checks performed by the transaction module  in
53       “debug” builds.  Ignored in “release” builds.
54
55       tx.cache.size | rw | - | long long | long long | - | integer
56
57       Size in bytes of the transaction snapshot cache.  In a larger cache the
58       frequency of persistent allocations is lower,  but  with  higher  fixed
59       cost.
60
61       This  should  be set to roughly the sum of sizes of the snapshotted re‐
62       gions in an average transaction in the pool.
63
64       This value must be a in a range between 0 and PMEMOBJ_MAX_ALLOC_SIZE.
65
66       This entry point is not thread safe and should not be modified if there
67       are any transactions currently running.
68
69       Returns 0 if successful, -1 otherwise.
70
71       tx.cache.threshold | rw | - | long long | long long | - | integer
72
73       This entry point is deprecated.  All snapshots, regardless of the size,
74       use the transactional cache.
75
76       Returns 0 if successful, -1 otherwise.
77
78       tx.post_commit.queue_depth | rw | - | int | int | - | integer
79
80       Controls the depth of the post-commit tasks queue.  A post-commit  task
81       is  the  collection of work items that need to be performed on the per‐
82       sistent state after a successfully  completed  transaction.   This  in‐
83       cludes freeing no longer needed objects and cleaning up various caches.
84       By default, this queue does not exist and the post-commit task is  exe‐
85       cuted  synchronously  in  the same thread that ran the transaction.  By
86       changing this parameter, one can offload this task to a separate  work‐
87       er.   If the queue is full, the algorithm, instead of waiting, performs
88       the post-commit in the current thread.
89
90       The task is performed on a finite resource (lanes, of which  there  are
91       1024),  and if the worker threads that process this queue are unable to
92       keep up with the demand, regular threads might start to  block  waiting
93       for  that  resource.   This will happen if the queue depth value is too
94       large.
95
96       As a general rule, this value should be set to approximately 1024 minus
97       the  average  number  of  threads  in the application (not counting the
98       post-commit workers); however, this may vary from workload to workload.
99
100       The queue depth value must also be a power of two.
101
102       This entry point is not thread-safe and must be called when no transac‐
103       tions are currently being executed.
104
105       Returns 0 if successful, -1 otherwise.
106
107       tx.post_commit.worker | r- | - | void * | - | - | -
108
109       The  worker  function launched in a thread to perform asynchronous pro‐
110       cessing of post-commit tasks.  This function returns only after a  stop
111       entry point is called.  There may be many worker threads at a time.  If
112       there is no work to be done, this function sleeps instead of polling.
113
114       Always returns 0.
115
116       tx.post_commit.stop | r- | - | void * | - | - | -
117
118       This function forces all the post-commit worker functions to  exit  and
119       return  control  back to the calling thread.  This should be called be‐
120       fore the application terminates and the post commit worker threads need
121       to be shutdown.
122
123       After  the  invocation  of this entry point, the post-commit task queue
124       can no longer be used.  If worker threads must  be  restarted  after  a
125       stop, the tx.post_commit.queue_depth needs to be set again.
126
127       This  entry point must be called when no transactions are currently be‐
128       ing executed.
129
130       Always returns 0.
131
132       heap.alloc_class.[class_id].desc | rw | - | struct pobj_alloc_class_de‐
133       sc  |  struct pobj_alloc_class_desc  |  -  | integer, integer, integer,
134       string
135
136       Describes an allocation class.  Allows one to create or view the inter‐
137       nal data structures of the allocator.
138
139       Creating custom allocation classes can be beneficial for both raw allo‐
140       cation throughput, scalability and,  most  importantly,  fragmentation.
141       By carefully constructing allocation classes that match the application
142       workload, one can entirely eliminate external and  internal  fragmenta‐
143       tion.   For example, it is possible to easily construct a slab-like al‐
144       location mechanism for any data structure.
145
146       The [class_id] is an index field.  Only values between 0-254 are valid.
147       If  setting an allocation class, but the class_id is already taken, the
148       function will return -1.  The values between 0-127 are reserved for the
149       default  allocation  classes  of  the  library and can be used only for
150       reading.
151
152       The recommended method for retrieving information about all  allocation
153       classes is to call this entry point for all class ids between 0 and 254
154       and discard those results for which the function returns an error.
155
156       This entry point takes a complex argument.
157
158              struct pobj_alloc_class_desc {
159                  size_t unit_size;
160                  size_t alignment;
161                  unsigned units_per_block;
162                  enum pobj_header_type header_type;
163                  unsigned class_id;
164              };
165
166       The first field, unit_size, is an 8-byte unsigned integer that  defines
167       the  allocation class size.  While theoretically limited only by PMEMO‐
168       BJ_MAX_ALLOC_SIZE, for most workloads this value should  be  between  8
169       bytes and 2 megabytes.
170
171       The  alignment field specifies the user data alignment of objects allo‐
172       cated using the class.  If set, must be a power of two and an even  di‐
173       visor  of  unit  size.  Alignment is limited to maximum of 2 megabytes.
174       All objects have default alignment of  64  bytes,  but  the  user  data
175       alignment is affected by the size of the chosen header.
176
177       The units_per_block field defines how many units a single block of mem‐
178       ory contains.  This value will be adjusted to match the  internal  size
179       of the block (256 kilobytes or a multiple thereof).  For example, given
180       a class with a unit_size of 512 bytes and a units_per_block of 1000,  a
181       single block of memory for that class will have 512 kilobytes.  This is
182       relevant because the bigger the block size, the less frequently  blocks
183       need to be fetched, resulting in lower contention on global heap state.
184       If the CTL call is being done at runtime, the units_per_block  variable
185       of  the  provided alloc class structure is modified to match the actual
186       value.
187
188       The header_type field defines the header of objects from the allocation
189       class.  There are three types:
190
191       · POBJ_HEADER_LEGACY, string value: legacy.  Used for allocation class‐
192         es prior to version 1.3 of the library.   Not  recommended  for  use.
193         Incurs  a 64 byte metadata overhead for every object.  Fully supports
194         all features.
195
196       · POBJ_HEADER_COMPACT, string value: compact.  Used as default for  all
197         predefined  allocation  classes.   Incurs a 16 byte metadata overhead
198         for every object.  Fully supports all features.
199
200       · POBJ_HEADER_NONE, string value: none.  Header  type  that  incurs  no
201         metadata overhead beyond a single bitmap entry.  Can be used for very
202         small allocation classes or when objects must  be  adjacent  to  each
203         other.   This  header type does not support type numbers (type number
204         is always
205
206         0) or allocations that span more than one unit.
207
208       The class_id field is an optional, runtime-only  variable  that  allows
209       the user to retrieve the identifier of the class.  This will be equiva‐
210       lent to the provided [class_id].  This field cannot be set from a  con‐
211       fig file.
212
213       The  allocation  classes are a runtime state of the library and must be
214       created after every open.  It is highly recommended to use the configu‐
215       ration file to store the classes.
216
217       This structure is declared in the libpmemobj/ctl.h header file.  Please
218       refer to this file for an in-depth explanation of the allocation class‐
219       es and relevant algorithms.
220
221       Allocation  classes constructed in this way can be leveraged by explic‐
222       itly specifying  the  class  using  POBJ_CLASS_ID(id)  flag  in  pmemo‐
223       bj_tx_xalloc()/pmemobj_xalloc() functions.
224
225       Example of a valid alloc class query string:
226
227              heap.alloc_class.128.desc=500,0,1000,compact
228
229       This  query, if executed, will create an allocation class with an id of
230       128 that has a unit size of 500 bytes, has  at  least  1000  units  per
231       block and uses a compact header.
232
233       For  reading, function returns 0 if successful, if the allocation class
234       does not exist it sets the errno to ENOENT and returns -1;
235
236       For writing, function returns 0 if the allocation class has  been  suc‐
237       cessfully created, -1 otherwise.
238
239       heap.alloc_class.new.desc | -w | - | - | struct pobj_alloc_class_desc |
240       - | integer, integer, integer, string
241
242       Same as heap.alloc_class.[class_id].desc, but instead of requiring  the
243       user  to  provide the class_id, it automatically creates the allocation
244       class with the first available identifier.
245
246       This should be used when it's impossible to guarantee unique allocation
247       class  naming in the application (e.g. when writing a library that uses
248       libpmemobj).
249
250       The required class identifier will be stored in the class_id  field  of
251       the struct pobj_alloc_class_desc.
252
253       This  function  returns 0 if the allocation class has been successfully
254       created, -1 otherwise.
255
256       stats.enabled | rw | - | int | int | - | boolean
257
258       Enables or disables runtime collection of statistics.   Statistics  are
259       not recalculated after enabling; any operations that occur between dis‐
260       abling and re-enabling will not be reflected in subsequent values.
261
262       Statistics are disabled by default.  Enabling them may have non-trivial
263       performance impact.
264
265       Always returns 0.
266
267       stats.heap.curr_allocated | r- | - | int | - | - | -
268
269       Returns  the  number of bytes currently allocated in the heap.  If sta‐
270       tistics were disabled at any time in the lifetime  of  the  heap,  this
271       value may be inaccurate.
272
273       heap.size.granularity | rw- | - | uint64_t | uint64_t | - | long long
274
275       Reads  or  modifies the granularity with which the heap grows when OOM.
276       Valid only if the poolset has been defined with directories.
277
278       A granularity of 0 specifies that the pool will not grow automatically.
279
280       This function returns 0 if the granularity value is  0,  or  is  larger
281       than PMEMOBJ_MIN_PART, -1 otherwise.
282
283       heap.size.extend | –x | - | - | - | uint64_t | -
284
285       Extends  the  heap  by  the  given  size.   Must  be larger than PMEMO‐
286       BJ_MIN_PART.
287
288       This function returns 0 if successful, -1 otherwise.
289
290       debug.heap.alloc_pattern | rw | - | int | int | - | -
291
292       Single byte pattern that is used to fill new uninitialized memory allo‐
293       cation.   If the value is negative, no pattern is written.  This is in‐
294       tended for debugging, and is disabled by default.
295

CTL EXTERNAL CONFIGURATION

297       In addition to direct function call, each write entry point can also be
298       set using two alternative methods.
299
300       The  first  method  is to load a configuration directly from the PMEMO‐
301       BJ_CONF environment variable.
302
303       The second method of loading an external configuration is  to  set  the
304       PMEMOBJ_CONF_FILE environment variable to point to a file that contains
305       a sequence of ctl queries.
306
307       See more in pmem_ctl(5) man page.
308

SEE ALSO

310       libpmemobj(7), pmem_ctl(5) and <http://pmem.io>
311
312
313
314PMDK - pmemobj API version 2.3    2018-10-23                PMEMOBJ_CTL_GET(3)
Impressum