Method

Asks the coroutines of the frame, and of the frames nested in it, to stop, without an exception: sets the flag Frame::isCancellationRequested reads.

Description#

public Frame::requestCancellation(): void

It throws nothing and wakes nothing; code that runs a loop checks the flag and returns. A run() entered later in the frame, or in a frame nested in it, starts with the flag set. The flag stays set until the frame's run() returns. Frame::cancel and a passed Frame::setTimeout deadline set it too.

run()'s own $fn, having started the other coroutines of its frame, can call this and return normally to end them and itself cleanly: the others see isCancellationRequested() and end, and run() returns what $fn returned once they have. Calling Frame::cancel from inside the frame instead makes run() throw CancelledException -- its own wait for the frame's coroutines is the next wait -- which is right when the run as a whole is being cancelled, rather than ending itself on purpose.

Errors / Exceptions#

Examples#

phasync::run(function () {
    $frame = phasync::frame();
    phasync::go(function () use ($frame) {
        while (!$frame->isCancellationRequested()) {
            phasync::sleep(0.01);   // one tick
        }
    });
    phasync::sleep(0.1);
    $frame->requestCancellation();   // the loop ends after its current tick
});

See also#