memory.html

<cxx-clause id="memory">
  <h1>Memory</h1>

  <cxx-section id="memory.syn">
    <h1>Header &lt;experimental/memory> synopsis</h1>

<pre><code>#include &lt;memory>

namespace std {
  namespace experimental::inline fundamentals_v3 {

    <cxx-ref insynopsis to="memory.observer.ptr"></cxx-ref>
    template &lt;class W> class observer_ptr;

    <cxx-ref insynopsis to="memory.observer.ptr.special"></cxx-ref>
    template &lt;class W>
    void swap(observer_ptr&lt;W>&amp;, observer_ptr&lt;W>&amp;) noexcept;
    template &lt;class W>
    observer_ptr&lt;W> make_observer(W*) noexcept;
    // (in)equality operators
    template &lt;class W1, class W2>
    bool operator==(observer_ptr&lt;W1>, observer_ptr&lt;W2>);

    template &lt;class W1, class W2>
    bool operator!=(observer_ptr&lt;W1>, observer_ptr&lt;W2>);
    template &lt;class W>
    bool operator==(observer_ptr&lt;W>, nullptr_t) noexcept;
    template &lt;class W>
    bool operator!=(observer_ptr&lt;W>, nullptr_t) noexcept;
    template &lt;class W>
    bool operator==(nullptr_t, observer_ptr&lt;W>) noexcept;
    template &lt;class W>
    bool operator!=(nullptr_t, observer_ptr&lt;W>) noexcept;
    // ordering operators
    template &lt;class W1, class W2>
    bool operator&lt;(observer_ptr&lt;W1>, observer_ptr&lt;W2>);
    template &lt;class W1, class W2>
    bool operator>(observer_ptr&lt;W1>, observer_ptr&lt;W2>);
    template &lt;class W1, class W2>
    bool operator&lt;=(observer_ptr&lt;W1>, observer_ptr&lt;W2>);
    template &lt;class W1, class W2>
    bool operator>=(observer_ptr&lt;W1>, observer_ptr&lt;W2>);

  } // namespace experimental::inline fundamentals_v3

  <cxx-ref insynopsis to="memory.observer.ptr.hash"></cxx-ref>
  template &lt;class T> struct hash;
  template &lt;class T> struct hash&lt;experimental::observer_ptr&lt;T>>;

} // namespace std</code></pre>
  </cxx-section>

  <cxx-section id="memory.observer.ptr">
    <h1>Non-owning (observer) pointers</h1>

    <cxx-section id="memory.observer.ptr.overview">
      <h1>Class template <code>observer_ptr</code> overview</h1>

