Routine : Thread : Stream : AbstractFunction : Object

Creates an instance of Routine, passing it the Function with code to run.

Arguments:

Discussion:

The Function class provides its own shortcut method r that calls Routine.new, thus one can also write:a = r { 1.yield; 2.yield };

This method performs differently according to the Routine's state:

• Starts the Routine, if it has not been started yet or it has been reset; i.e runs its Function from the beginning, passing on the inval argument.
• Resumes the Routine, if it has been suspended (it has yielded); i.e. resumes its Function from the point where yield was called on an Object, passing the inval argument as the return value of yield.
• Does nothing if the Routine has stopped (because its Function has returned, or -stop has been called).

thisThread : Since Routine inherits from Thread, it will become the current thread when it is started or resumed; i.e. thisThread used in the Routine Function will return the Routine.

Time: Just before next is called, thisThread points either to another Routine, or the top-level Thread. During the next call, this becomes the parent thread (see Thread: -parent). next then evaluates on the parent's clock, at the parent's logical time.

Synonyms for next are -value and -resume.

Returns:

Discussion:

When a Routine is started by a call to this method (or one of its synonyms), the method's argument is passed on as the argument to the Routine Function:Routine { arg inval; inval.postln; }.value("hello routine");

After the Routine has yielded (it has been suspended at the point in its Function where yield is called on an Object), a call to this method (or its synonyms) resumes executing the Function and the argument to this method becomes the return value of yield. To access that value within the Function, you have to assign it to a variable - typically, the argument of the Function is reused:( r = Routine { arg inval; inval.postln; inval = 123.yield; inval.postln; } ) r.value("hello routine"); r.value("goodbye routine");

Typically, a Routine yields multiple times, and each time the result of the yield is reassigning to the argument of its Function.( r = Routine { arg inval; inval.postln; // Post the value passed in when started. 5.do { arg i; inval = (i + 10).yield; inval.postln; // Post the value passed in when resumed. } } ) ( 5.do { r.value("hello routine").postln; // Post the value that the Routine yields. } )

Equivalent to -next.

Equivalent to -next.

Equivalent to the Routine Function reaching its end or returning: after this, the Routine will never run again (the -next method has no effect and returns nil), unless -reset is called.

Causes the Routine to start from the beginning next time -next is called.

Discussion:

If a Routine is stopped (its Function has returned or -stop has been called), it will never run again (the -next method has no effect and returns nil), unless this method is called.

A Routine cannot reset itself, except by calling Object: -yieldAndReset.

See also: Object: -yield, Object: -alwaysYield

Schedules the Routine on the given Clock, at a time specified by quant. At that time, the Routine will wake up (by calling Routine: -awake), setting the clock and time and evaluating the Routine. If the Routine yields a number, this number of beats will be added to the current time and the Routine will be rescheduled. (This behavior is compatible with scheduling a Stream or a Function.)

Arguments:

Discussion:

using Object: -idle within a routine, return values until this time is over. Time is measured relative to the thread's clock.// for 6 seconds, return 200, then continue ( r = Routine { 199.yield; 189.yield; 200.idle(6); 199.yield; 189.yield; }; fork { loop { r.value.postln; 1.wait; } } ); // the value can also be a stream or a function ( r = Routine { 199.yield; 189.yield; Routine { 100.do { |i| i.yield } }.idle(6); 199.yield; 189.yield; }; fork { loop { r.value.postln; 1.wait; } } );

If a Routine is currently scheduled on a clock, it will be expected to "awake" at a specific time, on a specific clock. reschedule allows you to change to a different clock or to a later time.

Arguments:

Discussion:

• Rescheduling to a different clock will be continuous in terms of seconds, but not necessarily continuous in terms of beats. Time-based patterns such as Pseg, or the use of Env as a stream, may not follow the envelope shape continuously. (Pseg and Env-as-stream measure time in beats on the clock that is playing. In normal use, the clock never changes, so time advances monotonically through the envelope's breakpoints. If a thread is rescheduled to a different clock, the beats values are very unlikely to be the same on the new clock. So the envelope would jump forward or backward in time.)

  When switching the clock, reschedule will first calculate the new "awake" time, in beats, based on the given quant. Then it converts that beats value into the new clock's beats for the same instant in time. If the old clock's tempo is 1 and the Routine is waiting for 1 beat, the next "awake" should happen after one second. When rescheduling without a quant, the next "awake" will still happen after one second -- but the beats value will adjust for the new clock.

• Currently quant will resolve to a time later than the Routine's current nextBeat. If you try to force it earlier, there is likely to be some discontinuity. This is because the Routine cannot reschedule until it wakes up normally. The workaround is to switch the Routine into a different Task wrapper.
• Currently the routine must be playing (already scheduled on a clock). This is because the handoff to the new clock or time occurs during the thread's "awake" process. If the routine is not playing, then it will not awake, and nothing will happen.

This method is called by a Clock on which the Routine was scheduled when its scheduling time is up. It calls -next, passing on the scheduling time in beats as an argument. The value returned by next (the value yielded by the Routine) will in turn be returned by this method, thus determining the time which the Routine will be rescheduled for.

Arguments:

Convert the routine to a (subclass of) Pattern.

Returns:

Discussion:

Any subclass of Pattern returns a Stream in response to asStream. However, the exact subclass of Stream returned depends on the class of the Pattern. In particular, a Prout returns a Routine in response to asStream. Thus, a way to make an independent copy of a Routine is to make a Prout from it with the method p, and then create a new Routine from this Prout. In the example immediately below, this second step is done explicitly by calling asStream, but in the context of passing arguments to other Patterns, this latter step usually happens automatically, as shown in later examples.( r = Routine { "hi".yield; "bye".yield }; r.next.postln; // "hi" posted q = r.p.asStream; // or just: r.p.iter q.next.postln; // "hi" again r.next.postln; // "bye" because r kept its own state, separate from q )

The Routine method p is mostly useful in the context of using the result of Routine-returning expressions as arguments to Patterns, when the intent is to use the Routine's result as a pattern, i.e. multiple occurrences acting independently of each other.( r = (:2..5); // a seriesIter Routine Ptuple([r, r]).asStream.all.postln; // posts [ [ 2, 3 ], [ 4, 5 ] ] r.next.postln; // nil p = r.p; // make a Pattern from r; it doesn't matter that r has ended Ptuple([p, p]).asStream.all.postln; // posts [ [ 2, 2 ], [ 3, 3 ], [ 4, 4 ], [ 5, 5 ] ] // Obviously, explicitly writing the same Routine-valued subexpression twice // also creates separate Routines. Ptuple([(:2..5), (:2..5)]).asStream.all.postln; // posts [ [ 2, 2 ], [ 3, 3 ], [ 4, 4 ], [ 5, 5 ] ] )

In the following example, directly reusing the same Routine object twice in a Pseq fails to duplicate its output, because the first embedding fully consumes the routine's (non-nil) output.( r = (:2..6); Pseq([r, r]).asStream.all.postln; // [ 2, 3, 4, 5, 6 ] p = r.p; Pseq([p, p]).asStream.all.postln; // [ 2, 3, 4, 5, 6, 2, 3, 4, 5, 6 ] Pseq([(:2..6), (:2..6)]).asStream.all.postln; // [ 2, 3, 4, 5, 6, 2, 3, 4, 5, 6 ] )

Returns:

Returns:

Returns: