Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
PMEMOBJ_CTL_GET(3)	   PMDK	Programmer's Manual	    PMEMOBJ_CTL_GET(3)

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

	      #include <libpmemobj.h>

	      int pmemobj_ctl_get(PMEMobjpool *pop, const char *name, void *arg); (EXPERIMENTAL)
	      int pmemobj_ctl_set(PMEMobjpool *pop, const char *name, void *arg); (EXPERIMENTAL)
	      int pmemobj_ctl_exec(PMEMobjpool *pop, const char	*name, void *arg); (EXPERIMENTAL)

       The pmemobj_ctl_get(), pmemobj_ctl_set()	and  pmemobj_ctl_exec()	 func-
       tions provide a uniform interface for querying and modifying the	inter-
       nal behavior of libpmemobj(7) through the control (CTL) namespace.

       The name	argument specifies an entry point as defined in	the CTL	 name-
       space specification.  The entry point description specifies whether the
       extra arg is required.  Those two  parameters  together	create	a  CTL
       query.  The functions and the entry points are thread-safe unless indi-
       cated otherwise below.  If there	are special conditions for calling  an
       entry  point, they are explicitly stated	in its description.  The func-
       tions propagate the return value	of the entry point.  If	either name or
       arg is invalid, -1 is returned.

       If  the	provided ctl query is valid, the CTL functions will always re-
       turn 0 on success and -1	on failure, unless otherwise specified in  the
       entry point description.

       See more	in pmem_ctl(5) man page.

       prefault.at_create | rw | global	| int |	int | -	| boolean

       If  set,	every page of the pool will be touched and written to when the
       pool is created,	in order to trigger page allocation and	 minimize  the
       performance  impact  of	pagefaults.  Affects only the pmemobj_create()

       prefault.at_open	| rw | global |	int | int | - |	boolean

       If set, every page of the pool will be touched and written to when  the
       pool  is	 opened,  in order to trigger page allocation and minimize the
       performance impact of  pagefaults.   Affects  only  the	pmemobj_open()

       sds.at_create | rw | global | int | int | - | boolean

       If  set,	 force-enables	or force-disables SDS feature during pool cre-
       ation.  Affects only the	pmemobj_create() function.  See	 pmempool_fea-
       ture_query(3) for informations about SDS	(SHUTDOWN_STATE) feature.

       copy_on_write.at_open | rw | global | int | int | - | boolean

       If set, pool is mapped in such a	way that modifications don't reach the
       underlying medium.  From	the user's perspective this  means  that  when
       the  pool is closed all changes are reverted.  This feature is not sup-
       ported for pools	located	on Device DAX.

       tx.debug.skip_expensive_checks |	rw | - | int | int | - | boolean

       Turns off some expensive	checks performed by the	transaction module  in
       "debug" builds.	Ignored	in "release" builds.

       tx.cache.size | rw | - |	long long | long long |	- | integer

       Size in bytes of	the transaction	snapshot cache.	 In a larger cache the
       frequency of persistent allocations is lower,  but  with	 higher	 fixed

       This  should  be	set to roughly the sum of sizes	of the snapshotted re-
       gions in	an average transaction in the pool.

       This entry point	is not thread safe and should not be modified if there
       are any transactions currently running.

       This  value  must be a in a range between 0 and PMEMOBJ_MAX_ALLOC_SIZE,
       otherwise this entry point will fail.

       tx.cache.threshold | rw | - | long long | long long | - | integer

       This entry point	is deprecated.	All snapshots, regardless of the size,
       use the transactional cache.

       tx.post_commit.queue_depth | rw | - | int | int | - | integer

       This entry point	is deprecated.

       tx.post_commit.worker | r- | - |	void * | - | - | -

       This entry point	is deprecated.

       tx.post_commit.stop | r-	| - | void * | - | - | -

       This entry point	is deprecated.

       heap.narenas.automatic |	r- | - | unsigned | - |	- | -

       Reads the number	of arenas used in automatic scheduling of memory oper-
       ations for threads.  By default,	this value is equal to the  number  of
       available  processors.  An arena	is a memory management structure which
       enables concurrency by taking exclusive ownership of parts of the  heap
       and allowing associated threads to allocate without contention. | r- | - | unsigned |	- | - |	-

       Reads  the  number of all created arenas.  It includes automatic	arenas
       created by default and arenas created using heap.arena.create CTL.

       heap.narenas.max	| rw- |	- | unsigned | unsigned	| - | -

       Reads or	writes the maximum number of arenas that can be	created.  This
       entry point is not thread-safe with regards to heap operations (alloca-
       tions, frees, reallocs).

       heap.arena.[arena_id].size | r- | - | uint64_t |	- | - |	-

       Reads the total amount of memory	in bytes which is currently exclusive-
       ly  owned by the	arena.	Large differences in this value	between	arenas
       might indicate an uneven	scheduling of memory resources.	 The arena  id
       cannot be 0.

       heap.thread.arena_id | rw- | - |	unsigned | unsigned | -	| -

       Reads  the index	of the arena assigned to the current thread or assigns
       arena with specific id to the current thread.  The arena	id  cannot  be

       heap.arena.create | -x |	- | - |	- | unsigned | -

       Creates	and  initializes  one new arena	in the heap.  This entry point
       reads an	id of the new created arena.

       Newly created arenas by this CTL	are inactive,  which  means  that  the
       arena  will not be used in the automatic	scheduling of memory requests.
       To activate the new arena, use heap.arena.[arena_id].automatic CTL.

       Arena created using this	CTL can	be used	for allocation	by  explicitly
       specifying  the	arena_id for POBJ_ARENA_ID(id) flag in pmemobj_tx_xal-
       loc()/pmemobj_xalloc()/pmemobj_xreserve() functions.

       By default, the number of arenas	is limited to 1024.

       heap.arena.[arena_id].automatic | rw- | - | boolean | boolean | - | -

       Reads or	modifies the state of the arena.  If set, the arena is used in
       automatic  scheduling of	memory operations for threads.	This should be
       set to false if the application	wants  to  manually  manage  allocator
       scalability  through  explicitly	 assigning  arenas to threads by using
       heap.thread.arena_id.  The arena	id cannot be 0 and at least one	 auto-
       matic arena must	exist.

       heap.alloc_class.[class_id].desc	| rw | - | struct pobj_alloc_class_de-
       sc | struct pobj_alloc_class_desc |  -  |  integer,  integer,  integer,

       Describes an allocation class.  Allows one to create or view the	inter-
       nal data	structures of the allocator.

       Creating	custom allocation classes can be beneficial for	both raw allo-
       cation  throughput,  scalability	 and, most importantly,	fragmentation.
       By carefully constructing allocation classes that match the application
       workload,  one  can entirely eliminate external and internal fragmenta-
       tion.  For example, it is possible to easily construct a	slab-like  al-
       location	mechanism for any data structure.

       The [class_id] is an index field.  Only values between 0-254 are	valid.
       If setting an allocation	class, but the class_id	is already taken,  the
       function	will return -1.	 The values between 0-127 are reserved for the
       default allocation classes of the library and  can  be  used  only  for

       The  recommended	method for retrieving information about	all allocation
       classes is to call this entry point for all class ids between 0 and 254
       and discard those results for which the function	returns	an error.

       This entry point	takes a	complex	argument.

	      struct pobj_alloc_class_desc {
		  size_t unit_size;
		  size_t alignment;
		  unsigned units_per_block;
		  enum pobj_header_type	header_type;
		  unsigned class_id;

       The  first field, unit_size, is an 8-byte unsigned integer that defines
       the allocation class size.  While theoretically limited only by	PMEMO-
       BJ_MAX_ALLOC_SIZE,  for	most  workloads	this value should be between 8
       bytes and 2 megabytes.

       The alignment field specifies the user data alignment of	objects	 allo-
       cated  using the	class.	If set,	must be	a power	of two and an even di-
       visor of	unit size.  Alignment is limited to maximum  of	 2  megabytes.
       All  objects  have  default  alignment  of  64 bytes, but the user data
       alignment is affected by	the size of the	chosen header.

       The units_per_block field defines how many units	a single block of mem-
       ory  contains.	This value will	be adjusted to match the internal size
       of the block (256 kilobytes or a	multiple thereof).  For	example, given
       a  class	with a unit_size of 512	bytes and a units_per_block of 1000, a
       single block of memory for that class will have 512 kilobytes.  This is
       relevant	 because the bigger the	block size, the	less frequently	blocks
       need to be fetched, resulting in	lower contention on global heap	state.
       If  the CTL call	is being done at runtime, the units_per_block variable
       of the provided alloc class structure is	modified to match  the	actual

       The header_type field defines the header	of objects from	the allocation
       class.  There are three types:

       o POBJ_HEADER_LEGACY, string value: legacy.  Used for allocation	class-
	 es  prior  to	version	 1.3 of	the library.  Not recommended for use.
	 Incurs	a 64 byte metadata overhead for	every object.  Fully  supports
	 all features.

       o POBJ_HEADER_COMPACT,  string value: compact.  Used as default for all
	 predefined allocation classes.	 Incurs	a 16  byte  metadata  overhead
	 for every object.  Fully supports all features.

       o POBJ_HEADER_NONE,  string  value:  none.   Header type	that incurs no
	 metadata overhead beyond a single bitmap entry.  Can be used for very
	 small	allocation  classes  or	 when objects must be adjacent to each
	 other.	 This header type does not support type	numbers	 (type	number
	 is always

	 0) or allocations that	span more than one unit.

       The  class_id  field  is	an optional, runtime-only variable that	allows
       the user	to retrieve the	identifier of the class.  This will be equiva-
       lent  to	the provided [class_id].  This field cannot be set from	a con-
       fig file.

       The allocation classes are a runtime state of the library and  must  be
       created after every open.  It is	highly recommended to use the configu-
       ration file to store the	classes.

       This structure is declared in the libpmemobj/ctl.h header file.	Please
       refer to	this file for an in-depth explanation of the allocation	class-
       es and relevant algorithms.

       Allocation classes constructed in this way can be leveraged by  explic-
       itly  specifying	 the  class  using  POBJ_CLASS_ID(id)  flag  in	pmemo-
       bj_tx_xalloc()/pmemobj_xalloc() functions.

       Example of a valid alloc	class query string:


       This query, if executed,	will create an allocation class	with an	id  of
       128  that  has  a  unit	size of	500 bytes, has at least	1000 units per
       block and uses a	compact	header.

       For reading, function returns 0 if successful, if the allocation	 class
       does not	exist it sets the errno	to ENOENT and returns -1;

       This  entry  point  can fail if any of the parameters of	the allocation
       class is	invalid	or if exactly the same class already exists. | -w |	- | - |	struct pobj_alloc_class_desc |
       - | integer, integer, integer, string

       Same  as	heap.alloc_class.[class_id].desc, but instead of requiring the
       user to provide the class_id, it	automatically creates  the  allocation
       class with the first available identifier.

       This should be used when	it's impossible	to guarantee unique allocation
       class naming in the application (e.g. when writing a library that  uses

       The  required  class identifier will be stored in the class_id field of
       the struct pobj_alloc_class_desc.

       stats.enabled | rw | - |	int | int | - |	boolean

       Enables or disables runtime collection of statistics.   Statistics  are
       not recalculated	after enabling;	any operations that occur between dis-
       abling and re-enabling will not be reflected in subsequent values.

       Statistics are disabled by default.  Enabling them may have non-trivial
       performance impact.

       stats.heap.curr_allocated | r- |	- | int	| - | -	| -

       Reads  the number of bytes currently allocated in the heap.  If statis-
       tics were disabled at any time in the lifetime of the heap, this	 value
       may be inaccurate.

       heap.size.granularity | rw- | - | uint64_t | uint64_t | - | long	long

       Reads  or  modifies the granularity with	which the heap grows when OOM.
       Valid only if the poolset has been defined with directories.

       A granularity of	0 specifies that the pool will not grow	automatically.

       This entry point	can fail if the	 granularity  value  is	 non-zero  and
       smaller than PMEMOBJ_MIN_PART.

       heap.size.extend	| -x | - | - | - | uint64_t | -

       Extends	the  heap  by  the  given  size.   Must	 be larger than	PMEMO-

       This entry point	can fail if the	pool does not support extend function-
       ality or	if there's not enough space left on the	device.

       debug.heap.alloc_pattern	| rw | - | int | int | - | -

       Single byte pattern that	is used	to fill	new uninitialized memory allo-
       cation.	If the value is	negative, no pattern is	written.  This is  in-
       tended for debugging, and is disabled by	default.

       In addition to direct function call, each write entry point can also be
       set using two alternative methods.

       The first method	is to load a configuration directly  from  the	PMEMO-
       BJ_CONF environment variable.

       The  second  method  of loading an external configuration is to set the
       PMEMOBJ_CONF_FILE environment variable to point to a file that contains
       a sequence of ctl queries.

       See more	in pmem_ctl(5) man page.

       libpmemobj(7), pmem_ctl(5) and <>

PMDK - pmemobj API version 2.3	  2019-07-10		    PMEMOBJ_CTL_GET(3)


Want to link to this manual page? Use this URL:

home | help