pmem::obj::persistent_ptr< T > Class Template Reference

Persistent pointer class. More...

#include <libpmemobj++/persistent_ptr.hpp>

Inheritance diagram for pmem::obj::persistent_ptr< T >:

Public Types
typedef pmem::detail::sp_element< T >::type	element_type
	Type of the actual object with all qualifiers removed, used for easy underlying type access.
template<class U >
using	rebind = pmem::obj::persistent_ptr< U >
	Rebind to a different type of pointer.
using	persistency_type = p< T >
	The persistency type to be used with this pointer.
using	bool_type = bool
	The used bool_type.
using	iterator_category = std::random_access_iterator_tag
	Random access iterator requirements (members) More...
using	difference_type = std::ptrdiff_t
	The persistent_ptr difference type.
using	value_type = T
	The type of the value pointed to by the persistent_ptr.
using	reference = T &
	The reference type of the value pointed to by the persistent_ptr.
using	pointer = persistent_ptr< T >
	The pointer type.

Public Member Functions
	persistent_ptr (persistent_ptr< void > const &rhs) noexcept
	Explicit void specialization of the converting constructor.
	persistent_ptr (persistent_ptr< const void > const &rhs) noexcept
	Explicit const void specialization of the converting constructor.
	persistent_ptr (element_type *ptr)
	Volatile pointer constructor. More...
template<typename U , typename = typename std::enable_if< !std::is_same<T, U>::value && std::is_same<typename std::remove_cv<T>::type, U>::value>::type>
	persistent_ptr (persistent_ptr< U > const &r) noexcept
	Copy constructor from a different persistent_ptr<>. More...
template<typename U , typename Dummy = void, typename = typename std::enable_if< !std::is_same< typename std::remove_cv<T>::type, typename std::remove_cv<U>::type>::value && !std::is_void<U>::value, decltype(static_cast<T *>(std::declval<U *>()))>::type>
	persistent_ptr (persistent_ptr< U > const &r) noexcept
	Copy constructor from a different persistent_ptr<>. More...
	operator persistent_ptr< void > () const noexcept
	Persistent pointer to void conversion operator.
pmem::detail::sp_dereference< T >::type	operator* () const noexcept
	Dereference operator.
pmem::detail::sp_member_access< T >::type	operator-> () const noexcept
	Member access operator.
template<typename = typename std::enable_if<!std::is_void<T>::value>>
pmem::detail::sp_array_access< T >::type	operator[] (std::ptrdiff_t i) const noexcept
	Array access operator. More...
persistent_ptr< T > &	operator++ ()
	Prefix increment operator.
persistent_ptr< T >	operator++ (int)
	Postfix increment operator.
persistent_ptr< T > &	operator-- ()
	Prefix decrement operator.
persistent_ptr< T >	operator-- (int)
	Postfix decrement operator.
persistent_ptr< T > &	operator+= (std::ptrdiff_t s)
	Addition assignment operator.
persistent_ptr< T > &	operator-= (std::ptrdiff_t s)
	Subtraction assignment operator.
template<typename Y , typename = typename std::enable_if< std::is_convertible<Y *, T *>::value>::type>
persistent_ptr< T > &	operator= (persistent_ptr< Y > const &r)
	Converting assignment operator from a different persistent_ptr<>. More...
void	persist (pool_base &pop)
	Persists the content of the underlying object. More...
void	persist (void)
	Persists what the persistent pointer points to. More...
void	flush (pool_base &pop)
	Flushes what the persistent pointer points to. More...
void	flush (void)
	Flushes what the persistent pointer points to. More...
element_type *	get () const noexcept
	Get the direct pointer. More...
Public Member Functions inherited from pmem::obj::persistent_ptr_base
	persistent_ptr_base () noexcept
	Default constructor, zeroes the PMEMoid.
	persistent_ptr_base (PMEMoid oid) noexcept
	PMEMoid constructor. More...
	persistent_ptr_base (persistent_ptr_base &&r) noexcept
	Move constructor.
