history.tex

\abschnitt{Revision History}\label{history}
This document supersedes P0876R17.

\uabschnitt{Changes since P0876R17}

\begin{itemize}
    \item Distinguish between a \emph{prepared} and a \emph{suspended} fiber.
    \item Distinguish the two context switches implied by entry to, and return
          from, \resumewith.
    \item Remove \cpp{current\_exception\_within\_fiber()}, which became moot
          in P0876R17.
\end{itemize}

\uabschnitt{Changes since P0876R16}

\begin{itemize}
    \item Update to reference N4981.
    \item Add \cpp{<fiber\_context>} header file to headers table.
    \item Remove \resumewith ``Case A'' and ``Case B'' in favor of
          nested bullet lists. Fix a bug in definition of internal-resume.
    \item Revert \resumewith\xspace\returns and \except clauses to R15
          structure, eliminating ``Case C'' and ``Case D''.
    \item Use scoped exposition-only terms \emph{calling fiber}, \emph{target
          fiber} and \emph{previous fiber} instead of quoting the phrases.
          Give previous fiber definition its own bullet.
    \item Eliminate \emph{internal-resume} parameter \cpp{after}, also
          definitions of \cpp{after\_entry\_copy}, \cpp{after\_stack\_copy}
          and \cpp{after\_deleter\_copy}. Describe \emph{internal-resume} in
          terms of the currently running fiber.
    \item Explicitly state that \emph{internal-resume} is exposition only, and
          italicize references.
    \item Move predicate for first \emph{internal-resume} definition to start
          of bullet text. Don't state the inverse predicate for the second.
    \item Remove one level of bullet list nesting from the
          second \emph{internal-resume} definition. Sequence the bullet list
          by appending ``, then'' after each item.
    \item Per EWG in St. Louis, remove implementation defined meaning
          of \emph{currently handled exception} and \cpp{uncaught\_exceptions}.
          Now both are fiber-specific.
    \item Clarify explicit constructor \except clause.
\end{itemize}

\uabschnitt{Changes since P0876R15}

