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

Persistent pointer class. More...

#include <libpmemobj++/persistent_ptr.hpp>

Public Types
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
	The persistent_ptr iterator category.
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.
	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.
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...

Static Public Member Functions
static persistent_ptr< T >	pointer_to (T &ref)
	Create a persistent pointer from a given reference. 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.

Template parameter type has following requirements:

• Is not polymorphic
• Has no non-static data members of reference type
• Satisfies Destructible requirement: https://en.cppreference.com/w/cpp/named_req/Destructible
• All non-static data members and base classes follows the same requirements

Even if all of the above requirements are met, type representation may vary depending on ABI and compiler optimizations (as stated in [class.mem]: "the order of allocation of non-static data members with different access control is unspecified"). To enforce the same layout for all ABIs and optimization levels type should satisfy StandardLayoutType requirement.

If persistent_ptr is used with array type, additional requirement is:

• Element type must be default constructible

The persistent_ptr is not designed to work with polymorphic types, as they have runtime RTTI info embedded, which is implementation specific and thus not consistently rebuildable. Such constructs as polymorphic members or members of a union defined within a class held in a persistent_ptr will also yield undefined behavior.

C++ standard states that lifetime of an object is a runtime property [basic.lifetime]. Conditions which must be fulfilled for object's lifetime to begin, imply that using any non-trivially constructible object with persistent_ptr is undefined behaviour. This is being partially addressed by the following proposal: https://groups.google.com/a/isocpp.org/forum/#!topic/std-proposals/bk8esqk-Qoo

Another caveat is that snapshotting elements in a transaction and performing rollback uses memcpy internally. Using memcpy on an object in C++ is allowed by the standard only if the type satisfies TriviallyCopyable requirement.

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;
}

Member Function Documentation

flush() [1/2]

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

flush() [2/2]

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

operator[]()

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.

persist() [1/2]

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

persist() [2/2]

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

pointer_to()

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