Scheduler refinements/defilements

Renamed basic scheduler method to .cue
Combined various other scheduler methods to use named parameters instead
Added :at($instant) for a way to specify an absolute time
Removed .outstanding because...
Added .loads to give info on how many cues are in delayed/startable/running states

Author: TimToady

S17-concurrency.pod

@@ -158,28 +158,28 @@ dynamically scoped, this means that test scheduler modules can be developed
 that poke a C<$*SCHEDULER> into C<EXPORT>, and then provide the test writer
 with control over time.
 
-The simplest operation available on a scheduler is C<schedule>, which takes a
-C<Callable> object and schedules it.
+The C<cue> method takes a C<Callable> object and schedules it.
 
-    $*SCHEDULER.schedule({ say "Golly, I got scheduled!" });
+    $*SCHEDULER.cue: { say "Golly, I got scheduled!" }
 
-There is also a method to schedule an operation to run after a certain time
-period:
+Various options may be supplied as named arguments.  (All references to time
+are taken to be in seconds, which may be fractional.)  You may schedule an
+event to fire off after some number of seconds:
 
-    $*SCHEDULER.schedule-in({ say "10s later" }, 10);
+    $*SCHEDULER.cue: in=>10, { say "10s later" }
 
-And one to schedule an operation to run at a fixed interval, possibly with a
+or at a given absolute time, specified as an C<Instant>:
+
+    $*SCHEDULER.cue: at=>$instant, { say "10s later" }
+
+Use C<:every> to schedule an operation to run at a fixed interval, possibly with a
 delay before the first scheduling.
 
     # Every second, from now
-    $*SCHEDULER.schedule-every({ say "Oh wow, a kangaroo!" }, 1);
-    $*SCHEDULER.schedule-every({ say "Oh wow, a kangaroo!" }, 1, 0);
+    $*SCHEDULER.cue: :every(1), { say "Oh wow, a kangaroo!" }
 
     # Every 0.5s, but don't start for 2s.
-    $*SCHEDULER.schedule-every({ say "Kenya believe it?" }, 0.5, 2);
-
-[To consider: we could have a single schedule method taking named parameters
-:$catch, :$in, and :$every instead.]
+    $*SCHEDULER.cue({ say "Kenya believe it?" }, :every(0.5), :in(2));
 
 If a scheduled item dies, the scheduler will catch this exception and pass it
 to a C<handle_uncaught> method, a default implementation of which is provided
@@ -193,22 +193,28 @@ the entire application to terminate. However, it is possible to replace this:
 For more fine-grained handling, it is possible to schedule code along with a
 code object to be invoked with the thrown exception if it dies:
 
-    $*SCHEDULER.schedule_with_catch(
+    $*SCHEDULER.cue:
         { upload_progress($stuff) },
-        -> $ex { warn "Could not upload latest progress" });
+        catch => -> $ex { warn "Could not upload latest progress" }
+
+Schedulers also provide counts of the number of operations in various states:
 
-Schedulers also provide a count of the number of outstanding operations to be
-performed:
+    say $*SCHEDULER.loads;
 
-    say $*SCHEDULER.outstanding;
+This returns, in order, the number of cues that are not yet runnable due to
+delays, the number of cues that are runnable but not yet assigned to a thread,
+and the number of cues that are now assigned to a thread (and presumably running).
+[Conjecture: perhaps these should be separate methods.]
 
-They may optionally provide further introspection in order to support tools
+Schedulers may optionally provide further introspection in order to support tools
 such as debuggers.
 
 There is also a C<CurrentThreadScheduler>, which always schedules things on
 the current thread. It provides the same methods, just no concurrency, and
 any exceptions are thrown immediately. This is mostly useful for forcing
-synchrony in places that default to asynchrony.
+synchrony in places that default to asynchrony.  (Note that C<.loads> can never
+return anything but 0 for the currently running cues, since they're waiting
+on the current thread to stop scheduling first!)
 
 =head1 Promises
 
@@ -324,7 +330,7 @@ C<Promise.alarm> factory is implemented:
     method alarm(Promise:U: $seconds, :$scheduler = $*SCHEDULER) {
         my $p = Promise.new(:$scheduler);
         my $k = $p.keeper;
-        $scheduler.schedule-in({ $k.keep(True) }, $seconds);
+        $scheduler.cue: { $k.keep(True) }, :in($seconds);
         $p
     }