<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
  <meta http-equiv="Content-Style-Type" content="text/css" />
  <meta name="generator" content="pandoc" />
  <meta name="author" content="Pablo Halpern phalpern@halpernwightsoftware.com" />
  <title>P1083r1 | Move resource_adaptor from Library TS to the C++ WP</title>
  <style type="text/css">code{white-space: pre;}</style>
</head>
<body>
<div id="header">
<h1 class="title">P1083r1 | Move resource_adaptor from Library TS to the C++ WP</h1>
<h2 class="author">Pablo Halpern <script type="text/javascript">
<!--
h='&#104;&#x61;&#108;&#112;&#x65;&#114;&#110;&#x77;&#x69;&#x67;&#104;&#116;&#x73;&#x6f;&#102;&#116;&#x77;&#x61;&#114;&#x65;&#46;&#x63;&#x6f;&#x6d;';a='&#64;';n='&#112;&#104;&#x61;&#108;&#112;&#x65;&#114;&#110;';e=n+a+h;
document.write('<a h'+'ref'+'="ma'+'ilto'+':'+e+'">'+e+'<\/'+'a'+'>');
// -->
</script><noscript>&#112;&#104;&#x61;&#108;&#112;&#x65;&#114;&#110;&#32;&#x61;&#116;&#32;&#104;&#x61;&#108;&#112;&#x65;&#114;&#110;&#x77;&#x69;&#x67;&#104;&#116;&#x73;&#x6f;&#102;&#116;&#x77;&#x61;&#114;&#x65;&#32;&#100;&#x6f;&#116;&#32;&#x63;&#x6f;&#x6d;</noscript></h2>
<h3 class="date">2018-10-07 | Target audience: Library Evolution</h3>
</div>
<h1 id="abstract"><span class="header-section-number">1</span> Abstract</h1>
<p>When the polymorphic allocator infrastructure was moved from the Library Fundamentals TS to the C++17 working draft, <code>pmr::resource_adaptor</code> was left behind. It is not clear whether this was an omission or a deliberately conservative move, but the absence of <code>resource_adaptor</code> in the standard is a hole that must be plugged for a smooth transition to the ubiquitous use of <code>polymorphic_allocator</code>, as proposed in <a href="http://wg21.link/p0339">P0339</a> and <a href="http://wg21.link/p0987">P0987</a>. This paper proposes that <code>pmr::resource_adaptor</code> be moved from the LFTS and added to the C++20 working draft.</p>
<h1 id="changes-from-r0"><span class="header-section-number">2</span> Changes from R0</h1>
<p>Added a note for LWG to consider clarifying the alignment requirements for <code>resource_adaptor&lt;A&gt;::do_allocate()</code>. Changed rebind type from <code>char</code> to <code>byte</code>. Rebased to July 2018 draft of the C++ WP.</p>
<h1 id="motivation"><span class="header-section-number">3</span> Motivation</h1>
<p>It is expected that more and more classes, especially those that would not otherwise be templates, will use <code>pmr::polymorphic_allocator&lt;byte&gt;</code> to allocate memory. In order to pass an allocator to one of these classes, the allocator must either already be a polymorphic allocator, or must be adapted from a non-polymorphic allocator. The process of adaptation is facilitated by <code>pmr::resource_adaptor</code>, which is a simple class template, has been in the LFTS for a long time, and has been fully implemented. It is therefore a low-risk, high-benefit component to add to the C++ WP.</p>
<h1 id="impact-on-the-standard"><span class="header-section-number">4</span> Impact on the standard</h1>
<p><code>pmr::resource_adaptor</code> is a pure library extension requiring no changes to the core language nor to any existing classes in the standard library.</p>
<h1 id="proposal"><span class="header-section-number">5</span> Proposal</h1>
<p>This proposal is based on the Library Fundamentals TS v2, <a href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2016/n4617.pdf">N4617</a> and the July 2018 draft of the C++ WP, <a href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2018/n4762.pdf">N4762</a>.</p>
<p>In section 19.12.1 [mem.res.syn] of the C++ WD, add the following declaration immediately after the declaration of <code>operator!=(const polymorphic_allocator...)</code>:</p>
<pre><code>// 19.12.x resource adaptor
// The name resource_adaptor_imp is for exposition only.
template &lt;class Allocator&gt; class resource_adaptor_imp;

template &lt;class Allocator&gt;
  using resource_adaptor = resource_adaptor_imp&lt;
    typename allocator_traits&lt;Allocator&gt;::template rebind_alloc&lt;byte&gt;&gt;;</code></pre>
<p>Insert between sections 19.12.3 [mem.poly.allocator.class] and 19.12.4 [mem.res.global] of the C++ WP, the whole of section 8.7 [memory.resource.adaptor] from the LFTS v2, including all of its subsections, renumbered appropriately.</p>
<p><strong>LWG NOTE:</strong> There was some concern that alignment support was unclear for <code>resource_adaptor</code>. We might consider replacing the <em>Returns</em> clause of <code>do_allocate</code> with something like the following (note the use of normative encouragement in the last sentence:</p>
<p><em>Returns:</em> a pointer to allocated storage obtained by calling the <code>allocate</code> member function on a suitably rebound copy of <code>m_alloc</code> such that the size and alignment of the allocated memory meet the requirements for a class derived from <code>memory_resource</code>. If the rebound <code>Allocator</code> supports over-aligned memory, then <code>resource_adaptor&lt;Allocator&gt;</code> should also support over-aligned memory.</p>
<h1 id="references"><span class="header-section-number">6</span> References</h1>
<p><a href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2018/n4762.pdf">N4762</a>: Working Draft, Standard for Programming Language C++, Richard Smith, editor, 2018-07-07.</p>
<p><a href="http://www.open-std.org/JTC1/SC22/WG21/docs/papers/2016/n4617.pdf">N4617</a>: Programming Languages - C++ Extensions for Library Fundamentals, Version 2, 2016-11-28.</p>
<p><a href="http://wg21.link/p0339">P0339</a>: polymorphic_allocator&lt;&gt; as a vocabulary type, Pablo Halpern, 2018-04-02.</p>
<p><a href="http://wg21.link/p0987">P0987</a>: polymorphic_allocator<byte> instead of type-erasure, Pablo Halpern, 2018-04-02.</p>
</body>
</html>
