Persistent self-relative pointer class. More...

#include <libpmemobj++/experimental/self_relative_ptr.hpp>

Inheritance diagram for pmem::obj::experimental::self_relative_ptr< T >:

Public Types
using	iterator_category = std::random_access_iterator_tag
	Random access iterator requirements (members) More...

using	difference_type = typename base_type::difference_type
	The self_relative_ptr difference type.

using	value_type = T
	The type of the value pointed to by the self_relative_ptr.

using	reference = T &
	The reference type of the value pointed to by the self_relative_ptr.

Public Member Functions
constexpr	self_relative_ptr () noexcept=default
	Default constructor, equal the nullptr.

constexpr	self_relative_ptr (std::nullptr_t) noexcept
	Nullptr constructor.

	self_relative_ptr (element_type *ptr) noexcept
	Volatile pointer constructor. More...

	self_relative_ptr (persistent_ptr< T > ptr) noexcept
	Constructor from persistent_ptr<T>

	self_relative_ptr (PMEMoid oid) noexcept
	PMEMoid constructor. More...

	self_relative_ptr (const self_relative_ptr &ptr) noexcept
	Copy constructor.

template<typename U , 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>
	self_relative_ptr (self_relative_ptr< U > const &r) noexcept
	Copy constructor from a different self_relative_ptr<>. More...

element_type *	get () const noexcept
	Get the direct pointer. More...

persistent_ptr< T >	to_persistent_ptr () const
	Conversion to persitent ptr.

	operator bool () const noexcept
	Bool conversion operator.

	operator persistent_ptr< T > () const
	Conversion operator to persistent_ptr.

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[] (difference_type i) const noexcept
	Array access operator. More...

self_relative_ptr &	operator= (const self_relative_ptr &r)
	Assignment operator. More...

template<typename Y , typename = typename std::enable_if< std::is_convertible<Y , T >::value>::type>
self_relative_ptr< T > &	operator= (self_relative_ptr< Y > const &r)
	Converting assignment operator from a different self_relative_ptr<>. More...

self_relative_ptr &	operator= (std::nullptr_t)
	Nullptr move assignment operator. More...

self_relative_ptr< T > &	operator++ ()
	Prefix increment operator.

self_relative_ptr< T >	operator++ (int)
	Postfix increment operator.

self_relative_ptr< T > &	operator-- ()
	Prefix decrement operator.

self_relative_ptr< T >	operator-- (int)
	Postfix decrement operator.

self_relative_ptr< T > &	operator+= (std::ptrdiff_t s)
	Addition assignment operator.

self_relative_ptr< T > &	operator-= (std::ptrdiff_t s)
	Subtraction assignment operator.

Public Member Functions inherited from pmem::detail::self_relative_ptr_base_impl< std::ptrdiff_t >
constexpr	self_relative_ptr_base_impl () noexcept
	Default constructor, equal the nullptr.

constexpr	self_relative_ptr_base_impl (std::nullptr_t) noexcept
	Nullptr constructor.

	self_relative_ptr_base_impl (void *ptr) noexcept
	Volatile pointer constructor. More...

	self_relative_ptr_base_impl (self_relative_ptr_base_impl const &r) noexcept
	Copy constructor. More...

self_relative_ptr_base_impl &	operator= (self_relative_ptr_base_impl const &r)
	Assignment operator. More...

self_relative_ptr_base_impl &	operator= (std::nullptr_t &&)
	Nullptr move assignment operator. More...

void	swap (self_relative_ptr_base_impl &other)
	Swaps two self_relative_ptr_base objects of the same type. More...

byte_ptr_type	to_byte_pointer () const noexcept
	Conversion to byte pointer.

void *	to_void_pointer () const noexcept
	Conversion to void*.

	operator void * () const noexcept
	Explicit conversion operator to void*.

	operator byte_ptr_type () const noexcept
	Explicit conversion operator to byte pointer.

bool	is_null () const noexcept
	Fast null checking without conversion to void*.

Protected Member Functions
void	verify_type ()
	Verify if element_type is not polymorphic.

Protected Member Functions inherited from pmem::detail::self_relative_ptr_base_impl< std::ptrdiff_t >
	self_relative_ptr_base_impl (difference_type offset) noexcept
	Offset constructor. More...

void *	offset_to_pointer (difference_type other_offset) const noexcept
	Conversion to void* use other offset.