<pre><code>namespace std::experimental::inline fundamentals_v3 {

  template &lt;class W> class observer_ptr {
    using pointer = add_pointer_t&lt;W>;            <i>// exposition-only</i>
    using reference = add_lvalue_reference_t&lt;W>; <i>// exposition-only</i>
  public:
    // publish our template parameter and variations thereof
    using element_type = W;

    <cxx-ref insynopsis to="memory.observer.ptr.ctor"></cxx-ref>
    // default constructor
    constexpr observer_ptr() noexcept;

    // pointer-accepting constructors
    constexpr observer_ptr(nullptr_t) noexcept;
    constexpr explicit observer_ptr(pointer) noexcept;

    // copying constructors (in addition to the implicit copy constructor)
    template &lt;class W2> constexpr observer_ptr(observer_ptr&lt;W2>) noexcept;

    <cxx-ref insynopsis to="memory.observer.ptr.obs"></cxx-ref>
    constexpr pointer get() const noexcept;
    constexpr reference operator*() const;
    constexpr pointer operator->() const noexcept;
    constexpr explicit operator bool() const noexcept;

    <cxx-ref insynopsis to="memory.observer.ptr.conv"></cxx-ref>
    constexpr explicit operator pointer() const noexcept;

    <cxx-ref insynopsis to="memory.observer.ptr.mod"></cxx-ref>
    constexpr pointer release() noexcept;
    constexpr void reset(pointer = nullptr) noexcept;
    constexpr void swap(observer_ptr&amp;) noexcept;
  }; // observer_ptr&lt;>

} // namespace std::experimental::inline fundamentals_v3</code></pre>

      <p>
        A non-owning pointer, known as an <dfn>observer</dfn>, is an object <code>o</code> that stores a pointer to a second object, <code>w</code>.
        In this context, <code>w</code> is known as a <dfn>watched</dfn> object.
        <cxx-note>There is no watched object when the stored pointer is <code>nullptr</code>.</cxx-note>
        An observer takes no responsibility or ownership of any kind for its watched object, if any;
        in particular, there is no inherent relationship between the lifetimes of <code>o</code> and <code>w</code>.
      </p>

      <p>
        Specializations of <code>observer_ptr</code> shall meet the requirements
        of a <cxx-17concept>Cpp17CopyConstructible</cxx-17concept>
        and <cxx-17concept>Cpp17CopyAssignable</cxx-17concept> type.
        The template parameter <code>W</code> of an <code>observer_ptr</code>
        shall not be a reference type, but may be an incomplete type.
      </p>

      <p>
        <cxx-note>The uses of <code>observer_ptr</code> include clarity of interface specification in new code,
          and interoperability with pointer-based legacy code.</cxx-note>
      </p>
    </cxx-section>

    <cxx-section id="memory.observer.ptr.ctor">
      <h1><code>observer_ptr</code> constructors</h1>

      <cxx-function>
        <cxx-signature>constexpr observer_ptr() noexcept;</cxx-signature>
        <cxx-signature>constexpr observer_ptr(nullptr_t) noexcept;</cxx-signature>

        <cxx-effects>Constructs an observer_ptr object that has no corresponding watched object.</cxx-effects>
        <cxx-postconditions><code>get() == nullptr</code>.</cxx-postconditions>
      </cxx-function>

      <cxx-function>
        <cxx-signature>constexpr explicit observer_ptr(pointer other) noexcept;</cxx-signature>

        <cxx-postconditions><code>get() == other</code>.</cxx-postconditions>
      </cxx-function>

      <cxx-function>
        <cxx-signature>template &lt;class W2> constexpr observer_ptr(observer_ptr&lt;W2> other) noexcept;</cxx-signature>

        <cxx-constraints><code>W2*</code> is convertible to <code>W*</code>.</cxx-constraints>
        <cxx-postconditions><code>get() == other.get()</code>.</cxx-postconditions>
      </cxx-function>
    </cxx-section>

    <cxx-section id="memory.observer.ptr.obs">
      <h1><code>observer_ptr</code> observers</h1>

      <cxx-function>
        <cxx-signature>constexpr pointer get() const noexcept;</cxx-signature>

        <cxx-returns>The stored pointer.</cxx-returns>
      </cxx-function>

      <cxx-function>
        <cxx-signature>constexpr reference operator*() const;</cxx-signature>

        <cxx-preconditions><code>get() != nullptr</code> is <code>true</code>.</cxx-preconditions>
        <cxx-returns><code>*get()</code>.</cxx-returns>
        <cxx-throws>Nothing.</cxx-throws>
      </cxx-function>

      <cxx-function>
        <cxx-signature>constexpr pointer operator->() const noexcept;</cxx-signature>

        <cxx-returns><code>get()</code>.</cxx-returns>
      </cxx-function>

      <cxx-function>
        <cxx-signature>constexpr explicit operator bool() const noexcept;</cxx-signature>

        <cxx-returns><code>get() != nullptr</code>.</cxx-returns>
      </cxx-function>
    </cxx-section>

    <cxx-section id="memory.observer.ptr.conv">
      <h1><code>observer_ptr</code> conversions</h1>

      <cxx-function>
        <cxx-signature>constexpr explicit operator pointer() const noexcept;</cxx-signature>

        <cxx-returns><code>get()</code>.</cxx-returns>
      </cxx-function>
    </cxx-section>

    <cxx-section id="memory.observer.ptr.mod">
      <h1><code>observer_ptr</code> modifiers</h1>

      <cxx-function>
        <cxx-signature>constexpr pointer release() noexcept;</cxx-signature>

        <cxx-postconditions><code>get() == nullptr</code>.</cxx-postconditions>
        <cxx-returns>The value <code>get()</code> had at the start of the call to <code>release</code>.</cxx-returns>
      </cxx-function>

      <cxx-function>
        <cxx-signature>constexpr void reset(pointer p = nullptr) noexcept;</cxx-signature>

        <cxx-postconditions><code>get() == p</code>.</cxx-postconditions>
      </cxx-function>

      <cxx-function>
        <cxx-signature>constexpr void swap(observer_ptr&amp; other) noexcept;</cxx-signature>

        <cxx-effects>Invokes <code>swap</code> on the stored pointers of <code>*this</code> and <code>other</code>.</cxx-effects>
      </cxx-function>
    </cxx-section>

    <cxx-section id="memory.observer.ptr.special">
      <h1><code>observer_ptr</code> specialized algorithms</h1>

      <cxx-function>
        <cxx-signature>template &lt;class W>