persistent_ptr_base &	operator= (persistent_ptr_base &&r)
	Move assignment operator.
persistent_ptr_base &	operator= (persistent_ptr_base const &r)
	Assignment operator. More...
persistent_ptr_base &	operator= (std::nullptr_t &&)
	Nullptr move assignment operator. More...
void	swap (persistent_ptr_base &other)
	Swaps two persistent_ptr objects of the same type. More...
const PMEMoid &	raw () const noexcept
	Get PMEMoid encapsulated by this object. More...
PMEMoid *	raw_ptr () noexcept
	Get pointer to PMEMoid encapsulated by this object. More...

Static Public Member Functions
static persistent_ptr< T >	pointer_to (T &ref)
	Create a persistent pointer from a given reference. More...

Protected Member Functions
void	verify_type ()
	Verify if element_type is not polymorphic.
	persistent_ptr (element_type *vptr, int)
	Private constructor enabling persistent_ptrs to volatile objects. More...
template<typename U >
ptrdiff_t	calculate_offset () const
	Calculate in-object offset for structures with inheritance. More...

Detailed Description

template<typename T>
class pmem::obj::persistent_ptr< T >

Persistent pointer class.

persistent_ptr implements a smart ptr. It encapsulates the PMEMoid fat pointer and provides member access, dereference and array access operators.

shared/pointer_requirements.txt

This type does NOT manage the life-cycle of the object. The typical usage example would be:

#include <fcntl.h>
#include <libpmemobj++/make_persistent.hpp>
#include <libpmemobj++/persistent_ptr.hpp>
#include <libpmemobj++/pool.hpp>
#include <libpmemobj++/transaction.hpp>

using namespace pmem::obj;

void
persistent_ptr_example()
{
    struct compound_type {

        void
        set_some_variable(int val)
        {
            some_variable = val;
        }

        int some_variable;
        double some_other_variable;
    };

    /* pool root structure */
    struct root {
        persistent_ptr<compound_type> comp;
    } proot;

    /* create a pmemobj pool */
    auto pop = pool<root>::create("poolfile", "layout", PMEMOBJ_MIN_POOL);

    /* typical usage schemes */
    transaction::run(pop, [&] {
        proot.comp = make_persistent<compound_type>(); /* allocation */
        proot.comp->set_some_variable(12);     /* call function */
        proot.comp->some_other_variable = 2.3; /* set variable */
    });

    /* reading from the persistent_ptr */
    compound_type tmp = *proot.comp;
    (void)tmp;

    /* Changing a persistent_ptr<> variable outside of a transaction is a
     * volatile modification. No way to ensure persistence in case of power
     * failure. */
    proot.comp->some_variable = 12;
}

Casting to persistent_ptr_base can be easily done from any persistent_ptr<T> objects, but when casting between convertible objects be advised to use constructors or operator= specified for such conversion, see:

• persistent_ptr::persistent_ptr(persistent_ptr<U> const &r) ,
• persistent_ptr<T> & operator=(persistent_ptr<Y> const &r) . When casting indirectly with (void *) or using static_cast, and then casting to the second (convertible) type, the offset will not be re-calculated.

Below you can find an example how to and how NOT to cast persistent_ptr's:

#include <iostream>
#include <libpmemobj++/make_persistent.hpp>
#include <libpmemobj++/persistent_ptr.hpp>
#include <libpmemobj++/persistent_ptr_base.hpp>
#include <libpmemobj++/pool.hpp>
#include <libpmemobj++/transaction.hpp>

using namespace pmem::obj;

