Merge pull request #2157 from nvml-bot/doc-update

doc: automatic docs update

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
 .\"

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
 .\"

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
 .\"

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

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
 .\"

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
 .\"

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
 .\"

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
 .\"

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
 .\"

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
 .\"

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
 .\"

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
 .\"

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
 .\"

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
 .\"

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
 .\"

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
 .\"

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
 .\"

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
 .\"