=begin pod :kind("Type") :subkind("role") :category("domain-specific")

=TITLE role Scheduler

=SUBTITLE Scheme for automatically assigning tasks to threads

    role Scheduler {
        has &.uncaught_handler is rw
    }

Common role for schedulers. A scheduler is a piece of code that determines
which resources to use to run which task, and when.

Some operations for example on L<Proc::Async|/type/Proc::Async>, L<Promise|/type/Promise>,
L<Supply|/type/Supply> allow you to specify a scheduler explicitly; they
generally expect those schedulers to follow the interface defined by
C<Scheduler>

=head1 Methods

=head2 method uncaught_handler

    method uncaught_handler() is rw

RW-Accessor for the handler that is caught for uncaught exceptions from the
code that is being scheduled and run.

=head2 method cue

    method cue(&code, Instant :$at, :$in, :$every, :$times = 1; :&catch --> Cancellation)

Schedules a callable (C<&code>) for execution and returns an instantiated
C<Cancellation> object to cancel the scheduling of the code for execution
(which is especially important if you specify the C<every => time> named
parameter. The adverbs control when and how the code is run:

C<$at> can be an L<Instant|/type/Instant> before which the code won't be run.
Alternatively C<$in> is the number of seconds (possibly fractional) to wait
before running the code. If C<$at> is in the past or C<$in> is negative,
the delay is treated as zero. Implementations may equate to zero
very small values (e.g. lower than 0.001s) of C<$in> or result of
C<$at> - L<now|/routine/now>.

If C<$every> is specified, it is interpreted as the number of seconds
(possibly fractional) to wait before re-executing the code. Implementations
may treat too-small values as lowest resolution they support, possibly
warning in such situations; e.g. treating C<0.0001> as C<0.001>.

C<$times> tells the scheduler how many times to run the code.

C<&catch> is called with the L<Exception|/type/Exception> as its sole argument
if C<&code> dies.

If C<$at> or C<$in> are C<Inf>, C<&code> will never be run; if C<$every> is
C<Inf>, C<&code> will only be run once. If any of the three are C<-Inf>,
C<&code> will be run immediately. If any of the three are C<NaN>, an
L<X::Scheduler::CueInNaNSeconds|/type/X::Scheduler::CueInNaNSeconds> exception
will be thrown. This only applies to releases 2019.05 and later.

One should call the C<cancel> method on the returned C<Cancellation> object
to cancel the (possibly repeated) cueing of the code.

=end pod

# vim: expandtab softtabstop=4 shiftwidth=4 ft=perl6