void
persistent_ptr_conversion_example()
{
    /* pool root structure */
    struct root {
        persistent_ptr<int> pfoo;
    };

    /* create a pmemobj pool */
    auto pop = pool<root>::create("poolfile", "layout", PMEMOBJ_MIN_POOL);

    /* Casting persistent_ptr to persistent_ptr_base */
    transaction::run(pop, [&] {
        /* Good: any persistent_ptr<T> can be stored in a base ptr */
        persistent_ptr_base i_ptr_base = make_persistent<int>(10);

        /*
         * Wrong: even though raw pointer can be used to create new
         * persistent_ptr it's not advised to use it this way, since
         * there's no information about underlying/template type
         */
        persistent_ptr<double> dptr = i_ptr_base.raw();
        std::cout << *dptr; // contains trash data

        /*
         * Acceptable: it's not advised, but it will work properly.
         * Although, you have to be sure the underlying type is correct
         */
        persistent_ptr<int> iptr_nonbase = i_ptr_base.raw();
        std::cout << *iptr_nonbase; // contains proper data

        /*
         * Wrong: illegal call for derived constructor.
         * no viable conversion from 'persistent_ptr_base' to
         * 'persistent_ptr<int>'
         * iptr_nonbase = i_ptr_base;
         */

        /*
         * Wrong: conversion from base class to persistent_ptr<T> is not
         * possible: no matching conversion from 'persistent_ptr_base'
         * to 'persistent_ptr<int>'
         * iptr_nonbase = static_cast<persistent_ptr<int>>(i_ptr_base);
         */

        /* Good: you can use base and ptr classes with volatile pointer
         */
        persistent_ptr<int> i_ptr = make_persistent<int>(10);
        persistent_ptr_base *i_ptr_ref = &i_ptr;
        std::cout << i_ptr_ref->raw().off; /* contains PMEMoid's data */
    });

    struct A {
        uint64_t a;
    };
    struct B {
        uint64_t b;
    };
    struct C : public A, public B {
        uint64_t c;
    };

    /* Convertible types, using struct A, B and C */
    transaction::run(pop, [] {
        /* Good: conversion from type C to B, using copy constructor */
        auto cptr = make_persistent<C>();
        persistent_ptr<B> bptr = cptr;
        std::cout << (bptr->b ==
                  cptr->b); /* thanks to conversion and */
                    /* recalculating offsets it's correct */

        /*
         * Good: conversion from type C to B, using converting
         * assignment operator
         */
        persistent_ptr<B> bptr2;
        bptr2 = cptr;
        std::cout << (bptr2->b == cptr->b); /* true */

        /* Good: direct conversion using static_cast */
        persistent_ptr<B> bptr3 = static_cast<persistent_ptr<B>>(cptr);
        std::cout << (bptr3->b == cptr->b); /* true */

        /*
         * Wrong: conversion to base class and then to different ptr.
         * class no matching conversion from 'persistent_ptr_base' to
         * 'persistent_ptr<B>'
         */
        /*
         * auto cptr2 = (persistent_ptr_base)cptr;
         * persistent_ptr<B> bptr4 =
         *      static_cast<persistent_ptr<B>>(cptr2);
         */

        /*
         * Wrong: conversion to 'void *' and then to different ptr
         * class. ambiguous conversion from 'void *' to
         * 'persistent_ptr<B>'
         */
        /*
         * auto cptr3 = (void *)&cptr;
         * persistent_ptr<B> bptr5 =
         *      static_cast<persistent_ptr<B>>(cptr3);
         */
    });
}

Member Typedef Documentation

template<typename T>

using pmem::obj::persistent_ptr< T >::iterator_category = std::random_access_iterator_tag

Random access iterator requirements (members)

The persistent_ptr iterator category.

Constructor & Destructor Documentation

template<typename T>

pmem::obj::persistent_ptr< T >::persistent_ptr ( element_type *  ptr )

inline

Volatile pointer constructor.

If ptr does not point to an address from a valid pool, the persistent pointer will evaluate to nullptr.

Parameters

ptr	volatile pointer, pointing to persistent memory.

template<typename T>

