SuperCollider CLASSES

Thread

The context of code evaluation
Inherits from: Stream : AbstractFunction : Object
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

 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%20and%20Threads.

// example
thisThread.beats;
thisThread.seconds;
thisThread.clock;

Class Methods

*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

*primitiveError

*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:

-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:

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.

See also: Clock: Scheduling%20and%20Threads.

-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:

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.

See also: Clock: Scheduling%20and%20Threads.

-isPlaying

Returns:

true if it is playing.

-state

The internal state values for a Thread instance can be polled:
0not started
7running
8stopped

Seeding the random number generator

see also: Random Seed

-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};

Inherited instance methods

Undocumented instance methods

-archiveAsCompileString

-checkCanArchive

-copy

-endBeat

-endBeat = value

-endValue

-endValue = value

-exceptionHandler

-exceptionHandler = value

-executingPath

-failedPrimitiveName

-findThreadPlayer

-handleError (error)

-next

-nextBeat

-oldExecutingPath

-primitiveError

-primitiveIndex

-threadPlayer

-threadPlayer = value

-value

-valueArray