Help/Scheduling/Task.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
   5 <meta http-equiv="Content-Style-Type" content="text/css">
   6 <title></title>
   7 <meta name="Generator" content="Cocoa HTML Writer">
   8 <meta name="CocoaVersion" content="824.44">
   9 <style type="text/css">
  10 p.p1 {margin: 0.0px 0.0px 0.0px 0.0px; font: 18.0px Helvetica}
  11 p.p2 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; min-height: 12.0px}
  12 p.p3 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica}
  13 p.p4 {margin: 0.0px 0.0px 0.0px 0.0px; font: 12.0px Helvetica; min-height: 14.0px}
  14 p.p5 {margin: 0.0px 0.0px 0.0px 0.0px; font: 14.0px Helvetica}
  15 p.p6 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #000000}
  16 p.p7 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #000000; min-height: 12.0px}
  17 p.p8 {margin: 0.0px 0.0px 0.0px 0.0px; font: 9.0px Monaco; color: #bf0000}
  18 span.s1 {color: #0000ff}
  19 span.s2 {color: #0000bf}
  20 span.s3 {color: #606060}
  21 span.Apple-tab-span {white-space:pre}
  22 </style>
  23 </head>
  24 <body>
  25 <p class="p1"><b>Task<span class="Apple-tab-span">      </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span>a pauseable process</b></p>
  26 <p class="p2"><br></p>
  27 <p class="p3"><b>superclass: PauseStream<span class="Apple-converted-space"> </span></b></p>
  28 <p class="p4"><br></p>
  29 <p class="p3">Task is a pauseable process. It is implemented by wrapping a PauseStream around a Routine. Most of its methods (start, stop, reset) are inherited from PauseStream.</p>
  30 <p class="p4"><br></p>
  31 <p class="p3">Tasks are not 100% interchangeable with Routines.</p>
  32 <p class="p4"><br></p>
  33 <p class="p3">- Condition does not work properly inside of a Task.</p>
  34 <p class="p3">- Stopping a task and restarting it quickly may yield surprising results (see example below), but this is necessary to prevent tasks from becoming unstable if they are started and/or stopped in rapid succession.</p>
  35 <p class="p4"><br></p>
  36 <p class="p4"><br></p>
  37 <p class="p3"><b>Task.new(func, clock)</b></p>
  38 <p class="p3"><b>func </b>- A <b>Function</b> to be evaluated.<span class="Apple-converted-space"> </span></p>
  39 <p class="p3"><b>clock </b>- A Clock in which to play the <b>Routine</b>. If you do not provide a Clock the default is an instance of TempoClock. Remember that methods which call Cocoa primitives (i.e. GUI functions) must be played in AppClock.</p>
  40 <p class="p4"><br></p>
  41 <p class="p3"><b>play(argClock, doReset, quant)</b></p>
  42 <p class="p3"><b>argClock</b> - (optional) Override the clock assigned in Task.new</p>
  43 <p class="p3"><b>doReset</b> - If true, the task will start over from the beginning. Default is false (task will resume where it was when it was last stopped)</p>
  44 <p class="p3"><b>quant</b> - see the <a href="Quant.html"><span class="s1">Quant</span></a> helpfile</p>
  45 <p class="p4"><br></p>
  46 <p class="p4"><br></p>
  47 <p class="p5"><b>Other control methods</b></p>
  48 <p class="p4"><br></p>
  49 <p class="p3"><b>start(argClock, quant)</b> - Restart the task from the beginning.</p>
  50 <p class="p3"><b>resume(argClock, quant)</b> - Resume the task where it left off.</p>
  51 <p class="p3"><b>pause</b> - Stop playing now.</p>
  52 <p class="p3"><b>stop</b> - Stop playing now. (Pause and stop have the same implementation.)</p>
  53 <p class="p3"><b>reset</b> - Set the stream to restart from the beginning the next time it's played.</p>
  54 <p class="p4"><br></p>
  55 <p class="p4"><br></p>
  56 <p class="p5"><b>Notifications</b></p>
  57 <p class="p4"><br></p>
  58 <p class="p3">Other objects might need to be aware of changes in the state of a task. The following notifications are broadcast to dependents registered with the Task object.</p>
  59 <p class="p4"><br></p>
  60 <p class="p3"><b>\userPlayed</b> - Sent at the time the user calls play, start or resume.</p>
  61 <p class="p3"><b>\playing</b> - Sent at the time the task begins playing on the clock (corresponding to quant).</p>
  62 <p class="p3"><b>\userStopped</b> - Sent at the time the user calls pause or stop.</p>
  63 <p class="p3"><b>\stopped</b> - Sent at the time the task is finally removed from the clock (this is the time when the next event would have occurred if the task had not been stopped). If the task function completes on its own, this notification is sent without 'userStopped' being sent previously.</p>
  64 <p class="p4"><br></p>
  65 <p class="p4"><br></p>
  66 <p class="p3"><b>What happens if you stop and start the task too quickly?</b></p>
  67 <p class="p4"><br></p>
  68 <p class="p2"><br></p>
  69 <p class="p6">t = <span class="s2">Task</span>({<span class="Apple-converted-space"> </span></p>
  70 <p class="p6"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>50.do({ <span class="s2">arg</span> i;</p>
  71 <p class="p6"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span>i.squared.postln;<span class="Apple-converted-space"> </span></p>
  72 <p class="p6"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span><span class="Apple-tab-span">    </span>0.5.wait<span class="Apple-converted-space"> </span></p>
  73 <p class="p6"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>});<span class="Apple-converted-space"> </span></p>
  74 <p class="p6"><span class="Apple-tab-span">     </span>});</p>
  75 <p class="p7"><br></p>
  76 <p class="p6">t.start;</p>
  77 <p class="p6">t.pause;</p>
  78 <p class="p6">t.resume;</p>
  79 <p class="p6">t.reset;</p>
  80 <p class="p6">t.stop;</p>
  81 <p class="p7"><br></p>
  82 <p class="p7"><br></p>
  83 <p class="p8">// unexpected behavior here</p>
  84 <p class="p7"><br></p>
  85 <p class="p6">(</p>
  86 <p class="p6">t = <span class="s2">Task</span>({</p>
  87 <p class="p6"><span class="Apple-tab-span">     </span>[<span class="s3">"go"</span>, <span class="s2">thisThread</span>.clock.beats].postln;</p>
  88 <p class="p6"><span class="Apple-tab-span">     </span><span class="s2">inf</span>.do({ <span class="s2">arg</span> i;</p>
  89 <p class="p6"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>2.wait;</p>
  90 <p class="p6"><span class="Apple-tab-span">     </span><span class="Apple-tab-span">    </span>[ <span class="s3">"wake up"</span>, i ].postln<span class="Apple-converted-space"> </span></p>
  91 <p class="p6"><span class="Apple-tab-span">     </span>})</p>
  92 <p class="p6">});</p>
  93 <p class="p7"><br></p>
  94 <p class="p6">fork {</p>
  95 <p class="p6"><span class="Apple-tab-span">     </span>t.start;</p>
  96 <p class="p6"><span class="Apple-tab-span">     </span>0.1.wait;</p>
  97 <p class="p6"><span class="Apple-tab-span">     </span>t.stop;</p>
  98 <p class="p6"><span class="Apple-tab-span">     </span>0.1.wait;</p>
  99 <p class="p6"><span class="Apple-tab-span">     </span>t.start;</p>
 100 <p class="p6"><span class="Apple-tab-span">     </span>6.wait;</p>
 101 <p class="p6"><span class="Apple-tab-span">     </span>t.stop;</p>
 102 <p class="p6">};</p>
 103 <p class="p6">)</p>
 104 <p class="p7"><br></p>
 105 <p class="p6">[ go, 1702.114411906 ]</p>
 106 <p class="p6">[ go, 1704.114411906 ]</p>
 107 <p class="p2"><br></p>
 108 <p class="p3">Based on the forked thread, you would expect the second "go" line of output to occur 0.2 seconds after the first, but in fact it happens two seconds later (the same amount of time the task waits between iterations). This is because the task must not schedule itself on the clock more than once. When the task is stopped, it remains scheduled until it wakes up again (based on its wait time). If, during this interval, the task were restarted, there would be two references to the task in the scheduler queue -- a situation that is irrecoverable short of stopping everything with command-period.</p>
 109 <p class="p4"><br></p>
 110 <p class="p3">As a result, Task should be used for processes that need to start and stop relatively infrequently, but for which maximum stability is required. If you need fine-grained control over when and how the process stops and resumes (as is the case, for instance, with condition), Routine is preferred.</p>
 111 </body>
 112 </html>