| Home | Libraries | People | FAQ | More

## Class template offset_ptr

boost::interprocess::offset_ptr

## Synopsis

    // In header: <boost/interprocess/offset_ptr.hpp>

    template<typename PointedType, typename DifferenceType, typename OffsetType,
             std::size_t OffsetAlignment>
    class offset_ptr {
    public:
      // types
      typedef PointedType                                                  element_type;
      typedef PointedType *                                                pointer;
      typedef unspecified                                                  reference;
      typedef unspecified                                                  value_type;
      typedef DifferenceType                                               difference_type;
      typedef std::random_access_iterator_tag                              iterator_category;
      typedef OffsetType                                                   offset_type;
      typedef offset_ptr< U, DifferenceType, OffsetType, OffsetAlignment > rebind;

      // construct/copy/destruct
      offset_ptr() noexcept;
      offset_ptr(pointer) noexcept;
      template<typename T> offset_ptr(T *, unspecified = 0) noexcept;
      offset_ptr(const offset_ptr &) noexcept;
      template<typename T2>
        offset_ptr(const offset_ptr< T2, DifferenceType, OffsetType, OffsetAlignment > &) noexcept;
      template<typename T2>
        explicit offset_ptr(const offset_ptr< T2, DifferenceType, OffsetType, OffsetAlignment > &) noexcept;
      template<typename T2, typename P2, typename O2, std::size_t A2>
        offset_ptr(const offset_ptr< T2, P2, O2, A2 > &, unspecified) noexcept;
      template<typename T2, typename P2, typename O2, std::size_t A2>
        offset_ptr(const offset_ptr< T2, P2, O2, A2 > &, unspecified) noexcept;
      template<typename T2, typename P2, typename O2, std::size_t A2>
        offset_ptr(const offset_ptr< T2, P2, O2, A2 > &, unspecified) noexcept;
      template<typename T2, typename P2, typename O2, std::size_t A2>
        offset_ptr(const offset_ptr< T2, P2, O2, A2 > &, unspecified) noexcept;
      offset_ptr & operator=(pointer) noexcept;
      offset_ptr & operator=(const offset_ptr &) noexcept;
      template<typename T2>
        offset_ptr &
        operator=(const offset_ptr< T2, DifferenceType, OffsetType, OffsetAlignment > &) noexcept;

      // public member functions
      pointer get() const noexcept;
      offset_type get_offset() const noexcept;
      pointer operator->() const noexcept;
      reference operator*() const noexcept;
      reference operator[](difference_type) const noexcept;
      offset_ptr & operator+=(difference_type) noexcept;
      offset_ptr & operator-=(difference_type) noexcept;
      offset_ptr & operator++(void) noexcept;
      offset_ptr operator++(int) noexcept;
      offset_ptr & operator--(void) noexcept;
      offset_ptr operator--(int) noexcept;
      explicit operator bool() const noexcept;
      bool operator!() const noexcept;

      // public static functions
      static offset_ptr pointer_to(reference) noexcept;

      // friend functions
      friend offset_ptr operator+(difference_type, offset_ptr) noexcept;
      friend offset_ptr operator+(offset_ptr, difference_type) noexcept;
      friend offset_ptr operator-(offset_ptr, difference_type) noexcept;
      friend offset_ptr operator-(difference_type, offset_ptr) noexcept;
      friend difference_type
      operator-(const offset_ptr &, const offset_ptr &) noexcept;

      // private member functions
      template<typename T2>
        void assign(const offset_ptr< T2, DifferenceType, OffsetType, OffsetAlignment > &,
                    unspecified) noexcept;
      template<typename T2>
        void assign(const offset_ptr< T2, DifferenceType, OffsetType, OffsetAlignment > &,
                    unspecified) noexcept;
    };

## Description

A smart pointer that stores the offset between between the pointer and the the object it points. This allows offset allows special properties, since the pointer is independent from the address of the pointee, if the pointer and the pointee are still separated by the same offset. This feature converts offset_ptr in a smart pointer that can be placed in shared memory and memory mapped files mapped in different addresses in every process.

b>Note: offset_ptr uses implementation defined properties, present in most platforms, for performance reasons:

- Assumes that OffsetType representation of nullptr is (OffsetType)zero.

- Assumes that incrementing a OffsetType obtained from a pointer is equivalent to incrementing the pointer and then converting it back to OffsetType.

### Template Parameters

1.     typename PointedType

   The type of the pointee.

2.     typename DifferenceType

   A signed integer type that can represent the arithmetic operations on the pointer

3.     typename OffsetType

   An unsigned integer type that can represent the distance between two pointers reinterpret_cast-ed as unsigned integers. This type should be at least of the same size of std::uintptr_t. In some systems it's possible to communicate between 32 and 64 bit processes using 64 bit offsets.

4.     std::size_t OffsetAlignment

   Alignment of the OffsetType stored inside. In some systems might be necessary to align it to 64 bits in order to communicate 32 and 64 bit processes using 64 bit offsets.

### `offset_ptr` public types

1. typedef offset_ptr< U, DifferenceType, OffsetType, OffsetAlignment > rebind;

   Compatibility with pointer_traits

