HelpSource/Classes/Scheduler.schelp

   1 CLASS::Scheduler
   2 categories::Scheduling
   3 summary::schedules functions to be evaluated in the future
   4
   5 DESCRIPTION::
   6 A Scheduler can be used to schedule and reschedule functions to be evaluated at a specific time-point. The Scheduler's time needs to be advanced manually. In most cases you will probably want to use a Clock (e.g. link::Classes/TempoClock::, link::Classes/SystemClock::, link::Classes/AppClock::) instead, in which the march of time is handled for you.
   7
   8 CLASSMETHODS::
   9
  10 method::new
  11 argument::clock
  12 A clock, like SystemClock.
  13 argument::drift
  14 If code::true::, link::#-sched:: will schedule tasks relative to the current absolute time ( link::Classes/Process#*elapsedTime#Main.elapsedTime:: ), otherwise to the current logical time of the scheduler ( link::#-seconds:: ).
  15 argument::recursive
  16 Sets link::#-recursive::.
  17
  18 INSTANCEMETHODS::
  19
  20 method::play
  21 Schedules the task immediately. Equivalent to code::sched(0, task)::.
  22
  23 method::sched
  24 Schedule the task at code::delta:: seconds relative to the current time, as defined by the code::drift:: argument of the link::#*new#constructor::.
  25
  26 Regardless of what time a task is scheduled, it will only be awaken the next time link::#-seconds:: is set.
  27
  28 method::schedAbs
  29 Schedule the task at absolute code::time:: in seconds.
  30
  31 method::advance
  32 Advance the current logical time by code::delta:: seconds. Has same effect as setting link::#-seconds::.
  33
  34 method::seconds
  35 The current logical time of the scheduler.
  36
  37 Setting a new time will wake up (evaluate) any tasks scheduled within that time; a task that returns a new time will be rescheduled accordingly.
  38
  39 method::isEmpty
  40 Returns whether the scheduling queue is empty.
  41
  42 method::clear
  43 Clears the scheduling queue
  44
  45 method::queue
  46 returns:: The instance of link::Classes/PriorityQueue:: used internally as scheduling queue.
  47
  48 method::recursive
  49 If waking up items results in new items being scheduled, but some of them are already expired (scheduled at current time or earlier), this variable determines whether those items will be awaken as well in the same call to -seconds.
  50
  51 EXAMPLES::
  52
  53 code::
  54 a = Scheduler(SystemClock);
  55
  56 a.sched(3, { "now it is 3 seconds.".postln; nil });
  57 a.sched(5, { "now it is 5 seconds.".postln; nil });
  58 a.sched(1, { "now it is 1 second.".postln; nil });
  59
  60 a.advance(0.5);
  61 a.advance(0.5);
  62 a.advance(2);
  63 a.advance(2);
  64
  65 // the beats, seconds and clock are passed into the task function:
  66 a.sched(1, { arg beats, secs, clock; [beats, secs, clock].postln });
  67 a.advance(1);
  68
  69 // the scheduling is relative to "now":
  70 a.sched(3, { "now it was 3 seconds.".postln });
  71 a.sched(5, { "now it was 5 seconds.".postln });
  72 a.sched(1, { "now it was 1 second.".postln });
  73
  74 a.advance(0.5);
  75 a.advance(0.5);
  76 a.advance(2);
  77 a.advance(2);
  78
  79 // play a Routine or a task:
  80 a.play(Routine { 5.do { arg i; i.postln; 1.yield } });
  81 a.advance(0.9);
  82 ::
  83
  84 code::
  85 // scheduling tasks
  86 (
  87 x = Scheduler(TempoClock.default);
  88
  89 Task {
  90         inf.do { |i|
  91                 ("next " ++ i ++ " in task." + Main.elapsedTime).postln;
  92                 0.5.wait;
  93         }
  94 }.play(x);
  95 )
  96
  97 x.advance(0.1);
  98 x.seconds;
  99 x.advance(5);
 100 x.seconds;
 101
 102 (
 103 Routine {
 104         loop { x.advance(0.1); 0.1.wait };
 105 }.play;
 106 )
 107
 108 (
 109 Task { 5.do {
 110         x.advance(1);
 111         2.0.rand.wait;
 112         }
 113 }.play;
 114 )
 115
 116 x.advance(8.1);
 117
 118 Pbind(\degree, Pseries(0, 2, 8), \dur, 0.25).play(x);
 119
 120 (
 121 Task { 5.do {
 122         x.advance(0.20);
 123         1.0.wait;
 124         }
 125 }.play;
 126 )
 127 ::