class::Routine
categories::Core>Kernel
summary:: Functions that can return in the middle and then resume where they left off
related:: Classes/Stream

description::
A Routine runs a link::Classes/Function:: and allows it to be suspended in the middle
and be resumed again where it left off. This functionality is supported by the Routine's
superclass link::Classes/Thread::. Effectively, Routines can be used to implement
co-routines as found in Scheme and some other languages.

A Routine is strong::started:: the first time link::#-next:: is called, which will run
the Function from the beginning. It is strong::suspended:: when it "yields"
(using link::Classes/Object#-yield:: within the Function), and then strong::resumed::
 using link::#-next:: again. When the Function returns, the Routine is considered
strong::stopped::, and calling link::#-next:: will have no effect - unless the Routine is
strong::reset:: using link::#-reset::, which will rewind the Function to the beginning.
You can stop a Routine before its Function returns using link::#-stop::.

When a Routine is strong::scheduled:: on a link::Classes/Clock:: (e.g. using
link::#-play::), it will be started or resumed at the scheduled time. The value yielded
by the Routine will be used as the time difference for rescheduling the Routine. (See
link::#-awake::).

Since Routine inherits from link::Classes/Thread::, it has its own associated
link::Classes/Thread#-beats#logical time::, etc. When a Routine is started or
resumed, it becomes the link::Classes/Thread#.thisThread#current thread::.

Routine also inherits from link::Classes/Stream::, and thus shares its ability to be
combined using math operations and "filtered".


classMethods::

method::new

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

argument::func
A Function with code for the Thread to run.

argument::stackSize
Call stack size (an Integer).

discussion::
code::
a = Routine.new({ 1.yield; 2.yield; });
a.next.postln;
a.next.postln;
a.next.postln;
::

The Function class provides its own shortcut method code::r:: that calls code::Routine.new::, thus one can also write:

code::
a = r { 1.yield; 2.yield };
::

instanceMethods::

method::next

This method performs differently according to the Routine's state:
list::
## Starts the Routine, if it has not been started yet or it has been
link::#-reset#reset::; i.e runs its Function from the beginning, passing on the
code::inval:: argument.
## Resumes the Routine, if it has been suspended (it has yielded); i.e. resumes its
Function from the point where link::Classes/Object#-yield#yield:: was called on an Object,
passing the code::inval:: argument as the return value of code::yield::.
## Does nothing if the Routine has stopped (because its Function has returned, or
link::#-stop:: has been called).
::

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

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

Synonyms for code::next:: are link::#-value:: and link::#-resume::.

returns::
list::
## Either the value that the Routine yields (the Object on which
link::Classes/Object#-yield#yield:: is called within the Routine Function),
## ...or code::nil::, if the Routine has stopped.
::

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:

code::
Routine { arg inval;
	inval.postln;
}.value("hello routine");
::

After the Routine has yielded (it has been suspended at the point in its Function where
code::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
code::yield::. To access that value within the Function, you have to assign it to a
variable - typically, the argument of the Function is reused:

code::
(
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.

code::
(
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.
}
)
::

method::value

Equivalent to link::#-next::.

method::resume

Equivalent to link::#-next::.

method::stop

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

method::reset

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

discussion::

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

A Routine cannot reset itself, except by calling link::Classes/Object#-yieldAndReset::.

See also: link::Classes/Object#-yield::, link::Classes/Object#-alwaysYield::


method::play

Schedules the Routine on the given link::Classes/Clock::, at a time specified by code::quant::. At that time, the Routine will wake up (by calling link::Classes/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 link::Classes/Stream:: or a link::Classes/Function::.)

argument::clock
a Clock, TempoClock by default

argument::quant
see the link::Classes/Quant:: helpfile

discussion::
using link::Classes/Object#-idle:: within a routine, return values until this time is over. Time is measured relative to the thread's clock.
code::
// 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;
	}
}
);
::

method:: reschedule

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

argument:: argClock
The new clock on which to run the Routine. If code::nil::, the routine's clock will not be changed. (Note: Currently incompatible with link::Classes/AppClock::; rescheduling depends upon the method code::schedAbs::, which AppClock does not implement.)

argument:: quant
A quantization specifier, identifying a time emphasis::later:: than the next-scheduled time. If code::nil::, the current value of code::nextBeat:: will be used.

discussion::

list::
## 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 link::Classes/Pseg::, or the use of link::Classes/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, code::reschedule:: will first calculate the new "awake" time, in beats, based on the given code::quant::. Then it converts that code::beats:: value into the new clock's code::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 code::quant::, the next "awake" will emphasis::still:: happen after one second -- but the code::beats:: value will adjust for the new clock.

## Currently code::quant:: will resolve to a time emphasis::later:: than the Routine's current code::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 link::Classes/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.
::

code::
// Rescheduling to a different clock, same time
c = TempoClock.new;

(
t = Routine {
	var lastSeconds = thisThread.seconds;
	loop {
		1.0.wait;
		[thisThread.beats, thisThread.seconds - lastSeconds].postln;
		lastSeconds = thisThread.seconds;
	}
}.play;
)

t.reschedule(c);  // seconds delta = 1.0 throughout

t.stop;

// Rescheduling to a later time, same clock
(
t = Routine {
	var lastSeconds = thisThread.seconds;
	loop {
		1.0.wait;
		[thisThread.beats, thisThread.seconds - lastSeconds].postln;
		lastSeconds = thisThread.seconds;
	}
}.play;
)

t.reschedule(quant: 1);

t.stop;

// Rescheduling to an earlier time (workaround, only possible way)
// Requires you to start with a PauseStream!
// This does not work if 't' is a Routine initially.
(
t = PauseStream(Routine {
	var lastSeconds = thisThread.seconds;
	loop {
		1.0.wait;
		[thisThread.beats, thisThread.seconds - lastSeconds].postln;
		lastSeconds = thisThread.seconds;
	}
}).play;
)

// shorter than 1 beat later
(
u = PauseStream(t.stream);
TempoClock.schedAbs(t.nextBeat.trunc, u.refresh);
t.stop;
)

u.stop;
::

method:: awake

This method is called by a link::Classes/Clock:: on which the Routine was scheduled
when its scheduling time is up. It calls link::#-next::, passing on the scheduling
time in beats as an argument. The value returned by code::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.

argument:: inBeats
The scheduling time in beats. This is equal to the current logical time
(link::Classes/Thread#-beats::).

argument:: inSeconds
The scheduling time in seconds. This is equal to the current logical time
(link::Classes/Thread#-seconds::).

argument:: inClock
The clock which awoke the Routine.


method:: p

Convert the routine to a (subclass of) link::Classes/Pattern::.

returns::

A link::Classes/Prout:: that (in response to code::asStream::) acts as a generator of independent copies of the original routine (the receiver of code::p::).


discussion::

Any subclass of Pattern returns a Stream in response to code::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 code::asStream::. Thus, a way to make an independent copy of a Routine is to make a Prout from it with the method code::p::, and then create a new Routine from this Prout. In the example immediately below, this second step is done explicitly by calling code::asStream::, but in the context of passing arguments to other Patterns, this latter step usually happens automatically, as shown in later examples.

code::
(
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
)
::

note::
New routines produced by code::.p.asStream:: run the original routine's function from the beginning. There is no copy of the internal state of the original routine, only its function is copied. On a related note, code::Routine.copy:: (inherited from code::Thread::) does not create a new, separate Routine; it just returns the receiver.
::

The Routine method code::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.

code::
(
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 code::Pseq:: fails to duplicate its output, because the first embedding fully consumes the routine's (non-nil) output.

code::
(
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 ]
)
::


subsection::Accessible instance variables

Routine inherits from link::Classes/Thread::, which allows access to some of its state:

code::
(
r = Routine { arg inval;
	loop {
		// thisThread refers to the routine.
		postf("beats: % seconds: % time: % \n",
			thisThread.beats, thisThread.seconds, Main.elapsedTime
		);
		1.0.yield;

	}
}.play;
)

r.stop;
r.beats;
r.seconds;
r.clock;
::

method::beats

returns:: The elapsed beats (logical time) of the routine. The beats do not proceed when the routine is not playing.

method::seconds

returns:: The elapsed seconds (logical time) of the routine. The seconds do not proceed when the routine is not playing, it is the converted beat value.

method::clock

returns:: The thread's clock. If it has not played, it is the SystemClock.

examples::

code::
(
var r, outval;
r = Routine.new({ arg inval;
	("->inval was " ++ inval).postln;
	inval = 1.yield;
	("->inval was " ++ inval).postln;
	inval = 2.yield;
	("->inval was " ++ inval).postln;
	inval = 99.yield;
});

outval = r.next('a');
("<-outval was " ++ outval).postln;
outval = r.next('b');
("<-outval was " ++ outval).postln;
r.reset; "reset".postln;
outval = r.next('c');
("<-outval was " ++ outval).postln;
outval = r.next('d');
("<-outval was " ++ outval).postln;
outval = r.next('e');
("<-outval was " ++ outval).postln;
outval = r.next('f');
("<-outval was " ++ outval).postln;
)
::

code::
// wait

(
var r;
r = Routine {
	10.do({ arg a;
		a.postln;
		// Often you might see Wait being used to pause a routine
		// This waits for one second between each number
		1.wait;
	});
	// Wait half second before saying we're done
	0.5.wait;
	"done".postln;
}.play;
)
::

code::
// waitUntil

(
var r;
r = Routine {
	var times = { rrand(1.0, 10.0) }.dup(10) + thisThread.beats;
	times = times.sort;
	times.do({ arg a;
		waitUntil(a);
		a.postln;
	});
	// Wait half second before saying we're done
	0.5.wait;
	"done".postln;
}.play;
)
::

code::
// Using Routine to set button states on the fly.
(
var update, w, b;
w = SCWindow.new("State Window", Rect(150,SCWindow.screenBounds.height-140,380,60));

// a convenient way to set the button label
update = {
	|but, string| but.states = [[string.asString, Color.black, Color.red]];
	but.refresh;
};

b = SCButton(w, Rect(10,10,360,40));
b.font_(Font("Impact", 24));

update.value(b, "there is only one state");

// if an action should do something different each time it is called, a routine is the
// right thing to use. This is better than creating variables outside and setting them
// from the action function to keep state from one action to the next

b.action_(Routine { |butt|
	rrand(15, 45).do { |i|
		update.value(butt, "%. there is still only 1 state".format(i + 2));
		0.yield; // stop here
	};
	w.close;
});

w.front;
)
::

code::
// drawing in a window dynamically with Pen
(
var w, much = 0.02, string, synth;

w = Window.new("swing", Rect(100, 100, 300, 500)).front;
w.view.background_(Color.new255(153, 255, 102).vary);

string = "swing ".dup(24).join;

w.drawFunc = Routine {
	var i = 0;
	var size = 40;
	var func = { |i, j| sin(i * 0.07 + (j * 0.0023) + 1.5pi) * much + 1 };
	var scale;
	Pen.font = Font("Helvetica-Bold", 40);
	loop {
		i = i + 1;
		string.do {	|char, j|

			scale = func.value(i, j).dup(6);

			Pen.fillColor = Color.new255(0, 120, 120).vary;
			Pen.matrix = scale * #[1, 0, 0, 1, 1, 0];
			Pen.stringAtPoint(char.asString,
				((size * (j % 9)) - 10) @ (size * (j div: 9))
			);
		};
		0.yield // stop here, return something unimportant
	}
};

fork { while { w.isClosed.not } { defer { w.refresh }; 0.04.wait; } };

w.front;

)
::