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 <libpmemobj++/container/vector.hpp>
#include <libpmemobj++/defrag.hpp>
#include <libpmemobj++/persistent_ptr_base.hpp>
#include <libpmemobj++/pexceptions.hpp>
#include <libpmemobj++/pool.hpp>
#include <libpmemobj/atomic_base.h>
 
using namespace pmem::obj;
 
void
defrag_example()
{
    struct root {
        persistent_ptr<int> i;
        persistent_ptr<vector<int>> v;
        persistent_ptr<vector<double>> v2;
    };
 
    auto pop = pool<root>::create("poolfile", "layout", PMEMOBJ_MIN_POOL);
    auto r = pop.root();
 
    persistent_ptr<int> i_ptr;
    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]

p

a 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]

ptr

reference of the persistent_ptr to be added to the defragmentation queue.

Exceptions

std::runtime_error

when 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]

t

object of type T to be added to the defragmentation queue.

Exceptions

std::runtime_error

when 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]

t

object of type T to be added to the defragmentation queue.

Exceptions

std::runtime_error

when 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

rethrows

pmem::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:

• libpmemobj++/defrag.hpp