difference_type	pointer_to_offset (const self_relative_ptr_base_impl &ptr) const noexcept
	Conversion self_relative_ptr_base to offset from itself.

difference_type	pointer_to_offset (void *ptr) const noexcept
	Conversion pointer to offset.

Additional Inherited Members
Static Public Member Functions inherited from pmem::detail::self_relative_ptr_base_impl< std::ptrdiff_t >
static difference_type	distance_between (const self_relative_ptr_base_impl &first, const self_relative_ptr_base_impl &second)
	Byte distance between two relative pointers.

Detailed Description

template<typename T>
class pmem::obj::experimental::self_relative_ptr< T >

Persistent self-relative pointer class.

self_relative_ptr implements a smart ptr. It encapsulates the self offseted 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 follow 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 pointer is used with array type, additional requirement is:

Element type must be default constructible

The pointer 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 pointer 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 pointer is undefined behaviour. This is being partially addressed by the following proposal: https://groups.google.com/a/isocpp.org/forum/#!topic/std-proposals/bk8esqk-QooAnother 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.

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

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

The current version uses an approach where we store offset=real_offset-1 and zero offset (or real_offset equal one) is a null pointer. This is needed to support zero initialization.

real_offset = pointer - this;
pointer = real_offset + this;
or pointer = offset + this + 1;

Member Typedef Documentation

◆ iterator_category

template<typename T >

using pmem::obj::experimental::self_relative_ptr< T >::iterator_category = std::random_access_iterator_tag

Random access iterator requirements (members)

The self_relative_ptr iterator category.

Constructor & Destructor Documentation

◆ self_relative_ptr() [1/3]

template<typename T >

pmem::obj::experimental::self_relative_ptr< T >::self_relative_ptr ( element_type * ptr )

inlinenoexcept

Volatile pointer constructor.

Parameters

ptr	volatile pointer, pointing to persistent memory.

◆ self_relative_ptr() [2/3]

template<typename T >

pmem::obj::experimental::self_relative_ptr< T >::self_relative_ptr ( PMEMoid oid )

inlinenoexcept

PMEMoid constructor.

Provided for easy interoperability between C++ and C API's.

Parameters

oid	C-style persistent pointer

◆ self_relative_ptr() [3/3]

template<typename T >

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

pmem::obj::experimental::self_relative_ptr< T >::self_relative_ptr ( self_relative_ptr const & r )

inlinenoexcept

Copy constructor from a different self_relative_ptr<>.

Available only for convertible, non-void types.

Member Function Documentation

◆ get()

template<typename T >

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

inlinenoexcept

Get the direct pointer.

Returns: the direct pointer to the object.

◆ operator=() [1/3]

template<typename T >

self_relative_ptr& pmem::obj::experimental::self_relative_ptr< T >::operator= ( const self_relative_ptr< T > & r )

inline

Assignment operator.

self-relative pointer assignment within a transaction automatically registers this operation so that a rollback is possible.

Exceptions

pmem::transaction_error when adding the object to the transaction failed.

◆ operator=() [2/3]

template<typename T >

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

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

inline

Converting assignment operator from a different self_relative_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.

◆ operator=() [3/3]

template<typename T >

self_relative_ptr& pmem::obj::experimental::self_relative_ptr< T >::operator= ( std::nullptr_t )

inline

Nullptr move assignment operator.

Exceptions

pmem::transaction_error when adding the object to the transaction failed.

◆ operator[]()

template<typename T >

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

pmem::detail::sp_array_access<T>::type pmem::obj::experimental::self_relative_ptr< T >::operator[] ( difference_type i ) const

inlinenoexcept

Array access operator.

Contains run-time bounds checking for static arrays.

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

libpmemobj++/experimental/self_relative_ptr.hpp

Public Types

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

template<typename T> class pmem::obj::experimental::self_relative_ptr< T >

Member Typedef Documentation

◆ iterator_category

Constructor & Destructor Documentation

◆ self_relative_ptr() [1/3]

◆ self_relative_ptr() [2/3]

◆ self_relative_ptr() [3/3]

Member Function Documentation

◆ get()

◆ operator=() [1/3]

◆ operator=() [2/3]

◆ operator=() [3/3]

◆ operator[]()

template<typename T>
class pmem::obj::experimental::self_relative_ptr< T >