Allocation

Functions and classes to support allocations on pmem. More...

Classes
class	pmem::obj::object_traits< T >
	Encapsulates object specific allocator functionality. More...
class	pmem::obj::object_traits< void >
	Object traits specialization for the void type. More...
class	pmem::obj::standard_alloc_policy< T >
	The allocation policy template for a given type. More...
class	pmem::obj::standard_alloc_policy< void >
	Void specialization of the standard allocation policy. More...
class	pmem::obj::allocator< T, Policy, Traits >
	(EXPERIMENTAL) Encapsulates the information about the persistent memory allocation model using PMDK's libpmemobj. More...

Functions
template<typename T , typename... Args>
detail::pp_if_not_array< T >::type	pmem::obj::make_persistent (allocation_flag flag, Args &&... args)
	Transactionally allocate and construct an object of type T. More...
template<typename T , typename... Args>
std::enable_if< !detail::is_first_arg_same< allocation_flag, Args... >::value, typename detail::pp_if_not_array< T >::type >::type	pmem::obj::make_persistent (Args &&... args)
	Transactionally allocate and construct an object of type T. More...
template<typename T >
void	pmem::obj::delete_persistent (typename detail::pp_if_not_array< T >::type ptr)
	Transactionally free an object of type T held in a persistent_ptr. More...
template<typename T >
detail::pp_if_array< T >::type	pmem::obj::make_persistent (std::size_t N, allocation_flag flag=allocation_flag::none())
	Transactionally allocate and construct an array of objects of type T. More...
template<typename T >
detail::pp_if_size_array< T >::type	pmem::obj::make_persistent (allocation_flag flag=allocation_flag::none())
	Transactionally allocate and construct an array of objects of type T. More...
template<typename T >
void	pmem::obj::delete_persistent (typename detail::pp_if_array< T >::type ptr, std::size_t N)
	Transactionally free an array of objects of type T held in a persistent_ptr. More...
template<typename T >
void	pmem::obj::delete_persistent (typename detail::pp_if_size_array< T >::type ptr)
	Transactionally free an array of objects of type T held in a persistent_ptr. More...
template<typename T >
void	pmem::obj::make_persistent_atomic (pool_base &pool, typename detail::pp_if_array< T >::type &ptr, std::size_t N, allocation_flag_atomic flag=allocation_flag_atomic::none())
	Atomically allocate an array of objects. More...
template<typename T >
void	pmem::obj::make_persistent_atomic (pool_base &pool, typename detail::pp_if_size_array< T >::type &ptr, allocation_flag_atomic flag=allocation_flag_atomic::none())
	Atomically allocate an array of objects. More...
template<typename T >
void	pmem::obj::delete_persistent_atomic (typename detail::pp_if_array< T >::type &ptr, std::size_t)
	Atomically deallocate an array of objects. More...
template<typename T >
void	pmem::obj::delete_persistent_atomic (typename detail::pp_if_size_array< T >::type &ptr)
	Atomically deallocate an array of objects. More...
template<typename T , typename... Args>
void	pmem::obj::make_persistent_atomic (pool_base &pool, typename detail::pp_if_not_array< T >::type &ptr, allocation_flag_atomic flag, Args &&... args)
	Atomically allocate and construct an object. More...
template<typename T , typename... Args>
std::enable_if<!detail::is_first_arg_same< allocation_flag_atomic, Args... >::value >::type	pmem::obj::make_persistent_atomic (pool_base &pool, typename detail::pp_if_not_array< T >::type &ptr, Args &&... args)
	Atomically allocate and construct an object. More...
template<typename T >
void	pmem::obj::delete_persistent_atomic (typename detail::pp_if_not_array< T >::type &ptr) noexcept
	Atomically deallocate an object. More...

Detailed Description

Functions and classes to support allocations on pmem.

Libpmemobj-cpp introduced special functions for allocating objects and arrays of objects on persistent memory, with ease. For all make_persistent specializations there are also delete_persistent counterparts. The latter are used to free memory of previously allocated objects or arrays, and calling their destructors. Each specialization comes in two versions - atomic and transactional. First one is distinguished with _atomic suffix (e.g. make_persistent_atomic()) and should not be called within an active transaction - it may lead to undefined behavior in case of transaction's rollback. On the other hand, transactional functions will throw an exception if called outside of an active transaction.

