diff --git a/source/algorithms.tex b/source/algorithms.tex index 9201d5e62a..4155e2cccd 100644 --- a/source/algorithms.tex +++ b/source/algorithms.tex @@ -1573,8 +1573,10 @@ If \tcode{f} returns a result, the result is ignored. \pnum -\realnotes Does not return a copy of its \tcode{Function} parameter, since +\begin{note} +Does not return a copy of its \tcode{Function} parameter, since parallelization may not permit efficient state accumulation. +\end{note} \end{itemdescr} \indexlibrary{\idxcode{for_each_n}}% @@ -2871,10 +2873,12 @@ applications of the corresponding predicate. \pnum -\realnote each element in the range \range{ret}{last}, where \tcode{ret} is +\begin{note} +Each element in the range \range{ret}{last}, where \tcode{ret} is the returned value, has a valid but unspecified state, because the algorithms can eliminate elements by moving from elements that were originally in that range. +\end{note} \end{itemdescr} \indexlibrary{\idxcode{remove_copy}}% diff --git a/source/atomics.tex b/source/atomics.tex index 1a30f6eb4f..fc872f3fbc 100644 --- a/source/atomics.tex +++ b/source/atomics.tex @@ -1497,11 +1497,11 @@ signal handler executed in the same thread. \pnum -\realnote \tcode{atomic_signal_fence} can be used to specify the order in which actions +\begin{note} +\tcode{atomic_signal_fence} can be used to specify the order in which actions performed by the thread become visible to the signal handler. - -\pnum -\realnote compiler optimizations and reorderings of loads and stores are inhibited in +Compiler optimizations and reorderings of loads and stores are inhibited in the same way as with \tcode{atomic_thread_fence}, but the hardware fence instructions that \tcode{atomic_thread_fence} would have inserted are not emitted. +\end{note} \end{itemdescr} diff --git a/source/containers.tex b/source/containers.tex index 1a4d2e1c8f..7eb0b10407 100644 --- a/source/containers.tex +++ b/source/containers.tex @@ -272,13 +272,14 @@ \end{libreqtab5} -Notes: the algorithm -\tcode{equal()} +\begin{note} +The algorithm \tcode{equal()} is defined in Clause~\ref{algorithms}. Those entries marked ``(Note A)'' or ``(Note B)'' have linear complexity for \tcode{array} and have constant complexity for all other standard containers. - +\end{note} + \pnum The member function \tcode{size()} returns the number of elements in the container. The number of elements is defined by the rules of @@ -3236,9 +3237,11 @@ \throws Nothing unless one of the element-wise swap calls throws an exception. \pnum -\realnote Unlike the \tcode{swap} function for other containers, \tcode{array::swap} +\begin{note} +Unlike the \tcode{swap} function for other containers, \tcode{array::swap} takes linear time, may exit via an exception, and does not cause iterators to become associated with the other container. +\end{note} \end{itemdescr} \rSec3[array.zero]{Zero sized arrays} diff --git a/source/iostreams.tex b/source/iostreams.tex index 5d366bcbb5..ca9889175a 100644 --- a/source/iostreams.tex +++ b/source/iostreams.tex @@ -2083,9 +2083,11 @@ \end{enumerate} \pnum -\realnote The second pass through the callback pairs permits a copied \tcode{pword} +\begin{note} +The second pass through the callback pairs permits a copied \tcode{pword} value to be zeroed, or to have its referent deep copied or reference counted, or to have other special action taken. +\end{note} \pnum \postconditions diff --git a/source/lib-intro.tex b/source/lib-intro.tex index 97b6e31bb1..a127c20b3a 100644 --- a/source/lib-intro.tex +++ b/source/lib-intro.tex @@ -488,7 +488,6 @@ \item \complexity the time and/or space complexity of the function \item \remarks additional semantic constraints on the function \item \errors the error conditions for error codes reported by the function -\item \realnotes non-normative comments about the function \end{itemize} \pnum @@ -497,7 +496,7 @@ interpreted as follows. If \tcode{F}'s semantics specifies a \requires element, then that requirement is logically imposed prior to the \techterm{equivalent-to} semantics. Next, the semantics of the code sequence are determined by the \requires, \effects, -\sync, \postconditions, \returns, \throws, \complexity, \remarks, \errors, and \realnotes +\sync, \postconditions, \returns, \throws, \complexity, \remarks, and \errors specified for the function invocations contained in the code sequence. The value returned from \tcode{F} is specified by \tcode{F}'s \returns element, or if \tcode{F} has no \returns element, a non-\tcode{void} return from \tcode{F} is specified by the diff --git a/source/macros.tex b/source/macros.tex index 70593faf41..bb3b91bd6a 100644 --- a/source/macros.tex +++ b/source/macros.tex @@ -217,8 +217,6 @@ \newcommand{\default}{\Fundesc{Default behavior}} \newcommand{\complexity}{\Fundesc{Complexity}} \newcommand{\remarks}{\Fundesc{Remarks}} -\newcommand{\realnote}{\Fundesc{Note}} -\newcommand{\realnotes}{\Fundesc{Notes}} \newcommand{\errors}{\Fundesc{Error conditions}} \newcommand{\sync}{\Fundesc{Synchronization}} \newcommand{\implimits}{\Fundesc{Implementation limits}} diff --git a/source/numerics.tex b/source/numerics.tex index bf12b26154..2d9ab9647f 100644 --- a/source/numerics.tex +++ b/source/numerics.tex @@ -912,12 +912,13 @@ \end{codeblock} \pnum -\realnote In a locale in which comma is used as a decimal point character, the +\begin{note} +In a locale in which comma is used as a decimal point character, the use of comma as a field separator can be ambiguous. Inserting \tcode{showpoint} into the output stream forces all outputs to show an explicit decimal point character; as a result, all inserted sequences of complex numbers can be extracted unambiguously. - +\end{note} \end{itemdescr} \rSec2[complex.value.ops]{\tcode{complex} value operations} @@ -8938,11 +8939,12 @@ \bigoh{\tcode{last - first}} applications of \tcode{binary_op}. \pnum -\realnotes +\begin{note} The difference between \tcode{reduce} and \tcode{accumulate} is that \tcode{reduce} applies \tcode{binary_op} in an unspecified order, which yields a nondeterministic result for non-associative or non-commutative \tcode{binary_op} such as floating-point addition. +\end{note} \end{itemdescr} \rSec2[transform.reduce]{Transform reduce} @@ -8975,8 +8977,9 @@ \tcode{binary_op}. \pnum -\realnotes +\begin{note} \tcode{transform_reduce} does not apply \tcode{unary_op} to \tcode{init}. +\end{note} \end{itemdescr} \rSec2[inner.product]{Inner product} @@ -9174,11 +9177,12 @@ \tcode{result} may be equal to \tcode{first}. \pnum -\realnotes +\begin{note} The difference between \tcode{exclusive_scan} and \tcode{inclusive_scan} is that \tcode{exclusive_scan} excludes the \tcode{i}th input element from the \tcode{i}th sum. If \tcode{binary_op} is not mathematically associative, the behavior of \tcode{exclusive_scan} may be nondeterministic. +\end{note} \end{itemdescr} \rSec2[inclusive.scan]{Inclusive scan} @@ -9272,11 +9276,12 @@ \tcode{result} may be equal to \tcode{first}. \pnum -\realnotes +\begin{note} The difference between \tcode{exclusive_scan} and \tcode{inclusive_scan} is that \tcode{inclusive_scan} includes the \tcode{i}th input element in the \tcode{i}th sum. If \tcode{binary_op} is not mathematically associative, the behavior of \tcode{inclusive_scan} may be nondeterministic. +\end{note} \end{itemdescr} \rSec2[transform.exclusive.scan]{Transform exclusive scan} @@ -9328,13 +9333,14 @@ \tcode{result} may be equal to \tcode{first}. \pnum -\realnotes +\begin{note} The difference between \tcode{transform_exclusive_scan} and \tcode{transform_inclusive_scan} is that \tcode{transform_exclusive_scan} excludes the ith input element from the ith sum. If \tcode{binary_op} is not mathematically associative, the behavior of \tcode{transform_exclusive_scan} may be nondeterministic. \tcode{transform_exclusive_scan} does not apply \tcode{unary_op} to \tcode{init}. +\end{note} \end{itemdescr} \rSec2[transform.inclusive.scan]{Transform inclusive scan} @@ -9408,13 +9414,14 @@ \tcode{result} may be equal to \tcode{first}. \pnum -\realnotes +\begin{note} The difference between \tcode{transform_exclusive_scan} and \tcode{transform_inclusive_scan} is that \tcode{transform_inclusive_scan} includes the ith input element in the ith sum. If \tcode{binary_op} is not mathematically associative, the behavior of \tcode{transform_inclusive_scan} may be nondeterministic. \tcode{transform_inclusive_scan} does not apply \tcode{unary_op} to \tcode{init}. +\end{note} \end{itemdescr} \rSec2[adjacent.difference]{Adjacent difference} diff --git a/source/support.tex b/source/support.tex index b94cd72d21..87aacbba3a 100644 --- a/source/support.tex +++ b/source/support.tex @@ -2530,7 +2530,7 @@ or (possibly cv-qualified) \tcode{void}. \pnum -\realnotes +\begin{note} If a new object is created in storage occupied by an existing object of the same type, a pointer to the original object @@ -2539,6 +2539,7 @@ in the latter cases, this function can be used to obtain a usable pointer to the new object. See~\ref{basic.life}. +\end{note} \pnum \begin{example} diff --git a/source/threads.tex b/source/threads.tex index f7f14c30ac..9e90ed662f 100644 --- a/source/threads.tex +++ b/source/threads.tex @@ -2838,18 +2838,20 @@ all objects with thread storage duration associated with the current thread. \pnum -\realnote The supplied lock will be held until the thread exits, and care +\begin{note} +The supplied lock will be held until the thread exits, and care must be taken to ensure that this does not cause deadlock due to lock ordering issues. After calling \tcode{notify_all_at_thread_exit} it is recommended that the thread should be exited as soon as possible, and that no blocking or time-consuming tasks are run on that thread. \pnum -\realnote It is the user's responsibility to ensure that waiting threads +It is the user's responsibility to ensure that waiting threads do not erroneously assume that the thread has finished if they experience spurious wakeups. This typically requires that the condition being waited for is satisfied while holding the lock on \tcode{lk}, and that this lock is not released and reacquired prior to calling \tcode{notify_all_at_thread_exit}. +\end{note} \end{itemdescr} \rSec2[thread.condition.condvar]{Class \tcode{condition_variable}} @@ -3339,6 +3341,13 @@ \pnum\effects Unblocks all threads that are blocked waiting for \tcode{*this}. \end{itemdescr} +\pnum +\begin{note} +If any of the \tcode{wait} functions exits via an exception, it is +unspecified whether the \tcode{Lock} is held. One can use a \tcode{Lock} type +that allows to query that, such as the \tcode{unique_lock} wrapper. +\end{note} + \indexlibrarymember{wait}{condition_variable_any}% \begin{itemdecl} template @@ -3346,11 +3355,6 @@ \end{itemdecl} \begin{itemdescr} -\pnum -\realnote if any of the \tcode{wait} functions exits via an exception, it is -unspecified whether the \tcode{Lock} is held. One can use a \tcode{Lock} type -that allows to query that, such as the \tcode{unique_lock} wrapper. - \pnum \effects \begin{itemize} @@ -4248,8 +4252,10 @@ \begin{itemdescr} \pnum -\realnote as described above, the template and its two required specializations differ only in +\begin{note} +As described above, the template and its two required specializations differ only in the return type and return value of the member function \tcode{get}. +\end{note} \pnum \effects @@ -4554,13 +4560,15 @@ \begin{itemdescr} \pnum -\realnote as described above, the template and its two required specializations differ only in +\begin{note} +As described above, the template and its two required specializations differ only in the return type and return value of the member function \tcode{get}. \pnum -\realnote access to a value object stored in the shared state is +Access to a value object stored in the shared state is unsynchronized, so programmers should apply only those operations on \tcode{R} that do not introduce a data race~(\ref{intro.multithread}). +\end{note} \pnum \effects \tcode{wait()}{s} until the shared state is ready, then retrieves the diff --git a/source/utilities.tex b/source/utilities.tex index 4c27552b8b..23d1a96b5f 100644 --- a/source/utilities.tex +++ b/source/utilities.tex @@ -2090,9 +2090,11 @@ each group $e_i$ in order. \pnum -\realnote An implementation may support additional types in the parameter +\begin{note} +An implementation may support additional types in the parameter pack \tcode{Tuples} that support the \tcode{tuple}-like protocol, such as \tcode{pair} and \tcode{array}. +\end{note} \end{itemdescr} \rSec3[tuple.apply]{Calling a function with a \tcode{tuple} of arguments} @@ -8765,7 +8767,9 @@ \returns \tcode{get()}. \pnum -\realnote use typically requires that \tcode{T} be a complete type. +\begin{note} +The use of this function typically requires that \tcode{T} be a complete type. +\end{note} \end{itemdescr} \indexlibrarymember{get}{unique_ptr}% @@ -11117,8 +11121,9 @@ Nothing. \pnum -\realnotes +\begin{note} This constructor provides an implicit conversion from \tcode{memory_resource*}. +\end{note} \end{itemdescr} \indexlibrary{\idxcode{polymorphic_allocator}!constructor}% @@ -18120,11 +18125,14 @@ \end{codeblock} \end{itemize} -\realnotes This function does not use any implicit conversions; all conversions +\pnum +\begin{note} +This function does not use any implicit conversions; all conversions are done with \tcode{static_cast}. It avoids multiplications and divisions when it is known at compile time that one or more arguments is 1. Intermediate computations are carried out in the widest representation and only converted to the destination representation at the final step. +\end{note} \end{itemdescr} \indexlibrarymember{floor}{duration}%