Provided by: libpmemobj-dev_1.6.1-1ubuntu1_amd64 bug

NAME

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

SYNOPSIS

              #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)

DESCRIPTION

       The  pmemobj_ctl_get(),  pmemobj_ctl_set()  and  pmemobj_ctl_exec()  functions  provide  a
       uniform  interface  for  querying  and  modifying  the  internal behavior of libpmemobj(7)
       through the control (CTL) namespace.

       The name argument specifies an entry point as defined in the CTL namespace  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 indicated otherwise below.  If there are special conditions for calling
       an entry point, they are explicitly stated in its description.   The  functions  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 return 0 on success and
       -1 on failure, unless otherwise specified in the entry point description.

       See more in pmem_ctl(5) man page.

CTL NAMESPACE

       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() function.

       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() function.

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

       If set, force-enables or force-disables SDS feature during pool  creation.   Affects  only
       the  pmemobj_create()  function.  See pmempool_feature_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 supported 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 cost.

       This should be set to roughly the sum of sizes of the snapshotted regions  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 operations 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.

       heap.narenas.total | 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 (allocations, frees, reallocs).

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

       Reads  the  total  amount  of  memory in bytes which is currently exclusively 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 0.

       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_xalloc()/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 automatic arena must exist.

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

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

       Creating  custom  allocation classes can be beneficial for both raw allocation throughput,
       scalability and, most importantly, fragmentation.  By  carefully  constructing  allocation
       classes  that  match  the  application  workload,  one can entirely eliminate external and
       internal fragmentation.  For example, it is  possible  to  easily  construct  a  slab-like
       allocation 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 reading.

       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  PMEMOBJ_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  allocated  using  the
       class.   If  set,  must  be a power of two and an even divisor 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 memory 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 value.

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

       · POBJ_HEADER_LEGACY,  string value: legacy.  Used for allocation classes 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.

       · 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.

       · 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 equivalent to the provided [class_id].  This
       field cannot be set from a config 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 configuration 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 classes and relevant algorithms.

       Allocation classes constructed in this way can be leveraged by explicitly  specifying  the
       class using POBJ_CLASS_ID(id) flag in pmemobj_tx_xalloc()/pmemobj_xalloc() functions.

       Example of a valid alloc class query string:

              heap.alloc_class.128.desc=500,0,1000,compact

       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.

       heap.alloc_class.new.desc | -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 libpmemobj).

       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 disabling 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 statistics 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 PMEMOBJ_MIN_PART.

       This  entry point can fail if the pool does not support extend functionality 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  allocation.   If  the
       value is negative, no pattern is written.  This is intended for debugging, and is disabled
       by default.

CTL EXTERNAL CONFIGURATION

       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 PMEMOBJ_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.

SEE ALSO

       libpmemobj(7), pmem_ctl(5) and <http://pmem.io>