For more flexibly approach we introduced pmem::obj::allocator class, which implements the concept of C++ Allocator. Allocation and deallocation using this class can only happen within an active transactions.

The typical use case of data allocation on pmem would be:

#include <fcntl.h>
#include <libpmemobj++/make_persistent.hpp>
#include <libpmemobj++/p.hpp>
#include <libpmemobj++/persistent_ptr.hpp>
#include <libpmemobj++/pool.hpp>
#include <libpmemobj++/transaction.hpp>
 
using namespace pmem::obj;
 
void
make_persistent_example()
{
    struct compound_type {
 
        compound_type(int val, double dval)
            : some_variable(val), some_other_variable(dval)
        {
        }
 
        void
        set_some_variable(int val)
        {
            some_variable = val;
        }
 
        p<int> some_variable;
        p<double> some_other_variable;
    };
 
    /* pool root structure */
    struct root {
        persistent_ptr<compound_type> comp;
    };
 
    /* create a pmemobj pool */
    auto pop = pool<root>::create("poolfile", "layout", PMEMOBJ_MIN_POOL);
    auto proot = pop.root();
 
    /* typical usage schemes */
    transaction::run(pop, [&] {
        /* allocation with constructor argument passing */
        proot->comp = make_persistent<compound_type>(1, 2.0);
 
        /* transactionally delete the object, ~compound_type() is called
         */
        delete_persistent<compound_type>(proot->comp);
 
        /* set pointer to null so that after restart it's known whether
         * compound_type is still allocated or not */
        proot->comp = nullptr;
    });
 
    /* throws an transaction_scope_error exception */
    auto arr1 = make_persistent<compound_type>(2, 15.0);
    delete_persistent<compound_type>(arr1);
}

For allocator usage see pmem::obj::experimental::inline_string example:

struct Object {
    Object(int x, const char *s) : x(x), s(s)
    {
    }
 
    int x;
 
    /* Using inline_string instead of pmem::obj::string reduces number of
     * allocations and dereferences which cost much more than on DRAM.
     */
    pmem::obj::experimental::inline_string s;
};
 
struct root {
    pmem::obj::persistent_ptr<Object> o;
};
 
void
create_and_print_object(pmem::obj::pool<root> pop)
{
    auto r = pop.root();
 
    pmem::obj::transaction::run(pop, [&] {
        /* String was already allocated in a previous app run. */
        if (r->o)
            return;
 
        auto value = "example";
 
        /* There must be space for the Object itself and "example"
         * string. */
        auto req_capacity =
            sizeof(Object) + strlen(value) + sizeof('\0');
 
        pmem::obj::allocator<void> a;
        r->o = static_cast<pmem::obj::persistent_ptr<Object>>(
            a.allocate(req_capacity));
        new (r->o.get()) Object(1, value);
    });
 
    std::cout << r->o->s.data() << std::endl;
}
 
void
assign_and_print_object(pmem::obj::pool<root> pop)
{
    auto r = pop.root();
 
    auto new_value = "some new, longer value";
 
    if (r->o->s.capacity() >= strlen(new_value)) {
        /* If there is enough capacity, we can assign the new value. */
        r->o->s.assign(new_value);
    } else {
        /* Otherwise we have to reallocate the whole object. */
        pmem::obj::transaction::run(pop, [&] {
            pmem::obj::allocator<void> a;
            auto ptr =
                static_cast<pmem::obj::persistent_ptr<Object>>(
                    a.allocate(sizeof(Object) +
                           strlen(new_value) + 1));
            new (ptr.get()) Object(r->o->x, new_value);
 
            pmem::obj::delete_persistent<Object>(r->o);
            r->o = ptr;
        });
    }
 
    std::cout << r->o->s.data() << std::endl;
}

Function Documentation

delete_persistent() [1/3]

template<typename T >

void pmem::obj::delete_persistent	(	typename detail::pp_if_array< T >::type	ptr,
		std::size_t	N
	)

Transactionally free an array of objects of type T held in a persistent_ptr.

This function can be used to transactionally free an array of objects. Calls the objects' destructors before freeing memory. This overload only participates in overload resolution if T is an array.

To ensure that proper recovery is possible, ptr should be set to null after delete_persistent call and within the same transaction.

Parameters

[in,out]	ptr	persistent pointer to an array of objects.
[in]	N	the size of the array.

