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 See more in pmem_ctl(5) man page.
22
24 prefault.at_create | rw | global | int | int | - | boolean
25 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 Always returns 0.
32 prefault.at_open | rw | global | int | int | - | boolean
34 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 Always returns 0.
41 sds.at_create | rw | global | int | int | - | boolean
43 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 Always returns 0.
49 tx.debug.skip_expensive_checks | rw | - | int | int | - | boolean
51 Turns off some expensive checks performed by the transaction module in
53 “debug” builds. Ignored in “release” builds.
54 tx.cache.size | rw | - | long long | long long | - | integer
56 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 This should be set to roughly the sum of sizes of the snapshotted re‐
62 gions in an average transaction in the pool.
63 This value must be a in a range between 0 and PMEMOBJ_MAX_ALLOC_SIZE.
65 This entry point is not thread safe and should not be modified if there
67 are any transactions currently running.
68 Returns 0 if successful, -1 otherwise.
70 tx.cache.threshold | rw | - | long long | long long | - | integer
72 This entry point is deprecated. All snapshots, regardless of the size,
74 use the transactional cache.
75 Returns 0 if successful, -1 otherwise.
77 tx.post_commit.queue_depth | rw | - | int | int | - | integer
79 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 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 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 The queue depth value must also be a power of two.
101 This entry point is not thread-safe and must be called when no transac‐
103 tions are currently being executed.
104 Returns 0 if successful, -1 otherwise.
106 tx.post_commit.worker | r- | - | void * | - | - | -
108 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 Always returns 0.
115 tx.post_commit.stop | r- | - | void * | - | - | -
117 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 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 This entry point must be called when no transactions are currently be‐
128 ing executed.
129 Always returns 0.
131 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 Describes an allocation class. Allows one to create or view the inter‐
137 nal data structures of the allocator.
138 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 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 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 This entry point takes a complex argument.
157 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 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 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 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 The header_type field defines the header of objects from the allocation
189 class. There are three types:
190 · 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 · 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 · 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 0) or allocations that span more than one unit.
207 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 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 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 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 Example of a valid alloc class query string:
226 heap.alloc_class.128.desc=500,0,1000,compact
228 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 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 For writing, function returns 0 if the allocation class has been suc‐
237 cessfully created, -1 otherwise.
238 heap.alloc_class.new.desc | -w | - | - | struct pobj_alloc_class_desc |
240 - | integer, integer, integer, string
241 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 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 The required class identifier will be stored in the class_id field of
251 the struct pobj_alloc_class_desc.
252 This function returns 0 if the allocation class has been successfully
254 created, -1 otherwise.
255 stats.enabled | rw | - | int | int | - | boolean
257 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 Statistics are disabled by default. Enabling them may have non-trivial
263 performance impact.
264 Always returns 0.
266 stats.heap.curr_allocated | r- | - | int | - | - | -
268 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 heap.size.granularity | rw- | - | uint64_t | uint64_t | - | long long
274 Reads or modifies the granularity with which the heap grows when OOM.
276 Valid only if the poolset has been defined with directories.
277 A granularity of 0 specifies that the pool will not grow automatically.
279 This function returns 0 if the granularity value is 0, or is larger
281 than PMEMOBJ_MIN_PART, -1 otherwise.
282 heap.size.extend | –x | - | - | - | uint64_t | -
284 Extends the heap by the given size. Must be larger than PMEMO‐
286 BJ_MIN_PART.
287 This function returns 0 if successful, -1 otherwise.
289 debug.heap.alloc_pattern | rw | - | int | int | - | -
291 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
297 In addition to direct function call, each write entry point can also be
298 set using two alternative methods.
299 The first method is to load a configuration directly from the PMEMO‐
301 BJ_CONF environment variable.
302 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 See more in pmem_ctl(5) man page.
308
310 libpmemobj(7), pmem_ctl(5) and <http://pmem.io>
311PMDK - pmemobj API version 2.3 2018-10-23 PMEMOBJ_CTL_GET(3)