From 5053859e1f544496a5be3897c0f2114922213855 Mon Sep 17 00:00:00 2001 From: Generic builder Date: Tue, 25 Jul 2017 15:17:04 -0700 Subject: [PATCH] doc: automatic docs update --- doc/generated/libpmem.3 | 2 +- doc/generated/libpmemblk.3 | 2 +- doc/generated/libpmemlog.3 | 2 +- doc/generated/libpmemobj.3 | 165 ++++++++++++++++++++++++++++- doc/generated/libpmempool.3 | 2 +- doc/generated/librpmem.3 | 2 +- doc/generated/libvmem.3 | 2 +- doc/generated/libvmmalloc.3 | 2 +- doc/generated/pmempool-check.1 | 2 +- doc/generated/pmempool-convert.1 | 2 +- doc/generated/pmempool-create.1 | 2 +- doc/generated/pmempool-dump.1 | 2 +- doc/generated/pmempool-info.1 | 2 +- doc/generated/pmempool-rm.1 | 2 +- doc/generated/pmempool-sync.1 | 2 +- doc/generated/pmempool-transform.1 | 2 +- doc/generated/pmempool.1 | 2 +- doc/generated/rpmemd.1 | 2 +- 18 files changed, 181 insertions(+), 18 deletions(-) diff --git a/doc/generated/libpmem.3 b/doc/generated/libpmem.3 index 88b5d64b434..0f189200931 100644 --- a/doc/generated/libpmem.3 +++ b/doc/generated/libpmem.3 @@ -1,6 +1,6 @@ .\" Automatically generated by Pandoc 1.16.0.2 .\" -.TH "LIBPMEM" "3" "2017-07-21" "NVM Library - pmem API version 1.0" "NVML Programmer's Manual" +.TH "LIBPMEM" "3" "2017-07-25" "NVM Library - pmem API version 1.0" "NVML Programmer's Manual" .hy .\" Copyright 2014-2017, Intel Corporation .\" diff --git a/doc/generated/libpmemblk.3 b/doc/generated/libpmemblk.3 index 08c31a0c825..bd8abf3519a 100644 --- a/doc/generated/libpmemblk.3 +++ b/doc/generated/libpmemblk.3 @@ -1,6 +1,6 @@ .\" Automatically generated by Pandoc 1.16.0.2 .\" -.TH "LIBPMEMBLK" "3" "2017-07-21" "NVM Library - pmemblk API version 1.0" "NVML Programmer's Manual" +.TH "LIBPMEMBLK" "3" "2017-07-25" "NVM Library - pmemblk API version 1.0" "NVML Programmer's Manual" .hy .\" Copyright 2014-2017, Intel Corporation .\" diff --git a/doc/generated/libpmemlog.3 b/doc/generated/libpmemlog.3 index 43840502b43..c94e32946ff 100644 --- a/doc/generated/libpmemlog.3 +++ b/doc/generated/libpmemlog.3 @@ -1,6 +1,6 @@ .\" Automatically generated by Pandoc 1.16.0.2 .\" -.TH "LIBPMEMLOG" "3" "2017-07-21" "NVM Library - pmemlog API version 1.0" "NVML Programmer's Manual" +.TH "LIBPMEMLOG" "3" "2017-07-25" "NVM Library - pmemlog API version 1.0" "NVML Programmer's Manual" .hy .\" Copyright 2014-2017, Intel Corporation .\" diff --git a/doc/generated/libpmemobj.3 b/doc/generated/libpmemobj.3 index af3afd09268..0eb1dfc23d7 100644 --- a/doc/generated/libpmemobj.3 +++ b/doc/generated/libpmemobj.3 @@ -1,6 +1,6 @@ .\" Automatically generated by Pandoc 1.16.0.2 .\" -.TH "LIBPMEMOBJ" "3" "2017-07-21" "NVM Library - pmemobj API version 2.2" "NVML Programmer's Manual" +.TH "LIBPMEMOBJ" "3" "2017-07-25" "NVM Library - pmemobj API version 2.2" "NVML Programmer's Manual" .hy .\" Copyright 2014-2017, Intel Corporation .\" @@ -150,6 +150,8 @@ typedef\ int\ (*pmemobj_constr)(PMEMobjpool\ *pop,\ void\ *ptr,\ void\ *arg); int\ pmemobj_alloc(PMEMobjpool\ *pop,\ PMEMoid\ *oidp,\ size_t\ size,\ uint64_t\ type_num, \ \ \ \ pmemobj_constr\ constructor,\ void\ *arg); int\ pmemobj_zalloc(PMEMobjpool\ *pop,\ PMEMoid\ *oidp,\ size_t\ size,\ uint64_t\ type_num); +int\ pmemobj_xalloc(PMEMobjpool\ *pop,\ PMEMoid\ *oidp,\ size_t\ size,\ uint64_t\ type_num, +\ \ \ \ uint64_t\ flags,\ pmemobj_constr\ constructor,\ void\ *arg); int\ pmemobj_realloc(PMEMobjpool\ *pop,\ PMEMoid\ *oidp,\ size_t\ size,\ uint64_t\ type_num); int\ pmemobj_zrealloc(PMEMobjpool\ *pop,\ PMEMoid\ *oidp,\ size_t\ size,\ uint64_t\ type_num); int\ pmemobj_strdup(PMEMobjpool\ *pop,\ PMEMoid\ *oidp,\ const\ char\ *s,\ uint64_t\ type_num); @@ -1674,6 +1676,27 @@ given \f[I]type_num\f[]. .IP .nf \f[C] +int\ pmemobj_xalloc(PMEMobjpool\ *pop,\ PMEMoid\ *oidp, +\ \ \ \ size_t\ size,\ uint64_t\ type_num,\ uint64_t\ flags, +\ \ \ \ pmemobj_constr\ constructor\ ,\ void\ *arg); +\f[] +.fi +.PP +The \f[B]pmemobj_xalloc\f[]() function allocates a new object from the +persistent memory heap associated with memory pool \f[I]pop\f[]. +Equivalent to \f[B]pmemobj_alloc\f[]() but with the addition of +allocation modifiers. +.PP +The \f[I]flags\f[] argument is a bitmask of the following values: +.IP \[bu] 2 +\f[B]POBJ_XALLOC_ZERO\f[] \- zero the object (equivalent of +\f[B]pmemobj_zalloc\f[]()) +.IP \[bu] 2 +\f[B]POBJ_CLASS_ID(class_id)\f[] \- allocate the object from the +allocation class with id equal to \f[I]class_id\f[] +.IP +.nf +\f[C] void\ pmemobj_free(PMEMoid\ *oidp); \f[] .fi @@ -2796,6 +2819,9 @@ pmemobj_tx_zalloc) .IP \[bu] 2 \f[B]POBJ_XALLOC_NO_FLUSH\f[] \- skip flush on commit (when application deals with flushing or uses pmemobj_memcpy_persist) +.IP \[bu] 2 +\f[B]POBJ_CLASS_ID(class_id)\f[] \- allocate the object from the +allocation class with id equal to \f[I]class_id\f[] .PP If successful, returns a handle to the newly allocated object. Otherwise, stage changes to \f[B]TX_STAGE_ONABORT\f[], \f[B]OID_NULL\f[] @@ -3692,6 +3718,143 @@ This entry point must be called when no transactions are currently being executed. .PP Always returns 0. +.PP +heap.alloc_class.[class_id].desc | rw | \- | +\f[C]struct\ pobj_alloc_class_desc\f[] | +\f[C]struct\ pobj_alloc_class_desc\f[] | integer, integer, string +.PP +A description of an allocation class. +Allows one to create or view the internal data structures of the +allocator. +.PP +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. +.PP +The \f[C][class_id]\f[] is an index field. +Only values between 0\-254 are valid. +If setting an allocation class, but the \f[C]class_id\f[] 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. +.PP +If one wants to retrieve information about all allocation classes, the +recommended method is to simply call this entry point for all class ids +between 0 and 254 and discard those results for which the function +returned an error. +.PP +This entry point takes a complex argument. +.IP +.nf +\f[C] +struct\ pobj_alloc_class_desc\ { +\ \ \ \ size_t\ unit_size; +\ \ \ \ unsigned\ units_per_block; +\ \ \ \ enum\ pobj_header_type\ header_type; +\ \ \ \ unsigned\ class_id; +}; +\f[] +.fi +.PP +The first field \f[C]unit_size\f[], is an 8\-byte unsigned integer that +defines the allocation class size. +While theoretically limited only by \f[B]PMEMOBJ_MAX_ALLOC_SIZE\f[], +this value should be between 8 bytes and a couple of megabytes for most +of the workloads. +.PP +The field \f[C]units_per_block\f[] defines how many units does a single +block of memory contains. +This value will be rounded up to match internal size of the block (256 +kilobytes or a multiple thereof). +For example, given a class with \f[C]unit_size\f[] of 512 bytes and +\f[C]units_per_block\f[] equal 1000, a single block of memory for that +class will have 512 kilobytes. +This is relevant because the bigger the block size, the blocks need to +be fetched less frequently which leads to a lower contention on global +state of the heap. +Keep in mind that the information whether an object is allocated or not +is stored in a bitmap with limited number of entries, this makes it +inefficient to create allocation classes smaller than 128 bytes. +.PP +The field \f[C]header_type\f[] defines the header of objects from the +allocation class. +There are three types: +.IP \[bu] 2 +\f[B]POBJ_HEADER_LEGACY\f[], string value: \f[C]legacy\f[]. +Used for allocation classes prior to 1.3 version of the library. +Not recommended for use. +Incurs 64 byte metadata overhead for every object. +Fully supports all features. +.IP \[bu] 2 +\f[B]POBJ_HEADER_COMPACT\f[], string value: \f[C]compact\f[]. +Used as default for all predefined allocation classes. +Incurs 16 bytes metadata overhead for every object. +Fully supports all features. +.IP \[bu] 2 +\f[B]POBJ_HEADER_NONE\f[], string value: \f[C]none\f[]. +Header type that doesn\[aq]t incur any 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 (it\[aq]s always 0) and +allocations that span more than one unit. +.PP +The field \f[C]class_id\f[] is optional, runtime only (can\[aq]t be set +from config file), variable that allows the user to retrieve the +identifier of the class. +This will be equivalent to the provided \f[C][class_id]\f[]. +.PP +The allocation classes are a runtime state of the library and must be +created after every open. +It\[aq]s highly recommended to use the configuration file to store the +classes. +.PP +This structure is declared in the \f[C]libpmemobj/ctl.h\f[] header file, +please read it for an in\-depth explanation of the allocation classes +and relevant algorithms. +.PP +Allocation classes constructed in this way can be leveraged by +explicitly specifying the class using \f[B]POBJ_CLASS_ID(id)\f[] flag in +\f[B]pmemobj_tx_xalloc\f[]()/\f[B]pmemobj_xalloc\f[]() functions. +.PP +Example of a valid alloc class query string: +.IP +.nf +\f[C] +heap.alloc_class.128.desc=500,1000,compact +\f[] +.fi +.PP +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. +.PP +For reading, function returns 0 if successful, if the allocation class +does not exist it sets the errno to \f[B]ENOENT\f[] and returns \-1; +.PP +For writing, function returns 0 if the allocation class has been +successfully created, \-1 otherwise. +.PP +heap.alloc_class.new.desc | wo | \- | \- | +\f[C]struct\ pobj_alloc_class_desc\f[] | integer, integer, string +.PP +Same as \f[C]heap.alloc_class.[class_id].desc\f[], but instead of +requiring the user to provide the class_id, it automatically creates the +allocation class with the first available identifier. +.PP +This should be used when it\[aq]s impossible to guarantee unique +allocation class naming in the application (e.g. +when writing a library that uses libpmemobj). +.PP +The required class identifier will be stored in the \f[C]class_id\f[] +field of the \f[C]struct\ pobj_alloc_class_desc\f[]. +.PP +This function returns 0 if the allocation class has been successfully +created, \-1 otherwise. .SH CTL external configuration .PP In addition to direct function call, each write entry point can also be diff --git a/doc/generated/libpmempool.3 b/doc/generated/libpmempool.3 index bdcd8c96f07..e64fd51767c 100644 --- a/doc/generated/libpmempool.3 +++ b/doc/generated/libpmempool.3 @@ -1,6 +1,6 @@ .\" Automatically generated by Pandoc 1.16.0.2 .\" -.TH "LIBPMEMPOOL" "3" "2017-07-21" "NVM Library - pmempool API version 1.1" "NVML Programmer's Manual" +.TH "LIBPMEMPOOL" "3" "2017-07-25" "NVM Library - pmempool API version 1.1" "NVML Programmer's Manual" .hy .\" Copyright 2014-2017, Intel Corporation .\" diff --git a/doc/generated/librpmem.3 b/doc/generated/librpmem.3 index 52f0bd76736..5a35aeb756f 100644 --- a/doc/generated/librpmem.3 +++ b/doc/generated/librpmem.3 @@ -1,6 +1,6 @@ .\" Automatically generated by Pandoc 1.16.0.2 .\" -.TH "LIBRPMEM" "3" "2017-07-21" "NVM Library - rpmem API version 1.1" "NVML Programmer's Manual" +.TH "LIBRPMEM" "3" "2017-07-25" "NVM Library - rpmem API version 1.1" "NVML Programmer's Manual" .hy .\" Copyright 2014-2017, Intel Corporation .\" diff --git a/doc/generated/libvmem.3 b/doc/generated/libvmem.3 index 5013ab64eae..26ffa45aa0a 100644 --- a/doc/generated/libvmem.3 +++ b/doc/generated/libvmem.3 @@ -1,6 +1,6 @@ .\" Automatically generated by Pandoc 1.16.0.2 .\" -.TH "LIBVMEM" "3" "2017-07-21" "NVM Library - vmem API version 1.1" "NVML Programmer's Manual" +.TH "LIBVMEM" "3" "2017-07-25" "NVM Library - vmem API version 1.1" "NVML Programmer's Manual" .hy .\" Copyright 2014-2017, Intel Corporation .\" diff --git a/doc/generated/libvmmalloc.3 b/doc/generated/libvmmalloc.3 index d2e9735dcd0..5a538ff80b1 100644 --- a/doc/generated/libvmmalloc.3 +++ b/doc/generated/libvmmalloc.3 @@ -1,6 +1,6 @@ .\" Automatically generated by Pandoc 1.16.0.2 .\" -.TH "LIBVMMALLOC" "3" "2017-07-21" "NVM Library - vmmalloc API version 1.0" "NVML Programmer's Manual" +.TH "LIBVMMALLOC" "3" "2017-07-25" "NVM Library - vmmalloc API version 1.0" "NVML Programmer's Manual" .hy .\" Copyright 2014-2017, Intel Corporation .\" diff --git a/doc/generated/pmempool-check.1 b/doc/generated/pmempool-check.1 index fc0b6cdc81d..f0a666e029f 100644 --- a/doc/generated/pmempool-check.1 +++ b/doc/generated/pmempool-check.1 @@ -1,6 +1,6 @@ .\" Automatically generated by Pandoc 1.16.0.2 .\" -.TH "PMEMPOOL-CHECK" "1" "2017-07-21" "NVM Library - pmem Tools version 1.3" "NVML Programmer's Manual" +.TH "PMEMPOOL-CHECK" "1" "2017-07-25" "NVM Library - pmem Tools version 1.3" "NVML Programmer's Manual" .hy .\" Copyright 2014-2017, Intel Corporation .\" diff --git a/doc/generated/pmempool-convert.1 b/doc/generated/pmempool-convert.1 index eb75819cbb7..7f5fc7e3712 100644 --- a/doc/generated/pmempool-convert.1 +++ b/doc/generated/pmempool-convert.1 @@ -1,6 +1,6 @@ .\" Automatically generated by Pandoc 1.16.0.2 .\" -.TH "PMEMPOOL-CONVERT" "1" "2017-07-21" "NVM Library - pmem Tools version 1.3" "NVML Programmer's Manual" +.TH "PMEMPOOL-CONVERT" "1" "2017-07-25" "NVM Library - pmem Tools version 1.3" "NVML Programmer's Manual" .hy .\" Copyright 2014-2017, Intel Corporation .\" diff --git a/doc/generated/pmempool-create.1 b/doc/generated/pmempool-create.1 index 19199190b02..4448c27dd8e 100644 --- a/doc/generated/pmempool-create.1 +++ b/doc/generated/pmempool-create.1 @@ -1,6 +1,6 @@ .\" Automatically generated by Pandoc 1.16.0.2 .\" -.TH "PMEMPOOL-CREATE" "1" "2017-07-21" "NVM Library - pmem Tools version 1.3" "NVML Programmer's Manual" +.TH "PMEMPOOL-CREATE" "1" "2017-07-25" "NVM Library - pmem Tools version 1.3" "NVML Programmer's Manual" .hy .\" Copyright 2014-2017, Intel Corporation .\" diff --git a/doc/generated/pmempool-dump.1 b/doc/generated/pmempool-dump.1 index 760efebc994..384913248cc 100644 --- a/doc/generated/pmempool-dump.1 +++ b/doc/generated/pmempool-dump.1 @@ -1,6 +1,6 @@ .\" Automatically generated by Pandoc 1.16.0.2 .\" -.TH "PMEMPOOL-DUMP" "1" "2017-07-21" "NVM Library - pmem Tools version 1.3" "NVML Programmer's Manual" +.TH "PMEMPOOL-DUMP" "1" "2017-07-25" "NVM Library - pmem Tools version 1.3" "NVML Programmer's Manual" .hy .\" Copyright 2014-2017, Intel Corporation .\" diff --git a/doc/generated/pmempool-info.1 b/doc/generated/pmempool-info.1 index aeec50e2850..476ba1f4c6b 100644 --- a/doc/generated/pmempool-info.1 +++ b/doc/generated/pmempool-info.1 @@ -1,6 +1,6 @@ .\" Automatically generated by Pandoc 1.16.0.2 .\" -.TH "PMEMPOOL-INFO" "1" "2017-07-21" "NVM Library - pmem Tools version 1.3" "NVML Programmer's Manual" +.TH "PMEMPOOL-INFO" "1" "2017-07-25" "NVM Library - pmem Tools version 1.3" "NVML Programmer's Manual" .hy .\" Copyright 2014-2017, Intel Corporation .\" diff --git a/doc/generated/pmempool-rm.1 b/doc/generated/pmempool-rm.1 index 79ded6ccb14..6834f022412 100644 --- a/doc/generated/pmempool-rm.1 +++ b/doc/generated/pmempool-rm.1 @@ -1,6 +1,6 @@ .\" Automatically generated by Pandoc 1.16.0.2 .\" -.TH "PMEMPOOL-RM" "1" "2017-07-21" "NVM Library - pmem Tools version 1.3" "NVML Programmer's Manual" +.TH "PMEMPOOL-RM" "1" "2017-07-25" "NVM Library - pmem Tools version 1.3" "NVML Programmer's Manual" .hy .\" Copyright 2014-2017, Intel Corporation .\" diff --git a/doc/generated/pmempool-sync.1 b/doc/generated/pmempool-sync.1 index be0bf136275..7976337f69d 100644 --- a/doc/generated/pmempool-sync.1 +++ b/doc/generated/pmempool-sync.1 @@ -1,6 +1,6 @@ .\" Automatically generated by Pandoc 1.16.0.2 .\" -.TH "PMEMPOOL-SYNC" "1" "2017-07-21" "NVM Library - pmem Tools version 1.3" "NVML Programmer's Manual" +.TH "PMEMPOOL-SYNC" "1" "2017-07-25" "NVM Library - pmem Tools version 1.3" "NVML Programmer's Manual" .hy .\" Copyright 2014-2017, Intel Corporation .\" diff --git a/doc/generated/pmempool-transform.1 b/doc/generated/pmempool-transform.1 index e8a411baa83..efb2677e1a8 100644 --- a/doc/generated/pmempool-transform.1 +++ b/doc/generated/pmempool-transform.1 @@ -1,6 +1,6 @@ .\" Automatically generated by Pandoc 1.16.0.2 .\" -.TH "PMEMPOOL-TRANSFORM" "1" "2017-07-21" "NVM Library - pmem Tools version 1.3" "NVML Programmer's Manual" +.TH "PMEMPOOL-TRANSFORM" "1" "2017-07-25" "NVM Library - pmem Tools version 1.3" "NVML Programmer's Manual" .hy .\" Copyright 2014-2017, Intel Corporation .\" diff --git a/doc/generated/pmempool.1 b/doc/generated/pmempool.1 index 9a5d3e8009b..43e66079d64 100644 --- a/doc/generated/pmempool.1 +++ b/doc/generated/pmempool.1 @@ -1,6 +1,6 @@ .\" Automatically generated by Pandoc 1.16.0.2 .\" -.TH "PMEMPOOL" "1" "2017-07-21" "NVM Library - pmem Tools version 1.3" "NVML Programmer's Manual" +.TH "PMEMPOOL" "1" "2017-07-25" "NVM Library - pmem Tools version 1.3" "NVML Programmer's Manual" .hy .\" Copyright 2014-2017, Intel Corporation .\" diff --git a/doc/generated/rpmemd.1 b/doc/generated/rpmemd.1 index f8cab74243a..a4979f3015e 100644 --- a/doc/generated/rpmemd.1 +++ b/doc/generated/rpmemd.1 @@ -1,6 +1,6 @@ .\" Automatically generated by Pandoc 1.16.0.2 .\" -.TH "RPMEMD" "1" "2017-07-21" "NVM Library - version 1.3" "NVML Programmer's Manual" +.TH "RPMEMD" "1" "2017-07-25" "NVM Library - version 1.3" "NVML Programmer's Manual" .hy .\" Copyright 2014-2017, Intel Corporation .\"