void swap(observer_ptr&lt;W>&amp; p1, observer_ptr&lt;W>&amp; p2) noexcept;</cxx-signature>

        <cxx-effects><code>p1.swap(p2)</code>.</cxx-effects>
      </cxx-function>

      <cxx-function>
        <cxx-signature>template &lt;class W> observer_ptr&lt;W> make_observer(W* p) noexcept;</cxx-signature>

        <cxx-returns><code>observer_ptr&lt;W>{p}</code>.</cxx-returns>
      </cxx-function>

      <cxx-function>
        <cxx-signature>template &lt;class W1, class W2>
bool operator==(observer_ptr&lt;W1> p1, observer_ptr&lt;W2> p2);</cxx-signature>

        <cxx-returns><code>p1.get() == p2.get()</code>.</cxx-returns>
      </cxx-function>

      <cxx-function>
        <cxx-signature>template &lt;class W1, class W2>
bool operator!=(observer_ptr&lt;W1> p1, observer_ptr&lt;W2> p2);</cxx-signature>

        <cxx-returns><code>not (p1 == p2)</code>.</cxx-returns>
      </cxx-function>

      <cxx-function>
        <cxx-signature>template &lt;class W>
bool operator==(observer_ptr&lt;W> p, nullptr_t) noexcept;</cxx-signature>
        <cxx-signature>template &lt;class W>
bool operator==(nullptr_t, observer_ptr&lt;W> p) noexcept;</cxx-signature>

        <cxx-returns><code>not p</code>.</cxx-returns>
      </cxx-function>

      <cxx-function>
        <cxx-signature>template &lt;class W>
bool operator!=(observer_ptr&lt;W> p, nullptr_t) noexcept;</cxx-signature>
        <cxx-signature>template &lt;class W>
bool operator!=(nullptr_t, observer_ptr&lt;W> p) noexcept;</cxx-signature>

        <cxx-returns><code>(bool)p</code>.</cxx-returns>
      </cxx-function>

      <cxx-function>
        <cxx-signature>template &lt;class W1, class W2>
bool operator&lt;(observer_ptr&lt;W1> p1, observer_ptr&lt;W2> p2);</cxx-signature>

        <cxx-returns>
          <code>less&lt;W3>()(p1.get(), p2.get())</code>,
          where <code>W3</code> is the composite pointer type (<cxx-ref in="cxx" to="expr"></cxx-ref>) of <code>W1*</code> and <code>W2*</code>.
        </cxx-returns>
      </cxx-function>

      <cxx-function>
        <cxx-signature>template &lt;class W1, class W2>