\begin{itemize}
    \item \null [fiber.context.overview] is now ``Overview'' instead of ``Preamble''.
    \item Make default \fiber constructor \cpp{= default}.
          Remove its section from member descriptions.
    \item In unary constructor, move ``Mandates'' before ``Constraints''. The
          ``Preconditions'' entry is actually a Constraint: move it and remove
          ``Preconditions''.
    \item In span constructor, stated ``Preconditions'' are actually ``Constraints''.
    \item In constructor descriptions, use less precise language about copying
          \cpp{entry}, \cpp{stack} and \cpp{deleter}. Add Note about them not
          being \fiber members. Move mention of stack to a Note.
    \item Rephrase \resumewith Note about emptying its \fiber object to avoid
          the appearance of a normative statement.
    \item Remove mention of ``legacy behaviour'' from
          \cpp{current\_exception\_within\_fiber()}.
    \item Remove mention of ``thread of execution'' from ``abstract,''
          ``control transfer mechanism'' and the section on \exfns.
    \item Simplify definitions of implicit fiber vs. explicit fiber.
    \item Add [intro.fibers] statement that a thread is always running one
          fiber, but can switch between fibers. This replaces the more
          detailed description of what happens when a fiber calls \anyresume.
    \item In [intro.fibers], hoist ``owning thread'' definition to its own
          paragraph 3 and clarify.
    \item Remove assertion that a fiber is an execution agent.
    \item Modify \stdclause{except.throw} paragraphs 2 and 4, and \stdclause{except.handle}
          paragraph 6, to constrain exception propagation to a fiber.
    \item Describe explicit fiber as being ``prepared,'' with a statement that
          it comes into existence on first resumption.
    \item Remove a few stray instances of ``may''.
    \item Move assertion that a received \fiber object could represent either
          an explicit fiber or an implicit fiber to a Note.
    \item Move assertion that no \fiber object represents a running fiber up
          to Overview.
    \item Use \cpp{successor} rather than the more generic \cpp{continuation}
          to reference the \fiber object returned by a terminating fiber.
    \item Remove nesting from \resumewith \except.
    \item Remove Note that the caller of \resumewith can detect whether the
          previous fiber has terminated: not necessarily.
    \item Hoist section on \exfns to have its own table of contents entry.
          Extend with examples of bad behavior when switching out of a catch
          block to a fiber which itself catches some exception before
          switching back to the original fiber.
    \item Remove explicit \cpp{delete} declarations of copy constructor and
          copy assignment: these are implicitly deleted.
    \item Since we want the constructor's \cpp{entry} and \cpp{deleter}
          parameters to support move-only objects,
          remove \emph{Cpp17CopyConstructible} requirements.
    \item For the same reason, state that \cpp{entry\_copy}
          and \cpp{deleter\_copy} are initialized rather than copied.
    \item Therefore ``any exception from initialization of \cpp{entry\_copy}''
          and the same for \cpp{deleter\_copy}.
    \item Remove mention of ``function call stack'' from constructor \except.
    \item \cpp{stack.data()} and \cpp{stack.size()} must meet implementation
          requirements, not the \cpp{span<byte>} itself.
    \item Remove \postcond \cpp{other.empty()} from move constructor and
          move assignment: these are implied by definition.
    \item Move statement about UB from stack overflow to \fiber Overview.
    \item Modify example about early destruction of exceptions to add sequence
          comments, highlight access to a destroyed exception object.
    \item Fix erroneous [fibercontext.mumble] references in class comments.
    \item Add green changebars for entirely new sections.
    \item Remove \cpp{std::} qualification from \cpp{decay\_t} in \effects.
    \item Remove the destructor Note about encouraging a fiber to terminate
          voluntarily.
    \item Clarify that \cpp{current\_exception\_within\_fiber()} is \true if
          \curex reports exceptions ``only'' within the current fiber.
          Remove \cpp{constexpr}: compiler can produce object code that might
          be linked with alternative runtimes.
    \item Remove ``.'' after ``;''.
    \item \resumewith\xspace\mandates\xspace\cpp{is\_invocable\_r<...>} is \true.
          Add periods to \mandates and \precond.
    \item Add \precond to span constructor that \cpp{deleter} must not throw.
          Remove cleanup exceptions from \resumewith \xspace \except. Remove
          ``before this point, no exceptions'' bullet in \effects.\
    \item \resumewith evaluates \cpp{invoke\_r(fn)}. Merge Notes about what
          its \cpp{returned} can be.
    \item Substantially rework \resumewith description. Break out and label
          the four cases: (target not yet entered, target previously
          suspended); (previous exited, previous called \resumewith). Use case
          labels in \effects, \returns and \except. Break out internal-resume
          operation because it's self-referential.
    \item Add span constructor \precond for \cpp{decay\_t<D>}
          meeting \emph{Cpp17MoveConstructible} requirements.
    \item Remove \canresume Note about ``can resume.''
    \item For \resume, use \cpp{std::identity} instead of identity lambda.
\end{itemize}

\uabschnitt{Changes since D0876R15}

\begin{itemize}
    \item Updated to reference N4971.
    \item Inserted a section to clarify relationship between threads and fibers.
    \item Borrowed ``single flow of control'' definition for ``fiber.''
    \item Added Note clarifying ``flow of control'' as state, with reference
    to \stdclause{stacktrace.general}.
    \item Changed stacktrace ``invocation sequence'' to reference ``fiber'' rather
    than ``thread of execution.''
    \item Changed ``thread'' definition to be the execution agent that runs fibers.
    \item Clarified that if a fiber terminates by returning an empty \fiber
          instance, \cpp{std::terminate} is called.
    \item Added \cpp{constexpr fiber\_context::current\_exception\_within\_fiber}.
    \item Removed definition of ``function call stack.''
    \item Removed change to definition of expression evaluation conflict.
    \item Removed Note about the second fiber in the program.
    \item Changed ``\fiber instance'' to ``\fiber object.''
    \item Changed ``method'' to ``member function.''
    \item Removed paragraph numbers from internal cross-references.
    \item Clarified editorial directives amongst not-green new text.
    \item Used ``fiber.context'' in stable labels.
    \item Changed the lone remaining preamble section in [fiber.context] from
    ``Empty vs. Non-Empty'' to ``Preamble.''
    \item Moved to ``Preamble'' the 1:1 relationship between non-empty \fiber
    objects and suspended fibers.
    \item Used ``Effects: Equivalent to \cpp{return <expression>}'' for
    \cpp{empty()} and \cpp{operator bool()}.
    \item Referenced \justmain instead of \main.
