PMDK C++ bindings  1.11
This is the C++ bindings documentation for PMDK's libpmemobj.
Public Member Functions | List of all members
pmem::obj::defrag Class Reference

Defrag class. More...

#include <libpmemobj++/defrag.hpp>

Public Member Functions

 defrag (pool_base p)
 The only allowed ctor. More...
 
template<typename T >
std::enable_if< is_defragmentable< T >), void >::type add (T &t)
 Stores address of the referenced object to the defragmentation queue. More...
 
template<typename T , typename = T>
std::enable_if<!is_defragmentable< T >), void >::type add (T &t)
 Specialization for non-defragmentable types. More...
 
template<typename T >
void add (persistent_ptr< T > &ptr)
 Stores address of a persistent_ptr to the defragmentation queue. More...
 
pobj_defrag_result run ()
 Starts defragmentation with previously stored pointers. More...
 

Detailed Description

Defrag class.

This class implements methods used to store pointers from a pool. When defragmentation is called/run, all objects previously stored will be a subject of a defragmentation process.

Important note: an instance of this class can collect pointers only from one pmem::obj::pool instance.

The typical usage example would be:

#include <iostream>
#include <libpmemobj/atomic_base.h>
using namespace pmem::obj;
struct root {
};
void
defrag_example(pool<root> &pop)
{
auto r = pop.root();
transaction::run(pop, [&] {
r->i = make_persistent<int>(5);
r->v = make_persistent<vector<int>>();
r->v2 = make_persistent<vector<double>>();
i_ptr = make_persistent<int>(10);
});
r->v->push_back(15);
/* Create a defrag object for elements in the current pool */
defrag my_defrag(pop);
/* And add all selected pointers for the defragmentation */
my_defrag.add(r->i);
/*
* Adding ptr<vector<T>> means also adding internal container's
* pointer(s), because it ('vector<int>' in this case) implements
* method 'for_each_ptr'.
*/
my_defrag.add(r->v);
/*
* We can also add just the reference of an element (in this case
* vector<double>). This means the persistent_ptr ('r->v2' in this
* case) itself won't be added for the defragmentation.
*/
my_defrag.add(*r->v2);
my_defrag.add(i_ptr);
/*
* Out of curosity, we can check if a class of an object is
* defragmentable or not.
*/
std::cout << is_defragmentable<persistent_ptr<int>>(); /* false */
static_assert(is_defragmentable<vector<char>>(), "should not assert");
pobj_defrag_result result;
try {
/*
* Start when all chosen pointers are added. It can throw an
* error, when failed (e.g. to allocate) in any moment of the
* process.
*/
result = my_defrag.run();
} catch (pmem::defrag_error &e) {
std::cerr << e.what() << "No. of the relocated objects: "
<< e.result.relocated
<< " out of total: " << e.result.total
<< " processed." << std::endl;
}
/* After successful defragmentation result contains basic summary */
std::cout << "No. of relocated objects: " << result.relocated
<< " out of total: " << result.total << " processed."
<< std::endl;
}

Constructor & Destructor Documentation

◆ defrag()

pmem::obj::defrag::defrag ( pool_base  p)
inline

The only allowed ctor.

Binds this object with the selected pool. It will limit pointers, while adding to the defragmentation queue, to only these from that pool. Otherwise during any 'add()' call the runtime_error will be thrown.

Parameters
[in]pa pool, which defrag will be working with/on.

Member Function Documentation

◆ add() [1/3]

template<typename T >
void pmem::obj::defrag::add ( persistent_ptr< T > &  ptr)
inline

Stores address of a persistent_ptr to the defragmentation queue.

It's to be called for a 'persistent_ptr<T>' objects. If 'is_defragmentable<T>()' returns true, the underlying (T) object will also be added to the defragmentation queue.

Parameters
[in]ptrreference of the persistent_ptr to be added to the defragmentation queue.
Exceptions
std::runtime_errorwhen ptr does not point to an object from the pool passed in ctor.

◆ add() [2/3]

template<typename T >
std::enable_if<is_defragmentable<T>), void>::type pmem::obj::defrag::add ( T &  t)
inline

Stores address of the referenced object to the defragmentation queue.

It's to be called on objects (most likely containers), which are defragmentable (they implement 'for_each_ptr' method).

Parameters
[in]tobject of type T to be added to the defragmentation queue.
Exceptions
std::runtime_errorwhen object t is not from the pool passed in ctor.

◆ add() [3/3]

template<typename T , typename = T>
std::enable_if<!is_defragmentable<T>), void>::type pmem::obj::defrag::add ( T &  t)
inline

Specialization for non-defragmentable types.

It's to be called on (most likely trivial) types, which are NOT defragmentable - it means they don't implement 'for_each_ptr' method.

Thanks to this specialization there's no need to check for each object, if it's defragmentable, before calling 'add()'.

Parameters
[in]tobject of type T to be added to the defragmentation queue.
Exceptions
std::runtime_errorwhen object t is not from the pool passed in ctor.

◆ run()

pobj_defrag_result pmem::obj::defrag::run ( )
inline

Starts defragmentation with previously stored pointers.

Note: It can be run within a transaction, but it will only work if the objects selected for the defragmentation won't be changed.

Returns
result struct containing a number of relocated and total processed objects.
Exceptions
rethrowspmem::defrag_error when a failure during defragmentation occurs. Even if this error is thrown, some of objects could have been relocated, see in such case defrag_error.result for summary stats.

The documentation for this class was generated from the following file:
vector.hpp
Vector container with std::vector compatible interface.
pexceptions.hpp
Custom exceptions.
pmem::obj::defrag
Defrag class.
Definition: defrag.hpp:83
pmem::obj::pool::root
persistent_ptr< T > root()
Retrieves pool's root object.
Definition: pool.hpp:624
defrag.hpp
Defragmentation class.
pool.hpp
C++ pmemobj pool.
pmem::defrag_error::result
pobj_defrag_result result
Results of the defragmentation run.
Definition: pexceptions.hpp:231
pmem::obj::transaction::run
static void run(pool_base &pool, std::function< void()> tx, Locks &... locks)
Execute a closure-like transaction and lock locks.
Definition: transaction.hpp:406
pmem::obj
Main libpmemobj namespace.
Definition: allocation_flag.hpp:18
pmem::obj::vector
pmem::obj::vector - persistent container with std::vector compatible interface.
Definition: vector.hpp:41
pmem::defrag_error
Custom defrag error class.
Definition: pexceptions.hpp:207
pmem::obj::persistent_ptr
Persistent pointer class.
Definition: persistent_ptr.hpp:152
pmem::obj::pool
PMEMobj pool class.
Definition: pool.hpp:462
persistent_ptr_base.hpp
Base class for persistent_ptr.