bool operator>(observer_ptr&lt;W1> p1, observer_ptr&lt;W2> p2);</cxx-signature>

        <cxx-returns><code>p2 &lt; p1</code>.</cxx-returns>
      </cxx-function>

      <cxx-function>
        <cxx-signature>template &lt;class W1, class W2>
bool operator&lt;=(observer_ptr&lt;W1> p1, observer_ptr&lt;W2> p2);</cxx-signature>

         <cxx-returns><code>not (p2 &lt; p1)</code>.</cxx-returns>
        </cxx-function>

      <cxx-function>
        <cxx-signature>template &lt;class W1, class W2>
bool operator>=(observer_ptr&lt;W1> p1, observer_ptr&lt;W2> p2);</cxx-signature>

        <cxx-returns><code>not (p1 &lt; p2)</code>.</cxx-returns>
      </cxx-function>
    </cxx-section>

    <cxx-section id="memory.observer.ptr.hash">
      <h1><code>observer_ptr</code> hash support</h1>

      <cxx-function>
        <cxx-signature>template &lt;class T> struct hash&lt;experimental::observer_ptr&lt;T>>;</cxx-signature>

        <p>
          The specialization is enabled (<cxx-ref in="cxx" to="unord.hash"></cxx-ref>).
          For an object <code>p</code> of type <code>observer_ptr&lt;T></code>,
          <code>hash&lt;observer_ptr&lt;T>>()(p)</code> evaluates to the same value as <code>hash&lt;T*>()(p.get())</code>.
        </p>
      </cxx-function>
    </cxx-section>
  </cxx-section>

  <cxx-section id="memory.resource.syn">
    <h1>Header <code>&lt;experimental/memory_resource></code> synopsis</h1>

    <pre><code>namespace std::pmr::experimental::inline fundamentals_v3 {

  // The name <var>resource_adaptor_imp</var> is for exposition only.
  template &lt;class Allocator> class <var>resource_adaptor_imp</var>;

  template &lt;class Allocator>
    using resource_adaptor = <var>resource_adaptor_imp</var>&lt;
      typename allocator_traits&lt;Allocator>::template rebind_alloc&lt;char>>;

} // namespace std::pmr::experimental::inline fundamentals_v3</code></pre>
  </cxx-section>

  <cxx-section id="memory.resource.adaptor">
    <h1>Alias template <code>resource_adaptor</code></h1>

    <cxx-section id="memory.resource.adaptor.overview">
      <h1><code>resource_adaptor</code></h1>

      <p>
        An instance of <code>resource_adaptor&lt;Allocator></code> is an adaptor that wraps a <code>memory_resource</code> interface around <code>Allocator</code>.
        In order that <code>resource_adaptor&lt;X&lt;T>></code> and <code>resource_adaptor&lt;X&lt;U>></code> are the same type for any allocator template <code>X</code> and types <code>T</code> and <code>U</code>,
        <code>resource_adaptor&lt;Allocator></code> is rendered as an alias to a class template such that <code>Allocator</code> is rebound to a <code>char</code> value type in every specialization of the class template.
        The requirements on this class template are defined below.
        The name <code><var>resource_adaptor_imp</var></code> is for exposition only and is not normative,
        but the definitions of the members of that class, whatever its name, are normative.
        In addition to the <cxx-17concept>Cpp17Allocator</cxx-17concept> requirements (<cxx-ref in="cxx" to="allocator.requirements"></cxx-ref>), the parameter to <code>resource_adaptor</code> shall meet the following additional requirements:
      </p>
      <ul>
        <li><code>typename allocator_traits&lt;Allocator>::pointer</code> shall be identical to <code>typename allocator_traits&lt;Allocator>::value_type*</code>.</li>
        <li><code>typename allocator_traits&lt;Allocator>::const_pointer</code> shall be identical to <code>typename allocator_traits&lt;Allocator>::value_type const*</code>.</li>
        <li><code>typename allocator_traits&lt;Allocator>::void_pointer</code> shall be identical to <code>void*</code>.</li>
        <li><code>typename allocator_traits&lt;Allocator>::const_void_pointer</code> shall be identical to <code>void const*</code>.</li>
      </ul>

      <pre><code>
