Thread | SuperCollider 3.13.0 Help

Subclasses: Routine

Description

NOTE: A SuperCollider Thread is not an operating system thread. Although they have some conceptual similarities, they do not correspond.

A Thread represents the context within which code runs. It is also said that code runs "on a Thread". A Thread records the state of code execution, and thus provides support for code to be suspended at any time, and then resumed where it left off. It is then said that the Thread itself is suspended and resumed.

There is always one main Thread belonging to the Process - it is the Thread on which the top-level code runs. Another Thread may be started using an instance of the Thread's subclass Routine which will run a Function in the context of its own (there is no use in instantiating the Thread class itself).

When code on a Thread starts or resumes another Thread (Routine), the former Thread becomes the latter's parent, and the latter its child. The parent Thread's execution is blocked until the child Thread finishes or is suspended, at which point the parent Thread continues execution. The current Thread may be accessed using thisThread, while a Thread's parent may be accessed using -parent.

A Thread has

associated logical time
an associated Clock
own random number seed
own exception handler

thisThread

The global pseudo-variable thisThread always represents the current Thread, i.e. the context in which the current code is running. It can be either the main Thread or the Routine running the current code.

See also: Clock: Scheduling and Threads.// example thisThread.beats; thisThread.seconds; thisThread.clock;

Class Methods

Thread.new(func, stackSize: 512)

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

NOTE: There is no good use in instantiating a Thread, because this class offers no method of starting the given Function. Instead, use the Thread's subclass Routine. The only purpose of this constructor is for Routine to call it within its own constructor.

Arguments:

func	A Function with code for the Thread to run.
stackSize	Call stack size (an Integer).

Inherited class methods

Undocumented class methods

Thread.primitiveError

Thread.primitiveErrorString

Instance Methods

.parent

The parent Thread that started or resumed this Thread.

Discussion:

The parent Thread's execution is blocked until the child Thread finishes or is suspended.

When a child Thread is started or resumed, it inherits certain aspects from its parent:

associated Clock
associated logical time

.beats

.beats = inBeats

Get or set the current logical time of the Thread in beats. This will be the same as the time in seconds, unless this Thread's clock is TempoClock, and the clock's tempo is other than 1.

Setting beats also sets -seconds to thisThread.clock.beats2secs(beats).

Discussion:

There are several sources of logical time:

When code is run from the code editor, the command line, or in response to OSC and MIDI messages, the main Thread's logical time is set to the current physical time (see Process: *elapsedTime).
When code scheduled on a Clock is run, the main Thread's logical time is set to the time the code was scheduled for.
Child Threads inherit logical time from their parents - whenever a Thread (Routine) is started or resumed, its logical time is set to that of the parent Thread.

However, a Thread's logical time may also be set manually (using this method or -seconds). It may be useful to change the current Thread's time in order to manipulate behavior of streams that use the current logical time for their operation (e.g. streams created by Pstep and Pseg patterns). This will affect all code running within the current Thread, as well as any child Threads, due to logical time inheritance. Note however that changing another Thread's time will have no effect, because the time will be overridden by inheritance as soon as the Thread is run; likewise, any changes to the current Thread's time only have effect until the Thread is suspended (it yields) and resumed again.

.seconds

.seconds = inSeconds

Get or set the current logical time of the Thread in seconds.

Setting seconds also sets -beats to thisThread.clock.secs2beats(seconds).

See -beats for general discussion on Threads and logical time.

.clock

.clock = inClock

Get or set the Thread's associated Clock.

Discussion:

There are several ways a Clock becomes associated with a Thread:

When code is run from the code editor, the command line, or in response to OSC and MIDI messages, the main Thread's clock is set to SystemClock.
When code scheduled on a Clock is run, that clock becomes the main Thread's clock.
Child Threads inherit the associated clock from their parents.

A Thread's associated clock may also be set manually using this method. Setting the current Thread's clock is useful to manipulate further behavior of the Thread or its child Threads, but the clock will be reset the next time the Thread is resumed, due to clock inheritance. For the same reason, setting another Thread's clock will have no effect on code running on it.

.deferAwayFrom(func, delta: 0)

Executes a given function, guaranteeing that it will not execute on the same thread as this. That is:

If delta > 0 (the function should evaluate later), defer to AppClock.
If delta <= 0 (execute right now), defer to AppClock if thisThread matches the thread receiving this method call. Otherwise, directly Function: -value the function.

This method interface is designed to be used with function-call syntax, e.g. deferAwayFrom(aThread) { ... function body ... }.

Arguments:

func	The function to evaluate. It will not be passed any argument values.
delta	A time delta in seconds. Normally, the default 0 will be used.

.isPlaying

Returns:

true if it is playing.

.state

The internal state values for a Thread instance can be polled:

0	not started
7	running
8	stopped

Seeding the random number generator

.randSeed = seed

Set the random number generator seed using a single integer.

Discussion:

Example:g = thisThread.randSeed = 4; 10.do{1.0.rand2.postln};

.randData

.randData = data

Get or set the three integer array which defines the internal basis for the random number generator. You can use this to get back the exact same random number sequence, and it provides a mechanism for automatic replay for generative music.

Discussion:

Example:g = thisThread.randData; 10.do{1.0.rand2.postln};

// each time the seed is reset, the random number generation should give the same sequence thisThread.randData_(Int32Array[ -662787342, 1546785953, 1661466823 ]); 10.do{1.0.rand2.postln};