Class

Frame

The lifetime of a phasync::run() call: the coroutines started inside it, which it waits for, cancels and rethrows.

Introduction#

Every run() creates a frame, and go() starts its coroutine in the frame of the caller. run() returns once every coroutine of its frame has ended, those of the frames nested in it included. It then throws every failure, what $fn threw and the failures of coroutines nobody awaited: one as it is, several in an AggregateException. The coroutines are never cancelled because one failed. A frame is not the identity of the work: that is the ambient Scope (fiber-interop/scope), which a frame neither creates nor changes. One scope may span several frames, and one frame hold coroutines of several scopes.

phasync::frame() returns the frame of the running coroutine. A service (phasync::service()) has none.

Class synopsis#

final class Frame {
    /* Methods */
    public Frame::cancel(
        Stringable|CancelledException|string $message = 'Operation cancelled'
    ): void
    public Frame::setTimeout(float $seconds): void
    public Frame::requestCancellation(): void
    public Frame::isCancellationRequested(): bool
    public Frame::setExceptionHandler(?Closure $handler): void
}

Methods#

Method	Description
`cancel`	Cancels every coroutine of the frame, and of the frames nested in it, with a CancelledException.
`setTimeout`	Cancels the frame when `$seconds` have passed, and makes its `run()` throw a TimeoutException instead of the cancellation.
`requestCancellation`	Asks the coroutines of the frame, and of the frames nested in it, to stop, without an exception: sets the flag `Frame::isCancellationRequested` reads.
`isCancellationRequested`	Whether the frame, or a frame it is nested in, was asked to stop.
`setExceptionHandler`	Sends the failures of the frame's coroutines that nobody awaited to `$handler`, one by one, instead of having `run()` throw them.

Examples#

Example 1

phasync::run(function () {
    phasync::frame()->setTimeout(2.0);   // the whole run, its coroutines included
    phasync::go(fn () => fetch('a'));
    phasync::go(fn () => fetch('b'));
});   // throws phasync\TimeoutException after 2 seconds

Frame

Introduction#

Class synopsis#

Methods#

Examples#

See also#