\end{itemize}

\uabschnitt{Changes since P0876R14}

\begin{itemize}
    \item Invoked ``blocks with forward progress guarantee delegation'' words
          of power for \resumewith, guaranteeing mutual exclusion.
    \item Fixed Mandates and Throws concerning the entry function and deleter
          passed to the implicit-stack or explicit-stack constructor.
    \item Cleaned up wording around initializing, assigning and testing the
          exposition-only \cpp{state} member.
    \item Dampened the optimism of the proposed feature-test macro.
\end{itemize}

\uabschnitt{Changes since P0876R13}

\begin{itemize}
    \item At LEWG's request, retracted changes to \cpp{uncaught\_exceptions()}
          and \cpp{current\_exception()}, instead clarifying that results may
          reflect exceptions on other fibers running on the current thread.
    \item Updated against draft standard N4958.
    \item Deleted ``User-Mode'' from new section title ``Cooperative Threads''
          and removed the explanatory paragraph.
    \item Removed \cpp{explicit} from the explicit-stack constructor.
    \item Added \cpp{system\_error}: \cpp{resource\_unavailable\_try\_again}
          to the \except clause of the implicit-stack constructor.
    \item Changed \cpp{bad\_alloc}
          to \cpp{system\_error}: \cpp{resource\_unavailable\_try\_again}
          in the \except clause of the explicit-stack constructor.
    \item Stated that the move constructor and move assignment operator empty
          the moved-from \fiber.
    \item Removed the \emptyfn precondition from assignment operator; instead
          added the same \cpp{(\! empty())} effect as for the destructor.
    \item Removed \resumewith references to ``execution context.'' Existing
          section 7.6.1.3 Function call \stdclause{expr.call} makes no mention
          of saving or restoring state.
    \item Removed bullets in \resumewith \returns and \except clauses
          regarding \resume, since they can be inferred from \resumewith and
          the trivial-lambda equivalence described for \resume.
    \item Removed the \remarks about concurrent calls from multiple threads
          from \canresume, leaving in place the editorial note about the
          intentional absence of \cpp{const}.
    \item Changed exposition-only \cpp{state} member from unspecified-type
          to \cpp{void*}.
    \item Sanitized stable names.
    \item Moved feature-test macro to appropriate section.
    \item Cleaned up the header-file synopsis.
    \item Grouped class members with forward references.
    \item Added \cpp{std::swap()} specialization.
    \item Added obtrusive paragraph numbers.
    \item Streamlined single-item dash lists.
    \item Changed \textit{Ensures} to \textit{Postconditions}.
    \item Changed template parameters from \cpp{typename} to \cpp{class}.
    \item Tweaked constructor \precond / \mandates.
    \item Clarified that \cpp{entry\_copy}, \cpp{stack\_copy}
          and \cpp{deleter\_copy} are not intended to be data members
          of \fiber.
    \item Streamlined initialization of these exposition objects.
    \item ``Instantiates a \fiber'' => ``Initializes \cpp{state}''
    \item \emptyfn returns \true => \emptyfn is \true, et al.
    \item Removed explicit-stack constructor \precond for stack size and
          alignment, since \except explicitly specifies exceptions for
          violations.
    \item Rephrased \effects of move constructor.
    \item Extracted ``Let'' statements from \effects to preceding paragraphs.
\end{itemize}

\uabschnitt{Changes since P0876R12}

