P0401R6 Providing size feedback in the Allocator interface

Author: jensmaurer

source/lib-intro.tex

@@ -1902,9 +1902,7 @@
 is small. That is, there is no need for a container to maintain its own
 free list.
 \end{footnote}
-\begin{tailnote}
-If \tcode{n == 0}, the return value is unspecified.
-\end{tailnote}
+See Note C, below.
 &  \\ \rowsep
 
 \tcode{a.allocate(n, y)}    &
@@ -1913,12 +1911,36 @@
     it is intended as an aid to locality. &
   \tcode{a.allocate(n)}     \\ \rowsep
 
+\tcode{a.allocate_at_least(n)} &
+  \tcode{allocation_result<X::pointer>} &
+  \returns
+  \tcode{allocation_result<X::pointer>\{ptr, count\}}
+  where \tcode{ptr} is memory allocated for an array of \tcode{count} \tcode{T}
+  and such an object is created but array elements are not constructed,
+  such that $\tcode{count} >= \tcode{n}$.
+  \tcode{allocate_at_least} may throw an appropriate exception.
+  See Note C, below. &
+  See Note D, below. \\ \rowsep
+
 \tcode{a.deallocate(p,n)}   &
   (not used)                &
-  \expects \tcode{p} is a value returned by an earlier call
-  to \tcode{allocate} that has not been invalidated by
-  an intervening call to \tcode{deallocate}. \tcode{n}
-  matches the value passed to \tcode{allocate} to obtain this memory.\br
+  \expects
+  \begin{itemize}
+  \item
+  If \tcode{p} is memory
+  that was obtained by a call to \tcode{a.allocate_at_least},
+  let \tcode{ret} be the value returned and
+  \tcode{req} be the value passed as the first argument of that call.
+  \tcode{p} is equal to \tcode{ret.ptr} and
+  \tcode{n} is a value such that
+  $\tcode{req} <= \tcode{n} <= \tcode{ret.count}$.
+  \item
+  Otherwise, \tcode{p} is a value obtained from \tcode{allocate}.
+  \tcode{n} equals the value passed as the first argument
+  to the invocation of \tcode{allocate} which returned \tcode{p}.
+  \end{itemize}
+  \tcode{p} has not been invalidated by
+  an intervening call to \tcode{deallocate}.\br
   \throws Nothing.          &  \\ \rowsep
 
 \tcode{a.max_size()}        &
@@ -2046,6 +2068,17 @@
 lvalues of type \tcode{X} shall be swappable\iref{swappable.requirements}
 and the \tcode{swap} operation shall not throw exceptions.
 
+\pnum
+Note C:
+If \tcode{n == 0}, the return value is unspecified.
+
+\pnum
+Note D:
+An allocator need not support \tcode{allocate_at_least},
+but no default is provided in \tcode{allocator_traits}.
+If an allocator has an \tcode{allocate_at_least} member,
+it shall satisify the requirements.
+
 \pnum
 An allocator type \tcode{X} shall meet the
 \oldconcept{CopyConstructible} requirements (\tref{cpp17.copyconstructible}).

source/support.tex

@@ -553,6 +553,7 @@
 
 \begin{codeblock}
 #define @\defnlibxname{cpp_lib_addressof_constexpr}@               201603L // also in \libheader{memory}
+#define @\defnlibxname{cpp_lib_allocate_at_least}@                 202106L // also in \libheader{memory}
 #define @\defnlibxname{cpp_lib_allocator_traits_is_always_equal}@  201411L
   // also in \libheader{memory}, \libheader{scoped_allocator}, \libheader{string}, \libheader{deque}, \libheader{forward_list}, \libheader{list}, \libheader{vector},
   // \libheader{map}, \libheader{set}, \libheader{unordered_map}, \libheader{unordered_set}

source/utilities.tex

@@ -6885,6 +6885,16 @@
   // \ref{allocator.traits}, allocator traits
   template<class Alloc> struct allocator_traits;
 
