api.tex

\newpage
\abschnitt{Wording}\label{api}

This wording is relative to N4981.\cite{Standard}

\zs{Append to \stdsection{3.6}{defns.block} as indicated:}

\add{\tsnoten{1 to entry}{Unless stated otherwise, blocking blocks the current
thread.}}

\zs{Modify \stdsection{4.1.2}{intro.abstract} paragraph 7.3 as indicated:}

\begin{description}
    \item[---] The input and output dynamics of interactive devices shall take
               place in such a fashion that prompting output is actually
               delivered before \replace{a program}{an input operation} waits
               for input. What constitutes an interactive device is
               implementation-defined.
\end{description}

\zs{Modify \stdsection{6.9.2.1}{intro.multithread.general} paragraph 1 as indicated:}

A \emph{thread of execution} (also known as a \emph{thread}) is
\replace{a single flow of control}{the primary execution agent}\\
\add{\xref{thread.req.lockable.general}}
within a program\delete{, including the initial invocation of a specific top-level
function, and}\\
\replace{recursively including every function invocation subsequently
executed by the thread}{. When the host environment first}\\
\add{enters a program, it provides a default thread to perform the program's
execution steps}.

\add{When a thread is created, it runs a default fiber ([intro.fibers]).}

\zs{Insert before \stdsection{6.9.3}{basic.start} and renumber existing 6.9.3 to 6.9.4:}

\setcounter{section}{6}
\setcounter{subsection}{9}
\setcounter{subsubsection}{2}
\setcounter{secnumdepth}{4}
\cbstart

\rSec3[intro.fibers]{Fibers and Threads}

1 A \emph{fiber} is a single flow of control within a program, including the
initial invocation of a specific top-level function, and recursively including
every function invocation subsequently executed by the fiber. The execution
steps of a fiber are performed by a thread.

\tsnote{``Flow of control'' here refers to state necessary to program
execution, for example the contents of a processor's registers including its
instruction pointer, and the invocation sequence \xref{stacktrace.general} of
functions that have been entered but have not yet returned.}

2 A thread is always running exactly one fiber. Member functions of \fiber
([fiber.context.class]) can direct the calling thread to \emph{suspend} the
running fiber and \emph{resume} a designated other fiber. This transition from
one fiber to another is a \emph{context switch}.

3 An \emph{implicit fiber} is the default fiber on any thread. All other
fibers are \emph{explicit fibers.}

4 An explicit fiber is created using \fiber. Instantiating \fiber \emph{prepares} a
fiber, which can consume resources. A fiber can thus be in one of three
states: prepared, running or suspended.

5 When a thread first enters a prepared fiber, that thread becomes the
fiber's \emph{owning thread.} The owning thread never changes.
\tsnote{A thread is the owning thread of its default fiber.}
\tsnote{If a thread resumes a fiber owned by another thread, the behaviour is
undefined.}
\cbend

\zs{Modify \stdsection{14.2}{except.throw} paragraph 2 as indicated:}

When an exception is thrown, control is transferred to the nearest handler
with a matching type \xref{except.handle}; ``nearest'' means the handler for
which the \nt{stmt.block}{compound-statement} or
\nt{class.base.init}{ctor-initializer} following the \cpp{try} keyword was
most recently entered by the \replace{thread of control}{running fiber} and
not yet exited.

\zs{Modify \stdsection{14.2}{except.throw} paragraph 4 Note 3 as indicated:}

\tsnoten{3}{A thrown exception does not propagate to other
\replace{threads}{fibers} unless caught, stored, and rethrown using
appropriate library functions; see \stdclause{propagation} and \stdclause{futures}.}

\zs{Modify \stdsection{14.4}{except.handle} paragraph 6 as indicated:}

If no match is found among the handlers for a try block, the search for a
matching handler continues in a dynamically surrounding try block of the same
\replace{thread}{fiber}.

\zs{Modify \stdsection{14.4}{except.handle} paragraph 8 as indicated:}

8 The exception with the most recently activated handler
\add{in the running fiber ([intro.fibers])} that is still active is called the
\emph{currently handled exception}.

\zs{Modify \stdsection{14.6.3}{except.uncaught} paragraph 1 as indicated:}

... The function \stdterm{\cpp{std::uncaught\_exceptions}}{uncaught.exceptions}
returns the number of uncaught exceptions in the
\replace{current thread}{running fiber ([intro.fibers])}.

\zs{Insert new final subclause in clause 33 \stdclause{thread} as indicated:}

\setcounter{section}{33}
\setcounter{subsection}{11}
\setcounter{secnumdepth}{4}

\cbstart