### `offset_ptr` public construct/copy/destruct

1.     offset_ptr() noexcept;

   Default constructor (null pointer). Never throws.

2.     offset_ptr(pointer ptr) noexcept;

   Constructor from raw pointer (allows "0" pointer conversion). Never throws.

3.     template<typename T> offset_ptr(T * ptr, unspecified = 0) noexcept;

   Constructor from other pointer. Never throws.

4.     offset_ptr(const offset_ptr & ptr) noexcept;

   Constructor from other `offset_ptr` Never throws.

5.     template<typename T2>
         offset_ptr(const offset_ptr< T2, DifferenceType, OffsetType, OffsetAlignment > & ptr) noexcept;

   Constructor from other `offset_ptr`. Only takes part in overload resolution if T2* is convertible to PointedType*. Never throws.

6.     template<typename T2>
         explicit offset_ptr(const offset_ptr< T2, DifferenceType, OffsetType, OffsetAlignment > & ptr) noexcept;

   Constructor from other `offset_ptr`. Only takes part in overload resolution if PointedType* is constructible from T2* other than via a conversion (e.g. cast to a derived class). Never throws.

7.     template<typename T2, typename P2, typename O2, std::size_t A2>
         offset_ptr(const offset_ptr< T2, P2, O2, A2 > & r, unspecified) noexcept;

   Emulates static_cast operator. Never throws.

8.     template<typename T2, typename P2, typename O2, std::size_t A2>
         offset_ptr(const offset_ptr< T2, P2, O2, A2 > & r, unspecified) noexcept;

   Emulates const_cast operator. Never throws.

9.     template<typename T2, typename P2, typename O2, std::size_t A2>
         offset_ptr(const offset_ptr< T2, P2, O2, A2 > & r, unspecified) noexcept;

   Emulates dynamic_cast operator. Never throws.

10.     template<typename T2, typename P2, typename O2, std::size_t A2>
          offset_ptr(const offset_ptr< T2, P2, O2, A2 > & r, unspecified) noexcept;

    Emulates reinterpret_cast operator. Never throws.

11.     offset_ptr & operator=(pointer from) noexcept;

    Assignment from pointer (saves extra conversion). Never throws.

12.     offset_ptr & operator=(const offset_ptr & ptr) noexcept;

    Assignment from other `offset_ptr`. Never throws.

13.     template<typename T2>
          offset_ptr &
          operator=(const offset_ptr< T2, DifferenceType, OffsetType, OffsetAlignment > & ptr) noexcept;

    Assignment from related `offset_ptr`. If pointers of pointee types are assignable, offset_ptrs will be assignable. Never throws.

### `offset_ptr` public member functions

1.     pointer get() const noexcept;

   Obtains raw pointer from offset. Never throws.

2.     offset_type get_offset() const noexcept;

3.     pointer operator->() const noexcept;

   Pointer-like -> operator. It can return 0 pointer. Never throws.

4.     reference operator*() const noexcept;

   Dereferencing operator, if it is a null `offset_ptr` behavior is undefined. Never throws.

5.     reference operator[](difference_type idx) const noexcept;

   Indexing operator. Never throws.

6.     offset_ptr & operator+=(difference_type offset) noexcept;

   `offset_ptr` += difference_type. Never throws.

7.     offset_ptr & operator-=(difference_type offset) noexcept;

   `offset_ptr` -= difference_type. Never throws.

8.     offset_ptr & operator++(void) noexcept;

   ++offset_ptr. Never throws.

9.     offset_ptr operator++(int) noexcept;

   offset_ptr++. Never throws.

10.     offset_ptr & operator--(void) noexcept;

    –`offset_ptr`. Never throws.

11.     offset_ptr operator--(int) noexcept;

    `offset_ptr`–. Never throws.

12.     explicit operator bool() const noexcept;

    safe bool conversion operator. Never throws.

13.     bool operator!() const noexcept;

    Not operator. Not needed in theory, but improves portability. Never throws

### `offset_ptr` public static functions

1.     static offset_ptr pointer_to(reference r) noexcept;

   Compatibility with pointer_traits

### `offset_ptr` friend functions

1.     friend offset_ptr operator+(difference_type diff, offset_ptr right) noexcept;

   difference_type + `offset_ptr` operation

2.     friend offset_ptr operator+(offset_ptr left, difference_type diff) noexcept;

   `offset_ptr` + difference_type operation

3.     friend offset_ptr operator-(offset_ptr left, difference_type diff) noexcept;

   `offset_ptr` - diff operation

4.     friend offset_ptr operator-(difference_type diff, offset_ptr right) noexcept;

   `offset_ptr` - diff operation

5.     friend difference_type
       operator-(const offset_ptr & pt, const offset_ptr & pt2) noexcept;

   `offset_ptr` - `offset_ptr` operation

### `offset_ptr` private member functions

1.     template<typename T2>
         void assign(const offset_ptr< T2, DifferenceType, OffsetType, OffsetAlignment > & ptr,
                     unspecified) noexcept;

2.     template<typename T2>
         void assign(const offset_ptr< T2, DifferenceType, OffsetType, OffsetAlignment > & ptr,
                     unspecified) noexcept;