/chapter: Events / ChucK

ChucK

Events

In addition to the built-in timing mechanisms for internal control, ChucK has an event class to allow exact synchronization across an arbitrary number of shreds.

What they are

ChucK events are a native class within the ChucK language. We can create an event objects, and then chuck (=>) that event to now. The event places the current shred on the event's waiting list, suspends the current shred (letting time advance from that shred's point of view). When the the event is triggered, one or more of the shreds on its waiting list is shreduled to run immediately. This trigger may originate from another ChucK shred, or from activities taking place outside the Virtual Machine ( MIDI, OSC, or IPC ).

    // declare event
    Event e;

    // function for shred
    fun void eventshred( Event event, string msg )
    {
        // infinite loop
        while ( true )
        {
            // wait on event
            event => now;
            // print
            <<>>;
        }
   }

    // create shreds
    spork   eventshred ( e, "fee" );
    spork   eventshred ( e, "fi" );
    spork   eventshred ( e, "fo" );
    spork   eventshred ( e, "fum" );

    // infinite time loop
    while ( true )
    {
        // either signal or broadcast
        if( maybe )
        {
            <<<"signaling...">>>;
            e.signal();
        }
        else
          {
            <<<"broadcasting...">>>;
            e.broadcast();
          }

        // advance time
        0.5::second => now;
   }

Use

Chucking an event to now suspends the current shred, letting time advance:

    // declare Event
    Event e;

    // ...

    // wait on the event
    e => now;

    // after the event is trigger
    <<< "I just woke up" >>>;

As shown above, events can be triggered in two ways, depending on the desired behavior.

    // signal one shred waiting on the event e
    e.signal();

Signal() releases the first shred in that event's queue, and shredule it to run at the current time, respecting the order in which shreds were added to the queue.

    // wake up all shreds waiting on the event e
    e.broadcast();

broadcast() releases all shreds queued by that event, in the order they were added, and at the same instant in time

The released shreds are shreduled to run immediately. But of course they will respect other shreds also shreduled to run at the same time. Furthermore, the shred that called signal() or broadcast() will continue to run until it advances time itself, or yield the virtual machine without advancing time. (see me.yield() under concurrency)

MIDI events

ChucK contains built-in MIDI classes to allow for interaction with MIDI based software or devices.

    MidiIn min;
    MidiMsg msg;

    // open midi receiver, exit on fail
    if ( !min.open(0) ) me.exit();

    while( true )
    {
        // wait on midi event
        min => now;

        // receive midimsg(s)
        while( min.recv( msg ) )
        {
            // print content
            <<< msg.data1, msg.data2, msg.data3 >>>;
        }
    }

MidiIn is a subclass of Event, as as such can be ChucKed to now. MidiIn then takes a MidiMsg object to its .recv() method to access the MIDI data. As a default, MidiIn events trigger the broadcast() event behavior.

OSC events

In addition to MIDI, ChucK has OSC communication classes as well:

    // create our OSC receiver
    OscRecv orec;
    // port 6449
    6449 => orec.port;
    // start listening (launch thread)
    orec.listen();

    function void rate_control_shred()
    {
        // create an address in the receiver
        // and store it in a new variable.
        orec.event("/sndbuf/buf/rate,f") @=> OscEvent oscdata;

        while ( true )
        {
            oscdata => now; //wait for events to arrive.

            // grab the next message from the queue.
            while( oscdata.nextMsg() != 0 )
             {
                // getFloat fetches the expected float
                // as indicated in the type string ",f"
                buf.rate( oscdata.getFloat() );
                0 => buf.pos;
             }
        }
   }

The OscRecv class listens for incoming OSC packets on the specified port. Each instance of OscRecv can create OscEvent objects using its event() method to listen for packets at any valid OSC address pattern.

An OscEvent event can then be ChucKed to now to wait for messages to arrive, after which the nextMsg() and getFloatStringInt() methods can be used to fetch message data.

Creating custom events

Events, like any other class, can be subclassed to add functionality and transmit data:

    // extended event
    class TheEvent extends Event
    {
        int value;
    }

    // the event
    TheEvent e;

    // handler
    fun int hi( TheEvent event )
    {
        while( true )
         {
            // wait on event
            event => now;
            // get the data
            <<>>;
         }
     }

    // spork
    spork   hi( e );
    spork   hi( e );
    spork   hi( e );
    spork   hi( e );

    // infinite time loop
    while( true )
    {
        // advance time
        1::second => now;

        // set data
        Math.rand2( 0, 5 ) => e.value;

        // signal one waiting shred
        e.signal();
    }

VM Wide Events

Often it can be useful to trigger events across the VM outside of the child/parent shred relationship.

This can be done by declaring a reference to static data within a public class. You may only declare one public class in a file so the following must be added as two files. For more on classes see Objects reference.

This example creates a VM wide event that also has communicates an int value.

File 1: Extend Event to carry int value

//First Extend Event to carry int
public class E extends Event{
    int value;
}

File 2:Declare static version of extend class and instantiate once.

//Create Static Event
public class vmwEvent{
    static E @ gbEvent;
}
new E @=> vmwEvent.gbEvent;

This creates the global VM wide event which can then be used as required.

Write int value and broadcast event

//send values
while (true){
    Std.rand2(100,300) => vmwEvent.gbEvent.value;
    vmwEvent.gbEvent.broadcast();
    500::ms => now;
    <<<"sent">>>;
}

Receive and read int value for VM wide event.

//receive values
while (true){
    vmwEvent.gbEvent => now;
    <<< vmwEvent.gbEvent.value >>>;
    <<<"got">>>;
}