diff --git a/doc/generated/pmemobj_alloc.3 b/doc/generated/pmemobj_alloc.3 index a117ffd8248d480dee069154ad0a7ca701fd83ab..d3f1c4646e13a57d3328505c8406a85f69ecc138 100644 --- a/doc/generated/pmemobj_alloc.3 +++ b/doc/generated/pmemobj_alloc.3 @@ -1,8 +1,8 @@ .\" Automatically generated by Pandoc 2.0.6 .\" -.TH "PMEMOBJ_ALLOC" "3" "2019-10-09" "PMDK - pmemobj API version 2.3" "PMDK Programmer's Manual" +.TH "PMEMOBJ_ALLOC" "3" "2020-01-16" "PMDK - pmemobj API version 2.3" "PMDK Programmer's Manual" .hy -.\" Copyright 2017-2018, Intel Corporation +.\" Copyright 2017-2020, Intel Corporation .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions @@ -65,6 +65,8 @@ int\ pmemobj_strdup(PMEMobjpool\ *pop,\ PMEMoid\ *oidp,\ const\ char\ *s, int\ pmemobj_wcsdup(PMEMobjpool\ *pop,\ PMEMoid\ *oidp,\ const\ wchar_t\ *s, \ \ \ \ uint64_t\ type_num); size_t\ pmemobj_alloc_usable_size(PMEMoid\ oid); +int\ pmemobj_defrag(PMEMobjpool\ *pop,\ PMEMoid\ **oidv,\ size_t\ oidcnt, +\ \ \ \ struct\ pobj_defrag_result\ *result); POBJ_NEW(PMEMobjpool\ *pop,\ TOID\ *oidp,\ TYPE,\ pmemobj_constr\ constructor, \ \ \ \ void\ *arg) @@ -272,6 +274,37 @@ number from the typed \f[I]OID\f[] to \f[B]pmemobj_zrealloc\f[](). The \f[B]POBJ_FREE\f[]() macro is a wrapper around the \f[B]pmemobj_free\f[]() function which takes a pointer to the typed \f[I]OID\f[] instead of to \f[I]PMEMoid\f[]. +.PP +The \f[B]pmemobj_defrag\f[]() function performs defragmentation on the +objects provided through the array of pointers to PMEMoids \f[I]oidv\f[] +with size \f[I]oidcnt\f[]. +If an object from the provided array is selected to be moved to a new +location in the heap, it is reallocated and all provided pointers to +that object are atomically updated. +To maintain data structure consistency, applications should always +provide all pointers for an object to \f[B]pmemobj_defrag\f[] method. +This ensures that, even in the presence of failures, all pointers to the +object will either point to the old or a new location. +All objects and pointers to objects should belong to the pool +\f[I]pop\f[] or, in case of pointers, can also reside in volatile +memory. +Defragmentation across pools is not supported. +Objects in the array that are \f[I]OID_NULL\f[] are skipped over and no +operation is performed on them. +All other objects must have been allocated by an earlier call to +\f[B]pmemobj_alloc\f[](), \f[B]pmemobj_xalloc\f[](), +\f[B]pmemobj_zalloc\f[](), \f[B]pmemobj_realloc\f[](), +\f[B]pmemobj_zrealloc\f[](), \f[B]pmemobj_strdup\f[]() or +\f[B]pmemobj_wcsdup\f[](). +The \f[I]result\f[] variable is an instance of \f[I]struct +pobj_defrag_result\f[] and, if not NULL, can be used to read +\f[I]total\f[], the number of objects found that were processed, and +\f[I]relocated\f[], the number of objects that were relocated during +defragmentation. +These variables are always initialized and can be non\-zero, even if the +return value of \f[B]pmemobj_defrag\f[]() indicated a failure. +This is because the failure might have occurred after some objects were +already processed. .SH RETURN VALUE .PP On success, \f[B]pmemobj_alloc\f[]() and \f[B]pmemobj_xalloc\f[] return @@ -312,6 +345,11 @@ On other errors, they return \-1 and set \f[I]errno\f[] appropriately. The \f[B]pmemobj_alloc_usable_size\f[]() function returns the number of usable bytes in the object represented by \f[I]oid\f[]. If \f[I]oid\f[] is \f[B]OID_NULL\f[], it returns 0. +.PP +On success, \f[B]pmemobj_defrag\f[]() returns 0. +If defragmentation was unsuccessful or only partially successful +(i.e.\ if it was aborted halfway through due to lack of resources), \-1 +is returned. .SH SEE ALSO .PP \f[B]free\f[](3), \f[B]POBJ_FOREACH\f[](3), \f[B]realloc\f[](3), diff --git a/doc/generated/pmemobj_ctl_get.3 b/doc/generated/pmemobj_ctl_get.3 index 1de49fbb40207da5d459a6d57dd8f4d5bdd9d608..84be57b2841cf2dcec90b1d25ad2bdc4d71bcab1 100644 --- a/doc/generated/pmemobj_ctl_get.3 +++ b/doc/generated/pmemobj_ctl_get.3 @@ -1,8 +1,8 @@ .\" Automatically generated by Pandoc 2.0.6 .\" -.TH "PMEMOBJ_CTL_GET" "3" "2019-10-09" "PMDK - pmemobj API version 2.3" "PMDK Programmer's Manual" +.TH "PMEMOBJ_CTL_GET" "3" "2020-01-16" "PMDK - pmemobj API version 2.3" "PMDK Programmer's Manual" .hy -.\" Copyright 2017-2019, Intel Corporation +.\" Copyright 2017-2020, Intel Corporation .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions @@ -358,22 +358,65 @@ libpmemobj). 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 -stats.enabled | rw | \- | int | int | \- | boolean +stats.enabled | rw | \- | enum pobj_stats_enabled | enum +pobj_stats_enabled | \- | string .PP Enables or disables runtime collection of statistics. +There are two types of statistics: persistent and transient ones. +Persistent statistics survive pool restarts, whereas transient ones +don't. Statistics are not recalculated after enabling; any operations that occur between disabling and re\-enabling will not be reflected in subsequent values. .PP -Statistics are disabled by default. -Enabling them may have non\-trivial performance impact. +Only transient statistics are enabled by default. +Enabling persistent statistics may have non\-trivial performance impact. .PP -stats.heap.curr_allocated | r\- | \- | int | \- | \- | \- +stats.heap.curr_allocated | r\- | \- | uint64_t | \- | \- | \- .PP 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. .PP +This is a persistent statistic. +.PP +stats.heap.run_allocated | r\- | \- | uint64_t | \- | \- | \- +.PP +Reads the number of bytes currently allocated using run\-based +allocation classes, i.e., huge allocations are not accounted for in this +statistic. +This is useful for comparison against stats.heap.run_active to estimate +the ratio between active and allocated memory. +.PP +This is a transient statistic and is rebuilt every time the pool is +opened. +.PP +stats.heap.run_active | r\- | \- | uint64_t | \- | \- | \- +.PP +Reads the number of bytes currently occupied by all run memory blocks, +including both allocated and free space, i.e., this is all the all space +that's not occupied by huge allocations. +.PP +This value is a sum of all allocated and free run memory. +In systems where memory is efficiently used, \f[C]run_active\f[] should +closely track \f[C]run_allocated\f[], and the amount of active, but +free, memory should be minimal. +.PP +A large relative difference between active memory and allocated memory +is indicative of heap fragmentation. +This information can be used to make a decision to call +\f[B]pmemobj_defrag()\f[](3) if the fragmentation looks to be high. +.PP +However, for small heaps \f[C]run_active\f[] might be disproportionately +higher than \f[C]run_allocated\f[] because the allocator typically +activates a significantly larger amount of memory than is required to +satisfy a single request in the anticipation of future needs. +For example, the first allocation of 100 bytes in a heap will trigger +activation of 256 kilobytes of space. +.PP +This is a transient statistic and is rebuilt lazily every time the pool +is opened. +.PP heap.size.granularity | rw\- | \- | uint64_t | uint64_t | \- | long long .PP Reads or modifies the granularity with which the heap grows when OOM.