\rSec2[fiber.context]{fiber\_context}

\rSec3[fiber.context.overview]{Overview}

1 A \fiber object is either \emph{empty} or \emph{non-empty}. A
default-constructed or moved-from \fiber is empty. Otherwise, a \fiber is
non-empty, and represents either a prepared or a suspended fiber.

2 An explicit fiber is prepared by passing an \emph{\entryfn} to \fiber's
constructor. At the first call to one of the \anyresume member functions,
that \entryfn is entered, and the fiber is running.

3 Every call to one of the \anyresume member functions on an accessible
non-empty \fiber object performs a context switch.
\begin{itemize}
    \item suspends the running fiber, making it the \emph{previous fiber}
    \item resumes \thisfiber, which was either prepared or suspended, making
          it the running fiber.
\end{itemize}
In addition, returning a non-empty \fiber from a fiber's \entryfn:
\begin{itemize}
    \item terminates the running fiber
    \item resumes \thefiber{the returned \fiber}.
\end{itemize}

4 When a prepared fiber is first entered, a synthesized non-empty \fiber
object representing the previous fiber is passed as a parameter to
its \entryfn. When a suspended fiber is resumed, a synthesized \fiber object
representing the previous fiber is returned from the relevant \anyresume
member function.
\tsnote{The synthesized \fiber object received in either of those ways might
represent either an explicit fiber or an implicit fiber.}

%% \rSec3[fiber.context.toplevel]{Implicit Top-Level Function}

%% On every explicit fiber, the behaviour is equivalent to calling the \entryfn
%% passed to \fiber's constructor from an implicit top-level function.
%% If the fiber is later
%% unwound, this conceptual top-level stack frame serves as delimiter: this point
%% is where unwinding stops.

5 When a running fiber returns a \fiber from its \entryfn, thus resuming the
designated fiber, the synthesized \fiber passed into the resumed fiber is
empty.

6 If a fiber's \entryfn returns an empty \fiber object, \cpp{std::terminate} is called.
If a fiber's \entryfn exits via an exception, \cpp{std::terminate} is called.

7 Regardless of the number of \fiber objects in the program, exactly one of them
represents each prepared or suspended fiber. No \fiber object represents a running fiber.

8 A \fiber object can optionally be constructed by passing an explicit
\cpp{span<byte>} in which to track the fiber's
\stdterm{invocation sequence}{stacktrace.general}. If at any time during the
life of a fiber the data storage required to track its invocation sequence
exceeds the \cpp{size()} of that \cpp{span<byte>}, the behaviour is undefined.

%% Returning a \fiber object from the explicit fiber's \entryfn is equivalent
%% to returning control to the implicit top-level function.
%% Similarly,
%% when \unwindfib unwinds a fiber stack, it conceptually returns the \fiber
%% object it was passed to the implicit top-level function. Either way, the
%% The
%% conceptual implicit top-level function is responsible for deallocating the
%% explicit fiber's stack memory on return from the \entryfn.
%% 
%% Similarly, on every implicit fiber, the behaviour is equivalent to passing control through an
%% implicit top-level function above \justmain and above the \entryfn for
%% each \thread.
%% The conceptual stack frame for this implicit top-level function delimits
%% stack unwinding for each of these stacks. If the fiber stack is unwound,
%% control is conceptually returned to this implicit top-level function.
%% The conceptual top-level
%% function for an implicit fiber does not deallocate the fiber's stack memory,
%% since the host environment will do that.

%% \begin{itemize}
%%     \item
%%     \item If an empty \fiber object is returned to the conceptual top-level
%%     function for an explicit fiber, the calling thread is terminated.
%%     \item If an empty \fiber object is returned to the conceptual top-level
%%     function for the default fiber of an explicit thread, that thread is
%%     terminated.
%%     \item If an empty \fiber object is returned to the conceptual top-level
%%     function above \justmain, the process is terminated.
%% \end{itemize}

%--------------------------------- synopsis ----------------------------------
\rSec3[fiber.context.syn]{Header <fiber\_context> synopsis}

\cppf{synopsis}

%--------------------------------- class def ---------------------------------
\rSec3[fiber.context.class]{Class fiber\_context}

\cppf{fiber}

\newcommand{\state}{\cpp{state}}

\rSec4[fiber.context.cons]{Constructors, move and assignment}

%---------------------------- implicit stack ctor ----------------------------
\mbrhdr{template<class F> explicit fiber\_context(F\&\& entry)}

1 \constraints
\begin{description}
    \item[---] \cpp{remove\_cvref\_t<F>} is not the same type as \fiber.
\end{description}

