NAME
EV::Future::Handle - Cancellation and progress handle for EV::Future
SYNOPSIS
use EV;
use EV::Future;
my $h = parallel_map(\@items, \&worker, sub { print "done\n" });
printf "%d in flight, %d to go\n", $h->active, $h->pending;
$h->cancel; # stop dispatching; final_cb will not fireDESCRIPTION
The object every primitive in EV::Future returns in non-void context. It is a lightweight reference to the operation and owns nothing: destroying the handle does not cancel the operation, and the operation ending does not invalidate the handle. Every method below is safe to call at any time, including on a handle whose operation is already over, where cancel does nothing and both counters read 0.
The object wraps an internal C pointer to a refcounted cell using PERL_MAGIC_ext. Duplicating the handle via thread cloning yields undef (EV::Future::Handle sets CLONE_SKIP), while cloning via Storable or Clone::clone yields an inert dead handle without duplicating the underlying C cell.
METHODS
cancel([$fire])
Stop dispatching. With no argument, or a false one, final_cb never fires; with a true $fire it fires exactly once, with no arguments, before cancel returns. Idempotent, and a no-op once the operation is over.
pending
Tasks that have not yet completed, counting both those in flight and those not yet dispatched.
active
Tasks currently in flight. parallel and race report the same value here as for pending, because they dispatch every task before returning; series always reports 1 while it is running.
What the counters guarantee
Both read 0 once the operation is over, so pending == 0 means it has finished or been cancelled. The one exception is an operation abandoned by an escaping unsafe-mode exception, whose counters freeze instead.
In unsafe mode, double-calling done corrupts the completion counter, so pending under-reports for parallel and parallel_limit for the same reason final_cb can fire early. The same double-call can drive the in-flight count below zero; active is floored at 0 rather than reporting a negative.
SEE ALSO
AUTHOR
vividsnow
LICENSE
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.