+  template<class Pointer>
+  struct allocation_result {
+    Pointer ptr;
+    size_t count;
+  };
+
+  template<class Allocator>
+    [[nodiscard] constexpr allocation_result<typename allocator_traits<Allocator>::pointer>
+      allocate_at_least(Allocator& a, size_t n);
+
   // \ref{default.allocator}, the default allocator
   template<class T> class allocator;
   template<class T, class U>
@@ -8254,6 +8264,26 @@
 well-formed; otherwise, \tcode{rhs}.
 \end{itemdescr}
 
+\rSec3[allocator.traits.other]{Other}
+
+\pnum
+The class template \tcode{allocation_result} has
+the template parameters, data members, and special members specified above.
+It has no base classes or members other than those specified.
+
+\begin{itemdecl}
+template<class Allocator>
+[[nodiscard]] constexpr allocation_result<typename allocator_traits<Allocator>::pointer>
+  allocate_at_least(Allocator& a, size_t n);
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\returns
+\tcode{a.allocate_at_least(n)} if that expression is well-formed;
+otherwise, \tcode{\{a.allocate(n), n\}}.
+\end{itemdescr}
+
 \rSec2[default.allocator]{The default allocator}
 
 \rSec3[default.allocator.general]{General}
@@ -8285,6 +8315,7 @@
     constexpr allocator& operator=(const allocator&) = default;
 
     [[nodiscard]] constexpr T* allocate(size_t n);
+    [[nodiscard]] constexpr allocation_result<T*> allocate_at_least(size_t n);
     constexpr void deallocate(T* p, size_t n);
   };
 }
@@ -8333,6 +8364,37 @@
 but not that of any of the array elements.
 \end{itemdescr}
 
+\indexlibrarymember{allocate_at_least}{allocator}%
+\begin{itemdecl}
+[[nodiscard]] constexpr allocation_result<T*> allocate_at_least(size_t n);
+\end{itemdecl}
+
+\begin{itemdescr}
+\pnum
+\mandates
+\tcode{T} is not an incomplete type\iref{basic.types}.
+
+\pnum
+\returns
+\tcode{allocation_result<T*>\{ptr, count\}},
+where \tcode{ptr} is a pointer to
+the initial element of an array of \tcode{count} \tcode{T} and
+$\tcode{count} >= \tcode{n}$.
+
+\pnum
+\throws
+\tcode{bad_array_new_length}
+if $\tcode{numeric_limits<size_t>::max() / sizeof(T)} < \tcode{n}$,
+or \tcode{bad_alloc} if the storage cannot be obtained.
+
+\pnum
+\remarks
+The storage for the array is obtained by calling \tcode{::operator new},
+but it is unspecified when or how often this function is called.
+This function starts the lifetime of the array object,
+but not that of any of the array elements.
+\end{itemdescr}
+
 \indexlibrarymember{deallocate}{allocator}%
 \begin{itemdecl}
 constexpr void deallocate(T* p, size_t n);
@@ -8341,9 +8403,18 @@
 \begin{itemdescr}
 \pnum
 \expects
-\tcode{p} is a pointer value obtained from \tcode{allocate()}.
+\begin{itemize}
+\item
+If \tcode{p} is memory that was obtained by a call to \tcode{allocate_at_least},
+let \tcode{ret} be the value returned and
+\tcode{req} be the value passed as the first argument to that call.
+\tcode{p} is equal to \tcode{ret.ptr} and
+\tcode{n} is a value such that $\tcode{req} <= \tcode{n} <= \tcode{ret.count}$.
+\item
+Otherwise, \tcode{p} is a pointer value obtained from \tcode{allocate}.
 \tcode{n} equals the value passed as the first argument
-to the invocation of allocate which returned \tcode{p}.
+to the invocation of \tcode{allocate} which returned \tcode{p}.
+\end{itemize}
 
 \pnum
 \effects