Often it is useful to have information that is shared across multiple threads or live loops. For example, you might want to share a notion of the current key, BPM or even more abstract concepts such as the current ‘complexity’ (which you’d potentially interpret in different ways across different threads). We also don’t want to lose any of our existing determinism guarantees when doing this. In other words, we’d still like to be able to share code with others and know exactly what they’ll hear when they run it. At the end of Section 5.6 of this tutorial we briefly discussed why we should not use variables to share information across threads due to a loss of determinism (in turn due to race conditions).

Sonic Pi’s solution to the problem of easily working with global variables in a deterministic way is through a novel system it calls Time State. This might sound complex and difficult (in fact, in the UK, programming with multiple threads and shared memory is typically a university level subject). However, as you’ll see, just like playing your first note, Sonic Pi makes it incredibly simple to share state across threads whilst still keeping your programs thread-safe and deterministic.

Meet get and set…

Sonic Pi has a global memory store called Time State. The two main things you do with it are to set information and get information. Let’s dive deeper…

Set

To store information into the Time State we need two things:

1. the information we want to store,
2. a unique name (key) for the information.

For example, we might want to store the number 3000 with the key :intensity. This is possible using the set function:

We can use any name for our key. If information has already been stored with that key, our new set will override it:

In the above example, as we stored both numbers under the same key, the last call to set ‘wins’, so the number associated with :intensity will be 3000 as the first call to set is effectively overridden.

Get

To fetch information from the Time State we just need the key we used to set it, which in our case is :intensity. We then just need to call get[:intensity] which we can see by printing out the result to the log:

Notice that calls to get can return information that was set in a previous run. Once a piece of information has been set it is available until either the information is overridden (just like we clobbered the :intensity value of 1000 to 3000 above) or Sonic Pi is closed.

Multiple Threads

The main benefit of the Time State system is that it can be safely used across threads or live loops. For example, you could have one live loop setting information and another one getting it:

The nice thing about using get and set across threads like this is that it will always produce the same result every time you hit run. Go on, try it. See if you get the following in your log:

Try running it a few times - see, it’s the same every time. This is what we call deterministic behaviour and it’s really very important when we want to share our music as code and know that the person playing the code is hearing exactly what we wanted them to hear (just like playing an MP3 or internet stream sounds the same for all listeners).

A Simple Deterministic State System

Back in Section 5.6 we discussed why using variables across threads can lead to random behaviour. This stops us from being able to reliably reproduce code such as this:

Let’s take a look at how this might look using get and set:

Notice how this code is pretty much identical to the version using a variable before it. However when you run the code, it behaves as you would expect with any typical Sonic Pi code - it does the same thing every time in this case thanks to the Time State system.

Therefore, when sharing information across live loops and threads, use get and set instead of variables for deterministic, reproducible behaviour.

Section 5.7 introduced the functions cue and sync when dealing with the issue of synchronising threads. What it didn’t explain was that it is the Time State system which provides this functionality. It just so happens that set is actually a variation of cue and is built on top of the same core functionality which is to insert information into the Time State system. Additionally, sync is also designed in such a way that it works seamlessly with Time State - any information that we plan to store in Time State we can sync on. In other words - we sync on events yet to be inserted into Time State.

Waiting for Events

Let’s take a quick look at how to use sync to wait for new events to be added to Time State:

In this example first we create a thread which waits for a :foo event to be added to the Time State. After this thread declaration we sleep for 2 beats and then set :foo to be 1. This then releases the sync which then moves to the next line which is to trigger the :ambi_lunar_land sample.

Note that sync always waits for future events and that it will block the current thread waiting for a new event. Also, it will inherit the logical time of the thread which triggered it via set or cue so it may also be used to sync time.

Passing values into the Future

In the example above we set :foo to 1 which we did nothing with. We can actually get this value from the thread calling sync:

Note that values that are passed through set and cue must be thread safe - i.e. immutable rings, numbers, symbols or frozen strings. Sonic Pi will throw an error if the value you are attempting to store in the Time State is not valid.

When getting and setting information into the Time State, it’s possible to use more complex keys than basic symbols such as :foo and :bar. You can also use URL style strings called paths such as "/foo/bar/baz". Once we start working with paths, we can then start taking advantage of Sonic Pi’s sophisticated pattern matching system to get and sync with ‘similar’ rather than ‘identical’ paths. Let’s take a look.

Match any path segment

Let’s assume we want to wait for the next event that has three path segments:

This will match any Time State event with exactly three path segments, regardless of their names. For example:

• cue "/foo/bar/baz"
• cue "/foo/baz/quux"
• cue "/eggs/beans/toast"
• cue "/moog/synths/rule"

However, it will not match paths with fewer or more path segments. The following will not match:

• cue "/foo/bar"
• cue "/foo/baz/quux/quaax"
• cue "/eggs"

Each * means any content. So we could match paths with just one segment with /* or paths with five segments with /*/*/*/*/*

Matching partial segments

If we know what the segment is going to start or finish with, we can use a * in addition to a partial segment name. For example: "/foo/b*/baz" will match any path that has three segments, the first of which is foo, the last baz and the middle segment can be anything that starts with b. So, it would match:

• cue "/foo/bar/baz"
• cue "/foo/baz/baz"
• cue "/foo/beans/baz"

However, it wouldn’t match the following:

• cue "/foo/flibble/baz"
• cue "/foo/abaz/baz"
• cue "/foo/beans/baz/eggs"

You can also place the * at the start of the segment to specify the last characters of a segment: "/foo/*zz/baz" which will match any 3 segment cue or set where the first segment is foo, the last is baz and the middle segment ends with zz such as "cue "/foo/whizz/baz".

Matching Nested Path Segments

Sometimes you don’t know how many path segments you want to match. In these cases you can use the powerful double star: ** such as "/foo/**/baz" which will match:

• cue "/foo/bar/baz"
• cue "/foo/bar/beans/baz"
• cue "/foo/baz"
• cue "/foo/a/b/c/d/e/f/baz"

Matching Single Letters

You can use the ? character to match against a single char such as "/?oo/bar/baz" which will match:

• cue "/foo/bar/baz"
• cue "/goo/bar/baz"
• cue "/too/bar/baz"
• cue "/woo/bar/baz"

Matching Multiple Words

If you know that a segment may be one of a select number of words, you can use the { and } matchers to specify a list of choices such as "/foo/{bar,beans,eggs}/quux" which will only match the following:

• cue "/foo/bar/quux"
• cue "/foo/beans/quux"
• cue "/foo/eggs/quux"

Matching Multiple Letters

Finally, you can match against a selection of letters if you use the [ and ] matchers to specify a list of choices such as "/foo/[abc]ux/baz" which will match only:

• cue "/foo/aux/baz"
• cue "/foo/bux/baz"
• cue "/foo/cux/baz"

You can also use the - character to specify ranges of letters. For example "/foo/[a-e]ux/baz" which will match only:

• cue "/foo/aux/baz"
• cue "/foo/bux/baz"
• cue "/foo/cux/baz"
• cue "/foo/dux/baz"
• cue "/foo/eux/baz"

Combining Matchers

When calling sync or get you are free to combine matchers in any order you see fit to powerfully match any Time State event created by cue or set. Let’s look at a far-fetched example:

OSC Pattern Matching

For those curious, these matching rules are based on the Open Sound Control pattern matching specification which is explained in detail here: https://opensoundcontrol.stanford.edu/spec-1_0.html