Simple Callback Messages

Callback messages are a way to call a function or a process using the syntax of a message, a syntactic commodity which does not introduce a new kind of actions.

A @message_def construction is used to specify a receiver and to associate to it a process or a function:

    @message_def recv1 := @cbk

The declaration is global: it can be appear anywhere in the score. Once specified, each message with receiver recv1 will call function @cbk instead of being dispatched to the Max or PD host (the default behavior).

Message's arguments becomes parameters of the function call:

  • If there is to few arguments w.r.t. to the function parameters, the remaining parameters are set to <undef>.

  • If there is to much arguments w.r.t. to the function parameters, all arguments in excess are gathered in a tab which becomes the last parameters.

For example, with @cbk defined as

    @fun_def @cbk($x, $y, $z) { print "x=" $x "y=" $y "z=" $z }

the following messages gives:

    toto 1          x= 1 y= <undef> z= <undef>
    toto 1 2        x= 1 y= 2 z= <undef>
    toto 1 2 3      x= 1 y= 2 z= 3
    toto 1 2 3 4    x= 1 y= 2 z= TAB[3, 4]


Callbacks

The right hand side of a @message_def specification must be an applicable value: a process, a function, an object with a method apply, a partially applied function, a nim, a tab or a map. However, to produce a visible effect, sending a callback message must imply some side-effect, which means that only process and (partially applied) function are relevant. For instance, a function may send Max messages.

The right hand side must be a closed expression or the @-name of a function.

Possibles Uses

This feature has been introduced to ease the transitionning of Max implemented functionnalities to Antescofo implementations. Using this features, messages sent to Max can be rerouted to an Antescofo process achieving the same behavior, without altering the main Antescofo program.

Another possibel use is to trap any control message to a sampler, to adapt its behavior during the fastforward phase of a transport command.


Full Callback Messages

The full specification of callback messages brought additional expressiveness.

Specification of receives through a regular expression

It is possible to define the receiver of a @message_def using a regular expression1 rather than a symbol. The callback is then defined for all receivers that match the regular expression. For example

    @message_def "t[ao]t[au]" := ::P

will call the process ::P instead of sending a message for the four receivers that are matched by the regular expression: tata, tatu, tota, and totu.

Optional Specification of a Context

Messages can appear in different contexts which modulate its interpretation:

  1. the message can be muted, in which case is it not actually sent,

  2. the execution can be done in fastforward mode, which implies that the messages are not sent,

  3. the receiver may correspond to an osc receivers,

  4. the receivers may correspond to an output file,

  5. or the receiver is really interpreted as a Max or PureData message that must be sent.

The @message_def construct accepts the specification of a context after the specification of the receiver. When a context is specified, the right hand side of the definition is substituted for the message only in the indicated context.

The contexts of a callback message are given as a bracketed list of symbols:

  1. muted is used to indicate a callback to use when the message is muted (instead of not sending it)

  2. fastforward or ffw for message during a fastforward mode

  3. osc for receivers that denote an osc output command

  4. outfile or out for receivers that denotes output in a file

  5. msg or message for ordinary message sent to the host.

Possible Use: a better handling of transport function

During a rehearsal, it is essential to have the ability to start the execution of the score at a given label. This can be done by using a transport command, for example startfromlabel. In this case, the execution of the score is started in fastforward mode up to the label and then the normal execution is resumed.

This approach is adequate when the computation at the other end of the messages send by Antescofo are “stateless”. As a matter of fact, messages are not sent during the fastforward mode. However, when the computation has a state, we need to send the relevant messages to update this state correctly, even in fastforward mode.

It can be achieved by definng a computation to trigger specifically during the fastforward mode:

    @message_def toto [ffw] := @toto_in_ffw_mode

replace the “non sending” of the toto message during a fastforward mode by a call to the function @toto_in_ffw_mode.

This mechanism can be used to bypass the message sending inhibition in the fastforward mode: it is enough to define a function @toto_in_ffw_mode that actually send the message.

There is however a difficulty: the substituted function or process is run also in fastforward mode and so cannot send itself a message. This difficulty can be alleviated using the @send_message() function which send a message irrespectively of a specific context.

For example, with this definition

    @fun_def @toto_in_ffw_mode($receiver, $args) { @send_message($receiver, args) }

the previous callback bypasses the silencing of messages during the fastforward mode to send specifically the toto messages.


An example of the correct management of sample playback relying on [callback events] and [message callbacks] is given here



  1. The syntax used to define the regular expression follows the posix extended syntax as defined in IEEE Std 1003.2, see for instance regular expression on Wikipedia