// The name <var>resource_adaptor_imp</var> is for exposition only.
template &lt;class Allocator>
class <var>resource_adaptor_imp</var> : public memory_resource {
  // for exposition only
  Allocator m_alloc;

public:
  using allocator_type = Allocator;

  <var>resource_adaptor_imp</var>() = default;
  <var>resource_adaptor_imp</var>(const <var>resource_adaptor_imp</var>&) = default;
  <var>resource_adaptor_imp</var>(<var>resource_adaptor_imp</var>&&) = default;

  explicit <var>resource_adaptor_imp</var>(const Allocator& a2);
  explicit <var>resource_adaptor_imp</var>(Allocator&& a2);

  <var>resource_adaptor_imp</var>& operator=(const <var>resource_adaptor_imp</var>&) = default;

  allocator_type get_allocator() const { return m_alloc; }

protected:
  virtual void* do_allocate(size_t bytes, size_t alignment);
  virtual void do_deallocate(void* p, size_t bytes, size_t alignment);

  virtual bool do_is_equal(const memory_resource& other) const noexcept;
};

template &lt;class Allocator>
  using resource_adaptor = typename <var>resource_adaptor_imp</var>&lt;
    typename allocator_traits&lt;Allocator>::template rebind_alloc&lt;char>>;</code></pre>
    </cxx-section>

    <cxx-section id="memory.resource.adaptor.ctor">
      <h1><code><var>resource_adaptor_imp</var></code> constructors</h1>

      <cxx-function>
        <cxx-signature>explicit <var>resource_adaptor_imp</var>(const Allocator& a2);</cxx-signature>
        <cxx-effects>Initializes <code>m_alloc</code> with <code>a2</code>.</cxx-effects>
      </cxx-function>

      <cxx-function>
        <cxx-signature>explicit <var>resource_adaptor_imp</var>(Allocator&& a2);</cxx-signature>
        <cxx-effects>Initializes <code>m_alloc</code> with <code>std::move(a2)</code>.</cxx-effects>
      </cxx-function>
    </cxx-section>

    <cxx-section id="memory.resource.adaptor.mem">
      <h1><code><var>resource_adaptor_imp</var></code> member functions</h1>

      <cxx-function>
        <cxx-signature>void* do_allocate(size_t bytes, size_t alignment);</cxx-signature>
        <cxx-returns>Allocated memory obtained by calling <code>m_alloc.allocate</code>.
          The size and alignment of the allocated memory shall meet the requirements
          for a class derived from <code>memory_resource</code> (<cxx-ref in="cxx" to="mem.res.class"></cxx-ref>).</cxx-returns>
      </cxx-function>

      <cxx-function>
        <cxx-signature>void do_deallocate(void* p, size_t bytes, size_t alignment);</cxx-signature>
        <cxx-preconditions><code>p</code> was previously allocated using <code>A.allocate</code>, where <code>A == m_alloc</code>, and not subsequently deallocated.</cxx-preconditions>
        <cxx-effects>Returns memory to the allocator using <code>m_alloc.deallocate()</code>.</cxx-effects>
      </cxx-function>

      <cxx-function>
        <cxx-signature>bool do_is_equal(const memory_resource& other) const noexcept;</cxx-signature>
        <p>Let <code>p</code> be <code>dynamic_cast&lt;const <var>resource_adaptor_imp</var>*>(&other)</code>.</p>
        <cxx-returns><code>false</code> if <code>p</code> is null, otherwise the value of <code>m_alloc == p->m_alloc</code>.</cxx-returns>
      </cxx-function>
    </cxx-section>
  </cxx-section>
</cxx-clause>