Exceptions

transaction_scope_error	if called outside of an active transaction
transaction_free_error	on transactional free failure.

delete_persistent() [2/3]

template<typename T >

void pmem::obj::delete_persistent

(

typename detail::pp_if_not_array< T >::type

ptr

)

Transactionally free an object of type T held in a persistent_ptr.

This function can be used to transactionally free an object. Calls the object's destructor before freeing memory. Cannot be used for array types.

To ensure that proper recovery is possible, ptr should be set to null after delete_persistent call and within the same transaction.

Parameters

[in,out]

ptr

persistent pointer to an object that is not an array.

Exceptions

transaction_scope_error	if called outside of an active transaction
transaction_free_error	on transactional free failure.

delete_persistent() [3/3]

template<typename T >

void pmem::obj::delete_persistent

(

typename detail::pp_if_size_array< T >::type

ptr

)

Transactionally free an array of objects of type T held in a persistent_ptr.

This function can be used to transactionally free an array of objects. Calls the objects' destructors before freeing memory. This overload only participates in overload resolution if T is an array.

To ensure that proper recovery is possible, ptr should be set to null after delete_persistent call and within the same transaction.

Parameters

[in,out]

ptr

persistent pointer to an array of objects.

Exceptions

transaction_scope_error	if called outside of an active transaction
transaction_free_error	on transactional free failure.

delete_persistent_atomic() [1/3]

template<typename T >

void pmem::obj::delete_persistent_atomic	(	typename detail::pp_if_array< T >::type &	ptr,
		std::size_t
	)

Atomically deallocate an array of objects.

There is no way to atomically destroy an object. Any object specific cleanup must be performed elsewhere. Do NOT use this inside transactions, as it might lead to undefined behavior in the presence of transaction aborts.

Parameters

[in,out]

ptr

the persistent_ptr whose pointee is to be deallocated.

delete_persistent_atomic() [2/3]

template<typename T >

void pmem::obj::delete_persistent_atomic ( typename detail::pp_if_not_array< T >::type &  ptr )

noexcept

Atomically deallocate an object.

There is no way to atomically destroy an object. Any object specific cleanup must be performed elsewhere. Do NOT use this inside transactions, as it might lead to undefined behavior in the presence of transaction aborts.

Parameters

[in,out]

ptr

the persistent_ptr whose pointee is to be deallocated.

delete_persistent_atomic() [3/3]

template<typename T >

void pmem::obj::delete_persistent_atomic

(

typename detail::pp_if_size_array< T >::type &

ptr

)

Atomically deallocate an array of objects.

There is no way to atomically destroy an object. Any object specific cleanup must be performed elsewhere. Do NOT use this inside transactions, as it might lead to undefined behavior in the presence of transaction aborts.

Parameters

[in,out]

ptr

the persistent_ptr whose pointee is to be deallocated.

make_persistent() [1/4]

template<typename T , typename... Args>

detail::pp_if_not_array<T>::type pmem::obj::make_persistent	(	allocation_flag	flag,
		Args &&...	args
	)

Transactionally allocate and construct an object of type T.

This function can be used to transactionally allocate an object. Cannot be used for array types.

Parameters

[in]	flag	affects behaviour of allocator
[in,out]	args	a list of parameters passed to the constructor.

Returns

persistent_ptr<T> on success

Exceptions

transaction_scope_error	if called outside of an active transaction
transaction_out_of_memory	if there is no free memory of requested size.
transaction_alloc_error	on transactional allocation failure.
rethrow	exception from T constructor

make_persistent() [2/4]

template<typename T >

detail::pp_if_size_array<T>::type pmem::obj::make_persistent

(

allocation_flag

flag = allocation_flag::none()

)

Transactionally allocate and construct an array of objects of type T.

This function can be used to transactionally allocate an array. This overload only participates in overload resolution if T is an array.

Parameters

[in]

flag

affects behaviour of allocator

Returns

persistent_ptr<T[N]> on success

Exceptions

transaction_scope_error	if called outside of an active transaction
transaction_out_of_memory	if there is no free memory of requested size.
transaction_alloc_error	on transactional allocation failure.
rethrow	exception from T constructor

make_persistent() [3/4]

template<typename T , typename... Args>

std::enable_if< !detail::is_first_arg_same<allocation_flag, Args...>::value, typename detail::pp_if_not_array<T>::type>::type pmem::obj::make_persistent