template<typename U , typename = typename std::enable_if< !std::is_same<T, U>::value && std::is_same<typename std::remove_cv<T>::type, U>::value>::type>

pmem::obj::persistent_ptr< T >::persistent_ptr ( persistent_ptr< U > const &  r )

inlinenoexcept

Copy constructor from a different persistent_ptr<>.

Available only for convertible types.

template<typename T>

template<typename U , typename Dummy = void, typename = typename std::enable_if< !std::is_same< typename std::remove_cv<T>::type, typename std::remove_cv<U>::type>::value && !std::is_void<U>::value, decltype(static_cast<T *>(std::declval<U *>()))>::type>

pmem::obj::persistent_ptr< T >::persistent_ptr ( persistent_ptr< U > const &  r )

inlinenoexcept

Copy constructor from a different persistent_ptr<>.

Available only for convertible, non-void types.

template<typename T>

pmem::obj::persistent_ptr< T >::persistent_ptr ( element_type *  vptr, int    )

inlineprotected

Private constructor enabling persistent_ptrs to volatile objects.

This is internal implementation needed only for the pointer_traits<persistent_ptr>::pointer_to to be able to create valid pointers. This is used in libstdc++'s std::vector::insert().

Member Function Documentation

template<typename T>

template<typename U >

ptrdiff_t pmem::obj::persistent_ptr< T >::calculate_offset ( ) const

inlineprotected

Calculate in-object offset for structures with inheritance.

In case of the given inheritance:

A B \ / C

A pointer to B *ptr = &C should be offset by sizeof(A). This function calculates that offset.

Returns

offset between two compatible pointer types to the same object

template<typename T>

void pmem::obj::persistent_ptr< T >::flush ( pool_base &  pop )

inline

Flushes what the persistent pointer points to.

Parameters

[in]

pop

Pmemobj pool

template<typename T>

void pmem::obj::persistent_ptr< T >::flush ( void  )

inline

Flushes what the persistent pointer points to.

Exceptions

pool_error

when cannot get pool from persistent pointer

template<typename T>

element_type* pmem::obj::persistent_ptr< T >::get ( ) const

inlinenoexcept

Get the direct pointer.

Performs a calculations on the underlying C-style pointer.

Returns

the direct pointer to the object.

template<typename T>

template<typename Y , typename = typename std::enable_if< std::is_convertible<Y *, T *>::value>::type>

persistent_ptr<T>& pmem::obj::persistent_ptr< T >::operator= ( persistent_ptr< Y > const &  r )

inline

Converting assignment operator from a different persistent_ptr<>.

Available only for convertible types. Just like regular assignment, also automatically registers itself in a transaction.

Exceptions

pmem::transaction_error

when adding the object to the transaction failed.

template<typename T>

template<typename = typename std::enable_if<!std::is_void<T>::value>>

pmem::detail::sp_array_access<T>::type pmem::obj::persistent_ptr< T >::operator[] ( std::ptrdiff_t  i ) const

inlinenoexcept

Array access operator.

Contains run-time bounds checking for static arrays.

template<typename T>

void pmem::obj::persistent_ptr< T >::persist ( pool_base &  pop )

inline

Persists the content of the underlying object.

Parameters

[in]

pop

Pmemobj pool

template<typename T>

void pmem::obj::persistent_ptr< T >::persist ( void  )

inline

Persists what the persistent pointer points to.

Exceptions

pool_error

when cannot get pool from persistent pointer

template<typename T>

static persistent_ptr<T> pmem::obj::persistent_ptr< T >::pointer_to ( T &  ref )

inlinestatic

Create a persistent pointer from a given reference.

This can create a persistent_ptr to a volatile object, use with extreme caution.

Parameters

ref	reference to an object.

---

The documentation for this class was generated from the following files:

• libpmemobj++/detail/common.hpp
• libpmemobj++/persistent_ptr.hpp