\begin{itemize}
    \item Proposed that \cpp{uncaught\_exceptions()}
          and \cpp{current\_exception()} be specific to the current thread of
          execution.
    \item Specified that constructors \emph{decay-copy} the \entryfn.
    \item Changed \cpp{span<byte, N>} constructor param to
          simply \cpp{span<byte>}; also accepted deleter function, which it
          must \emph{decay-copy}.
    \item Specified constructor exceptions.
    \item Specified that destroying a non-empty \fiber
          calls \cpp{terminate()}.
    \item Clarified that when \resumewith is called, \emptyfn becomes
          true immediately.
    \item Introduced exposition-only \cpp{fiber\_context::state} member to
          streamline wording.
    \item Removed \cpp{concurrency\_v2} namespace.
    \item Changed ``Equivalent to'' to ``As-if''.
    \item Clarified Preconditions vs. Mandates.
\end{itemize}

\uabschnitt{Changes since P0876R11}

\begin{itemize}
    \item Removed \getsource, \gettoken, \reqstop and
          exposition-only \cpp{ssource} members.
    \item Added a \fiber constructor accepting a caller-provided
          uninitialized memory area for the new fiber's function call stack.
\end{itemize}

Bundling a \cpp{stop\_source} into \fiber presented implementability concerns.
Although each fiber (specifically, its function call stack) is itself a
persistent entity, the \fiber representing that fiber is not: a
new \fiber object is synthesized on every suspension. This
presents a problem: how does the code that suspends a fiber find its
associated \cpp{stop\_source} shared state?

A consumer wishing to pass a \cpp{std::stop\_token} to a new fiber can itself
instantiate \cpp{std::stop\_source}, obtain from it a \cpp{stop\_token} and
bind that \cpp{stop\_token} in a lambda passed to the \fiber
constructor. Accordingly, the \fiber API need not explicitly support that.

\uabschnitt{Changes since P0876R10}

\begin{itemize}
    \item Removed \cpp{cancel()} method and the \cancelfn constructor
          argument. Replaced with the \cpp{std::jthread} stop token handling
          API: \getsource, \gettoken and \reqstop. This simplifies examples by
          eliminating \cpp{launch()} and \cpp{assert\_on\_cancel}.
    \item Added a section exploring the relationship of \fiber to the larger
          C++ ecosystem.
    \item Reordered some sections to make the paper more accessible for new readers.
\end{itemize}

\uabschnitt{Changes since P0876R9}

\begin{itemize}
    \item Removed \xtresume, \xtresumewith, \xtcancel and \canxtresume, along
          with stated support for resuming a suspended fiber on some thread
          other than the one on which it was launched.
\end{itemize}

In Belfast, EWG came down strongly against cross-thread fiber resumption. The
most emphatic objection was that for a function referencing TLS, multiple
compilers cache TLS pointers on the function's stack frame. Resuming a fiber
containing that stack frame on some other thread would cause problems. In the
best case, the resumed function would merely reference TLS belonging to the
wrong thread -- but at some point the original thread will terminate, its TLS
will be destroyed, and the cached pointers will be left dangling.

With \fiber, any opaque function call might possibly suspend -- but
invalidating cached TLS pointers across every opaque function call is deemed
unacceptable overhead.

\uabschnitt{Changes since P0876R8}

\begin{itemize}
    \item Reinstated cancellation function constructor argument.
    \item Added \cpp{cancel()} and \cpp{cancel\_from\_any\_thread()} member
          functions.
    \item Re-removed \unwindfib.
\end{itemize}

SG1 directed P0876R9 to conform to the Cologne 2019 recommendations, with any
other changes proposed in a separate paper.

\uabschnitt{Changes since D0876R7}

\begin{itemize}
    \item Cancellation function removed from \fiber constructor.
    \item \unwindfib re-added, with implementation-defined behaviour.
    \item Added elaboration of \cpp{filament} example to bind cancellation
          function.
\end{itemize}

P0876R8 diverged from the recommendations of the second SG1 round in Cologne
2019. It did not introduce \cpp{cancel()} or \cpp{cancel\_from\_any\_thread()}
member functions. In fact it removed the \cancelfn constructor argument.