(

Args &&...

args

)

Transactionally allocate and construct an object of type T.

This function can be used to transactionally allocate an object. Cannot be used for array types.

Parameters

[in,out]

args

a list of parameters passed to the constructor.

Returns

persistent_ptr<T> on success

Exceptions

transaction_scope_error	if called outside of an active transaction
transaction_out_of_memory	if there is no free memory of requested size.
transaction_alloc_error	on transactional allocation failure.
rethrow	exception from T constructor

make_persistent() [4/4]

template<typename T >

detail::pp_if_array<T>::type pmem::obj::make_persistent	(	std::size_t	N,
		allocation_flag	flag = allocation_flag::none()
	)

Transactionally allocate and construct an array of objects of type T.

This function can be used to transactionally allocate an array. This overload only participates in overload resolution if T is an array.

Parameters

[in]	N	the number of array elements.
[in]	flag	affects behaviour of allocator

Returns

persistent_ptr<T[]> on success

Exceptions

transaction_scope_error	if called outside of an active transaction
transaction_out_of_memory	if there is no free memory of requested size.
transaction_alloc_error	on transactional allocation failure.
rethrow	exception from T constructor

make_persistent_atomic() [1/4]

template<typename T >

void pmem::obj::make_persistent_atomic	(	pool_base &	pool,
		typename detail::pp_if_array< T >::type &	ptr,
		std::size_t	N,
		allocation_flag_atomic	flag = allocation_flag_atomic::none()
	)

Atomically allocate an array of objects.

This function can be used to atomically allocate an array of objects. Cannot be used for simple objects. Do NOT use this inside transactions, as it might lead to undefined behavior in the presence of transaction aborts.

Parameters

[in,out]	pool	the pool from which the object will be allocated.
[in,out]	ptr	the persistent pointer to which the allocation will take place.
[in]	N	the number of array elements.
[in]	flag	affects behaviour of allocator

Exceptions

std::bad_alloc

on allocation failure.

make_persistent_atomic() [2/4]

template<typename T , typename... Args>

void pmem::obj::make_persistent_atomic	(	pool_base &	pool,
		typename detail::pp_if_not_array< T >::type &	ptr,
		allocation_flag_atomic	flag,
		Args &&...	args
	)

Atomically allocate and construct an object.

Constructor parameters are passed through variadic parameters. Do NOT use this inside transactions, as it might lead to undefined behavior in the presence of transaction aborts.

Parameters

[in,out]	pool	the pool from which the object will be allocated.
[in,out]	ptr	the persistent pointer to which the allocation will take place.
[in]	flag	affects behaviour of allocator
[in]	args	variadic function parameter containing all parameters passed to the objects constructor.

Exceptions

std::bad_alloc

on allocation failure.

make_persistent_atomic() [3/4]

template<typename T , typename... Args>

std::enable_if<!detail::is_first_arg_same<allocation_flag_atomic, Args...>::value>::type pmem::obj::make_persistent_atomic	(	pool_base &	pool,
		typename detail::pp_if_not_array< T >::type &	ptr,
		Args &&...	args
	)

Atomically allocate and construct an object.

Constructor parameters are passed through variadic parameters. Do NOT use this inside transactions, as it might lead to undefined behavior in the presence of transaction aborts.

Parameters

[in,out]	pool	the pool from which the object will be allocated.
[in,out]	ptr	the persistent pointer to which the allocation will take place.
[in]	args	variadic function parameter containing all parameters passed to the objects constructor.

Exceptions

std::bad_alloc

on allocation failure.

make_persistent_atomic() [4/4]

template<typename T >

void pmem::obj::make_persistent_atomic	(	pool_base &	pool,
		typename detail::pp_if_size_array< T >::type &	ptr,
		allocation_flag_atomic	flag = allocation_flag_atomic::none()
	)

Atomically allocate an array of objects.

This function can be used to atomically allocate an array of objects. Cannot be used for simple objects. Do NOT use this inside transactions, as it might lead to undefined behavior in the presence of transaction aborts.

Parameters

[in,out]	pool	the pool from which the object will be allocated.
[in,out]	ptr	the persistent pointer to which the allocation will take place.
[in]	flag	affects behaviour of allocator

Exceptions

std::bad_alloc

on allocation failure.