2 \mandates
\begin{description}
    \item[---] \cpp{is\_constructible\_v<decay\_t<F>, F>} is \true.
    \item[---] \cpp{is\_invocable\_r\_v<fiber\_context, decay\_t<F>,
               fiber\_context&&>} is \true.
\end{description}

3 \effects
\begin{description}
    \item[---] Let \cpp{entry\_copy} be an object of
               type \cpp{decay\_t<F>} direct-non-list-initialized
               with \cpp{std::forward<F>(entry)}. 
    \item[---] Initializes \cpp{state} to prepare a fiber that will, when
               first resumed, enter \cpp{entry\_copy}.
               \tsnote{\cpp{entry\_copy} is not a member of \fiber because it
               is destroyed on fiber termination, not when a \fiber object is
               destroyed. Storage for \cpp{entry\_copy} is associated
               with \cpp{state}.}
    \item[---] Any necessary resources are created. \tsnote{This includes
               storage for the new fiber's invocation sequence.}
    \item[---] The prepared fiber has no owning thread.
\end{description}

4 \postcond
\emptyfn is \false.

5 \except
\begin{description}
    \item[---] \cpp{bad\_alloc} if unable to allocate storage while preparing
               the new fiber.
    \item[---] \cpp{system\_error} if unable to prepare the new fiber for any
               other reason.
    \item[---] Any exception from initialization of \cpp{entry\_copy}.
\end{description}

6 \errors
\cpp{resource\_unavailable\_try\_again} -- the system lacked the necessary resources to prepare another fiber.

%---------------------------- explicit stack ctor ----------------------------
\mbrhdr{template<class F, class D> fiber\_context(F\&\& entry, span<byte> stack, D\&\& deleter)}

1 \mandates
\begin{description}
    \item[---] \cpp{is\_constructible\_v<decay\_t<F>, F>} is \true.
    \item[---] \cpp{is\_constructible\_v<decay\_t<D>, D>} is \true.
    \item[---] \cpp{is\_invocable\_r\_v<fiber\_context, decay\_t<F>,
               fiber\_context&&>} is \true.
    \item[---] \cpp{is\_invocable\_v<decay\_t<D>, span<byte>>} is \true.
\end{description}

2 \precond
\begin{description}
    \item[---] \cpp{decay\_t<D>} meets the \emph{Cpp17MoveConstructible} requirements.
    \item[---] \cpp{invoke(deleter, stack)} does not throw an exception.
\end{description}

3 \effects
\begin{description}
    \item[---] Let \cpp{entry\_copy} be an object of
               type \cpp{decay\_t<F>} direct-non-list-initialized
               with \cpp{std::forward<F>(entry)}. 
    \item[---] Let \cpp{stack\_copy} be a copy of \cpp{stack}.
               \tsnote{It might be advantageous to obtain from the host
               environment a memory block with a read-only guard page to trap
               stack overflow.}
    \item[---] Let \cpp{deleter\_copy} be an object of
               type \cpp{decay\_t<D>} direct-non-list-initialized
               with \cpp{std::forward<F>(deleter)}. 
    \item[---] Initializes \cpp{state} to prepare a fiber that will, when
               first resumed, enter \cpp{entry\_copy}.
               \tsnote{\cpp{entry\_copy}, \cpp{stack\_copy} and
               \cpp{deleter\_copy} are not members of \fiber because they 
               are destroyed on fiber termination, not when a \fiber object is
               destroyed. Storage for \cpp{entry\_copy}, \cpp{stack\_copy} and
               \cpp{deleter\_copy} is associated with \cpp{state}.}
    \item[---] Any necessary resources are created.
    \item[---] The prepared fiber has no owning thread.
\end{description}

4 \postcond
\emptyfn is \false.

5 \except
\begin{description}
    \item[---] \cpp{invalid\_argument} if \cpp{stack.data()} fails to meet
               implementation-defined alignment requirements.
    \item[---] \cpp{length\_error} if \cpp{stack.size()} is less than the
               implementation-defined minimum length.
    \item[---] \cpp{system\_error} if unable to prepare the new fiber.
    \item[---] Any exception from initialization of \cpp{entry\_copy}.
    \item[---] Any exception from initialization of \cpp{deleter\_copy}.
\end{description}

6 \errors
\cpp{resource\_unavailable\_try\_again} -- the system lacked the necessary resources to prepare another fiber.

%--------------------------------- move ctor ---------------------------------
\mbrhdr{fiber\_context(fiber\_context\&\& other) noexcept}

1 \effects
Initializes \cpp{state} with \cpp{exchange(other.state, nullptr)}.

%----------------------------------- dtor ------------------------------------
\mbrhdr{\cpp{\~fiber\_context()}}

1 \effects
If \emptyfn is \false, \cpp{terminate} is invoked \xref{except.terminate}.

%------------------------------ move assignment ------------------------------
\mbrhdr{fiber\_context\& operator=(fiber\_context\&\& other) noexcept}

1 \effects
\begin{description}
    \item[---] If \emptyfn is \false, \cpp{terminate} is invoked \xref{except.terminate}.
    \item[---] Equivalent to: \cpp{this->state = exchange(other.state, nullptr)}.
\end{description}

2 \returns
\this

\rSec4[fiber.context.mem]{Members}
%-------------------------------- resume_with --------------------------------
\mbrhdr{template<class Fn> fiber\_context resume\_with(Fn\&\& fn) \&\&}

The operation of \resumewith involves at least two and possibly three fibers.
Within [fiber.context.mem], for exposition only:

\begin{itemize}
    \item Entering \resumewith performs a context switch.
    \item The \emph{calling fiber} is the fiber calling \resumewith.
    \item The \emph{target fiber} is \thefiber{\state}.
    \item \resumewith synthesizes a \fiber object representing the calling
          fiber. Let \cpp{caller} be that synthesized \fiber object.
    \item Because \resumewith suspends the calling fiber, return
          from \resumewith necessarily requires some other fiber to perform a
          subsequent context switch back to the original calling fiber.
          When \resumewith returns, that other fiber is the previous fiber.
          \tsnote{The previous fiber can be other than the target fiber.}
    \item Let \cpp{previous} be the synthesized \fiber object representing the
          suspended previous fiber.
\end{itemize}

At entry to \resumewith, the target fiber can either be in the prepared state
(not yet entered) or in the suspended state (waiting to return from \resumewith).

\begin{description}
    \item[---]
          If the running fiber is suspended, that implies that at some earlier
          time, it called \resumewith[other], where \cpp{other} was some
          non-empty \fiber object. In that case, let
          exposition-only \emph{internal-resume(\cpp{before})},
          where \cpp{before} is a \fiber object, denote the following sequence
          of steps:
        \begin{itemize}
            \item Return \cpp{before} from \resumewith[other].
        \end{itemize}   
    \item[---] Otherwise, let \emph{internal-resume(\cpp{before})}
          denote the following sequence of steps:
        \begin{itemize}
            \item Execute
                  \cpp{invoke\_r<fiber\_context>(entry\_copy, std::move(before))}
                  and let \cpp{successor} be the resulting \fiber, then
            \item destroy \cpp{entry\_copy}, then
            \item if \cpp{stack\_copy} and \cpp{deleter\_copy} exist:
                \begin{itemize}
                    \item execute \cpp{invoke(deleter\_copy, stack\_copy)}, then
                    \item destroy \cpp{deleter\_copy}, then
                \end{itemize}
            \item exit the running fiber, then
            \item reclaim implementation-provided resources, then
            \item direct the current thread to resume \thefiber{\cpp{successor}}, then
            \item execute \emph{internal-resume(\cpp{fiber\_context()})}.
        \end{itemize}
\end{description}

1 \mandates
\cpp{is\_invocable\_r\_v<fiber\_context, decay\_t<Fn>, fiber\_context&&>} is \true.

2 \precond
\canresume is \true.

3 \effects
\begin{description}
    \item[---] Resets \state so that \emptyfn is \true.
    \item[---] Directs the current thread to suspend the calling fiber and resume
               the target fiber.
    \item[---] Associates the calling thread as the target fiber's owning thread.
    \item[---] Evaluates \cpp{invoke\_r(std::forward<Fn>(fn), std::move(caller))}.
               Let \cpp{returned} be the \fiber object returned by \cpp{fn}.
               \tsnote{\cpp{returned} can be other than \cpp{caller}.
               \cpp{returned} can be empty.}
    \item[---] Executes \emph{internal-resume(\cpp{returned})}.
\end{description}

4 \returns

\begin{description}
    \item[---] If the previous fiber resumed the calling fiber by returning
          a \fiber object representing the calling fiber, an empty \fiber.
    \item[---] If the previous fiber resumed the calling fiber by
          calling \cpp{resume\_with(somefn)}, the \fiber object returned
          by \cpp{invoke\_r<fiber\_context>(somefn, std::move(previous))}.
\end{description}

5 \except

If the previous fiber resumed the calling fiber by calling \cpp{resume\_with(somefn)}:
\begin{itemize}
    \item Any exception thrown by \cpp{invoke\_r<fiber\_context>(somefn,
          std::move(previous))}.
\end{itemize}

\tsnote{\resumewith throws nothing before suspending the calling fiber and
ensuring \emptyfn is \true.} 

6 \postcond
\emptyfn is \true.

\tsnote{Because \anyresume empties the object on which it is called, these
member functions are rvalue-reference qualified.}

%---------------------------------- resume -----------------------------------
\mbrhdr{fiber\_context resume() \&\&}

1 \effects
Equivalent to:\\
\cpp{return resume\_with(identity());}

%-------------------------------- can_resume ---------------------------------
\mbrhdr{bool can\_resume() noexcept}

1 \returns
\begin{description}
    \item[---] \false if \emptyfn is \true
    \item[---] \true if \thisfiber is in the prepared state (has no owning thread)
    \item[---] \true if \currthread is \ownthread
    \item[---] \false otherwise.
\end{description}

\red{\EnterBlock{Editorial note} \canresume is intentionally not
marked \cpp{const}. \ExitBlock{editorial note}}

%----------------------------------- empty -----------------------------------
\mbrhdr{bool empty() const noexcept}

1 \effects
Equivalent to: \cpp{return (\! state);}

%------------------------------- operator bool -------------------------------
\mbrhdr{explicit operator bool() const noexcept}

1 \effects
Equivalent to: \cpp{return (\! empty());}

%----------------------------------- swap ------------------------------------
\mbrhdr{void swap(fiber\_context\& other) noexcept}

1 \effects
Equivalent to: \cpp{swap(this->state, other.state)}.

\rSec4[fiber.context.special]{Specialized algorithms}
\mbrhdr{friend void swap(fiber\_context\& lhs, fiber\_context\& rhs) noexcept}

1 \effects
Equivalent to: \cpp{lhs.swap(rhs)}.


%% \rSec3[fiber.context.unwinding]{Function unwind\_fiber()}
%% 
%% \mbrhdr{[[ noreturn ]] void unwind\_fiber(fiber\_context\&\& other)}
%% 
%% 1 \effects
%% terminate the running fiber.
%% 
%% 2 \remarks
%% \begin{description}
%%     \item[---] The underlying Unwinding facility (for instance the unwind facility
%%                described in \emph{System V ABI for AMD64}) unwinds the stack
%%                to the implicit top-level stack frame and terminates the
%%                running fiber as described above.
%%     \item[---] Unwinding the fiber's stack causes its stack variables to be
%%                destroyed.
%%     \item[---] During this specific stack unwinding, 
%% %% only \catchall clauses are executed. No other
%%                no \cpp{catch} clauses are executed, not even \catchall.
%%     \item[---] Once the running fiber has been fully unwound, \cpp{other} is
%%                returned to the fiber's conceptual top-level function as
%%                described in \nameref{fiber-context.toplevel}.
%% %%  \item[---] Unwinding the fiber's stack causes relevant \catchall
%% %%             clauses to be executed.
%% %%  \item[---] During this specific stack unwinding, a \catchall
%% %%             clause that does not execute a \cpp{throw;} statement behaves
%% %%             as if it ended with a \cpp{throw;} statement.
%% %%  \item[---] During this specific stack unwinding, if a \catchall
%% %%             clause attempts to throw any C++ exception, the
%% %%             behaviour is undefined.
%% \end{description}
%% 
%% 3 \returns
%% \begin{description}
%%     \item[---] None: \unwindfib does not return
%% \end{description}
%% 
%% 4 \except
%% \begin{description}
%%     \item[---] None catchable by C++
%% \end{description}

\cbend

\zs{Modify \stdsection{19.6.1}{stacktrace.general} as indicated:}

1 Subclause \stdclause{stacktrace} describes components that C++ programs may use to
store the stacktrace of the \delete{current thread of}\\
\replace{execution}{running fiber ([intro.fibers])}
and query information about the stored stacktrace at runtime.

2 The \emph{invocation sequence} of the current evaluation $x_0$
in the \replace{current thread of execution}{running fiber} is a sequence
($x_0$,...,$x_n$) of evaluations such that, for $i \geq 0$,
$x_i$ is within the function invocation $x_{i+1}$ \xref{intro.execution}.

\abschnitt{Header File}

\zs{Add a new header file to Table 24 in \stdsection{16.4.2.3}{headers}:}

\add{\cpp{<fiber\_context>}}

\abschnitt{Feature-test Macro}
\zs{Add a new feature-test macro to \stdsection{17.3.2}{version.syn} as indicated:}

\add{\cpp{#define \__cpp\_lib\_fiber\_context 202XXXL // also in <fiber\_context>}}