\fiber is intended as the lowest-level stackful context-switching API. Binding
a \cancelfn on the fiber stack is a flourish rather than a necessity. It adds
overhead in both space (on the fiber stack) and time (to traverse the stack to
retrieve the \cancelfn). For this API, it should suffice to pass the desired
\cancelfn to \anyresumewith. If it is important to associate a \cancelfn with
a particular fiber earlier in the lifespan of the fiber, a struct serves.

A more compelling reason to avoid constructing an explicit fiber with
a \cancelfn is that no implicit fiber has any such \cancelfn\xspace -- and the
consuming application cannot tell, a priori, whether a given \fiber instance
represents an explicit or an implicit fiber. If \this represents an
implicit fiber, what should the proposed \cpp{cancel()} member function do?

Passing a specific \cancelfn to \anyresumewith avoids that problem.

P0876R8 follows SG1 recommendation in making it Undefined Behaviour to destroy
(or assign to) a non-empty \fiber instance.

\unwindfib was reintroduced with implementation-defined behaviour to allow fiber
cleanup leveraging implementation internals. Its use was entirely optional (and
auditable). 

\uabschnitt{Changes since P0876R6}

\begin{itemize}
    \item Implicit stack unwinding (by non-C++ exception) removed.
    \item \unwindfib removed.
    \item Cancellation function added to \fiber constructor.
\end{itemize}

In Cologne 2019, SG1 took the position that:

\begin{itemize}
    \item The \fiber facility is not the only C++ feature that
          requires ``special'' unwinding (special function exit path).
    \item Such functionality should be decoupled from \fiber. It requires its
          own proposal that follows its own course through WG21 process.
    \item Depending on this (yet to be written) proposal would unduly delay
          the \fiber facility.
    \item For now, the \fiber facility should adopt a ``less is
          more'' approach, removing promises about implicit unwinding, placing
          the burden on the consumer of the facility instead.
    \item This leaves the way open for \fiber to integrate with
          a new, improved unwind facility when such becomes available.
\end{itemize}

The idea of making \fiber's constructor accept a cancellation function was
suggested to permit consumer opt-in to P0876R5 functionality where
permissible, or convey to the fiber in question by any suitable means the need
to clean up and terminate.

Requiring the cancellation function is partly because it remains unclear what
the default should be. This could be one of the questions to be answered by a
TS. Moreover, the absence of a default permits specifying later that the
default engages the new, improved unwind facility.

\uabschnitt{Changes since P0876R5}

\begin{itemize}
    \item \cpp{std::unwind\_exception} removed.
    \item \cpp{fiber\_context::can\_resume\_from\_any\_thread()} renamed to
      \canxtresume.
    \item \cpp{fiber\_context::valid()} renamed to \emptyfn with inverted
      sense.
    \item Material has been added concerning the top-level wrapper
      logic governing each fiber.
\end{itemize}

\unwindex was removed in response to deep
discussions in Kona 2019 of the surprisingly numerous problems surfaced by
using an ordinary C++ exception for that purpose.

Problems resolved by discarding \unwindex:
\begin{itemize}
    \item When unwinding a fiber stack, it is essential to know the subsequent
          fiber to resume. \unwindex therefore bound a \fiber. \fiber is
          move-only. But C++ exceptions must be copyable.
    \item It was possible to catch and discard \unwindex, with problematic
          consequences for its bound \fiber.
    \item Similarly, it was possible to catch \unwindex but not rethrow it.
    \item If we attempted to address the problem above by introducing a
          \unwindex operation to extract the bound \fiber, it became possible
          to rethrow the exception with an empty (moved-from) \fiber instance.
    \item Throwing a C++ exception during C++ exception unwinding terminates
          the program. It was possible for an exception implementation based
          on \cpp{thread\_local} to become confused by exceptions on different
          fibers on the same thread.
    \item It was possible to capture \unwindex with \cpp{std::exception\_ptr}
          and migrate it to a different fiber -- or a different thread.
\end{itemize}