PMDK C++ bindings  1.13.0-git85.g2ab46040
This is the C++ bindings documentation for PMDK's libpmemobj.
pmem::obj::experimental::self_relative_ptr< T > Class Template Reference

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_ptroperator= (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_ptroperator= (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:

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:

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
ptrvolatile 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
oidC-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<U>::type>::value && !std::is_void<U>::value, decltype(static_cast<T *>(std::declval<U *>()))>::type>
pmem::obj::experimental::self_relative_ptr< T >::self_relative_ptr ( self_relative_ptr< U > 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_errorwhen 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_errorwhen 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_errorwhen 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]otherthe 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 
)
related

Subtraction operator for self-relative pointers of identical type.

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 
)
related

Less than operator.

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 
)
related

Less or equal than operator.

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 
)
related

Greater than operator.

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 
)
related

Greater or equal than operator.

See less than operator for comparison rules.

◆ swap()

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

Swaps two self_relative_ptr objects of the same type.

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: