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	base_type = self_relative_ptr_base

using	this_type = self_relative_ptr

using	element_type = typename pmem::detail::sp_element< T >::type

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.

using	offset_type = OffsetType

using	byte_type = uint8_t

using	byte_ptr_type = byte_type *

using	const_byte_ptr_type = const byte_type *

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.

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*.

Static Public Member Functions
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.

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

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.

Protected Attributes
offset_type	offset

Related Functions
(Note that these are not member functions.)
template<class T >
void	swap (self_relative_ptr< T > &a, self_relative_ptr< T > &b)
	Swaps two self_relative_ptr objects of the same type. More...

template<typename T , typename Y >
bool	operator== (self_relative_ptr< T > const &lhs, self_relative_ptr< Y > const &rhs) noexcept
	Equality operator.

template<typename T , typename Y >
bool	operator!= (self_relative_ptr< T > const &lhs, self_relative_ptr< Y > const &rhs) noexcept
	Inequality operator.

template<typename T >
bool	operator== (self_relative_ptr< T > const &lhs, std::nullptr_t) noexcept
	Equality operator with nullptr.

template<typename T >
bool	operator== (std::nullptr_t, self_relative_ptr< T > const &lhs) noexcept
	Equality operator with nullptr.

template<typename T >
bool	operator!= (self_relative_ptr< T > const &lhs, std::nullptr_t) noexcept
	Inequality operator with nullptr.

template<typename T >
bool	operator!= (std::nullptr_t, self_relative_ptr< T > const &lhs) noexcept
	Inequality operator with nullptr.

template<typename T , typename Y >
bool	operator< (self_relative_ptr< T > const &lhs, self_relative_ptr< Y > const &rhs) noexcept
	Less than operator. More...

template<typename T , typename Y >
bool	operator<= (self_relative_ptr< T > const &lhs, self_relative_ptr< Y > const &rhs) noexcept
	Less or equal than operator. More...

template<typename T , typename Y >
bool	operator> (self_relative_ptr< T > const &lhs, self_relative_ptr< Y > const &rhs) noexcept
	Greater than operator. More...

template<typename T , typename Y >
bool	operator>= (self_relative_ptr< T > const &lhs, self_relative_ptr< Y > const &rhs) noexcept
	Greater or equal than operator. More...

template<typename T >
bool	operator< (self_relative_ptr< T > const &lhs, std::nullptr_t) noexcept
	Compare a self_relative_ptr with a null pointer.

template<typename T >
bool	operator< (std::nullptr_t, self_relative_ptr< T > const &rhs) noexcept
	Compare a self_relative_ptr with a null pointer.

template<typename T >
bool	operator<= (self_relative_ptr< T > const &lhs, std::nullptr_t) noexcept
	Compare a self_relative_ptr with a null pointer.

template<typename T >
bool	operator<= (std::nullptr_t, self_relative_ptr< T > const &rhs) noexcept
	Compare a self_relative_ptr with a null pointer.

template<typename T >
bool	operator> (self_relative_ptr< T > const &lhs, std::nullptr_t) noexcept
	Compare a self_relative_ptr with a null pointer.

template<typename T >
bool	operator> (std::nullptr_t, self_relative_ptr< T > const &rhs) noexcept
	Compare a self_relative_ptr with a null pointer.

template<typename T >
bool	operator>= (self_relative_ptr< T > const &lhs, std::nullptr_t) noexcept
	Compare a self_relative_ptr with a null pointer.

template<typename T >
bool	operator>= (std::nullptr_t, self_relative_ptr< T > const &rhs) noexcept
	Compare a self_relative_ptr with a null pointer.

template<typename T >
self_relative_ptr< T >	operator+ (self_relative_ptr< T > const &lhs, std::ptrdiff_t s)
	Addition operator for self-relative pointers.

template<typename T >
self_relative_ptr< T >	operator- (self_relative_ptr< T > const &lhs, std::ptrdiff_t s)
	Subtraction operator for self-relative pointers.

template<typename T , typename Y , typename = typename std::enable_if< std::is_same<typename std::remove_cv<T>::type, typename std::remove_cv<Y>::type>::value>>
ptrdiff_t	operator- (self_relative_ptr< T > const &lhs, self_relative_ptr< Y > const &rhs)
	Subtraction operator for self-relative pointers of identical type. More...

template<typename T >
std::ostream &	operator<< (std::ostream &os, self_relative_ptr< T > const &ptr)
	Ostream operator.

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 offsetted 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.

◆ swap()

template<typename OffsetType >

void pmem::detail::self_relative_ptr_base_impl< OffsetType >::swap ( self_relative_ptr_base_impl< OffsetType > & other )

inlineinherited

Swaps two self_relative_ptr_base objects of the same type.

Parameters

[in,out] other the other self_relative_ptr to swap.

Friends And Related Function Documentation

◆ operator-()

template<typename T , typename Y , typename = typename std::enable_if< std::is_same<typename std::remove_cv<T>::type, typename std::remove_cv<Y>::type>::value>>

ptrdiff_t operator-	(	self_relative_ptr< T > const &	lhs,
		self_relative_ptr< Y > const &	rhs
	)

Calculates the offset difference. Calculating the difference of pointers from objects of different pools is not allowed.

◆ operator<()

template<typename T , typename Y >

bool operator<	(	self_relative_ptr< T > const &	lhs,
		self_relative_ptr< Y > const &	rhs
	)

Returns: true if the sum(this, offset) of lhs is less than the sum(this, offset) of rhs. Returns false otherwise.

◆ operator<=()

template<typename T , typename Y >

bool operator<=	(	self_relative_ptr< T > const &	lhs,
		self_relative_ptr< Y > const &	rhs
	)

See less than operator for comparison rules.

◆ operator>()

template<typename T , typename Y >

bool operator>	(	self_relative_ptr< T > const &	lhs,
		self_relative_ptr< Y > const &	rhs
	)

See less than operator for comparison rules.

◆ operator>=()

template<typename T , typename Y >

bool operator>=	(	self_relative_ptr< T > const &	lhs,
		self_relative_ptr< Y > const &	rhs
	)

See less than operator for comparison rules.

◆ swap()

template<class T >

void swap	(	self_relative_ptr< T > &	a,
		self_relative_ptr< T > &	b
	)

Non-member swap function as required by Swappable concept. en.cppreference.com/w/cpp/concept/Swappable

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

libpmemobj++/experimental/self_relative_ptr.hpp

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Related Functions

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[]()

◆ swap()

Friends And Related Function Documentation

◆ operator-()

◆ operator<()

◆ operator<=()

◆ operator>()

◆ operator>=()

◆ swap()

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