Galaxy Communicator Documentation:

Synchronous and asynchronous interaction and continuations

License / Documentation home / Help and feedback

One of the strengths of the Galaxy Communicator infrastructure is the way it allows the programmer to reconcile conflicts between synchronous and asynchronous models of interaction, thereby enabling developers to use servers which embrace different models of synchrony without needing to modify the servers themselves. In this section, we present an overview of the different ways the Communicator infrastructure accomplishes this.

What doe we mean by synchrony?
Hub/server expectation mismatches
Continuations

In addition to the mechanisms described here, it's also possible to use provider IDs to guarantee that information reaches the proper provider when you're not using synchronous invocations.

What doe we mean by synchrony?

For the purposes of this discussion, we'll distinguish between invocations and interactions.

Invocations

Simply put, a synchronous invocation is one where the caller blocks waiting for the answer, and an asynchronous invocation is one where the caller does not block. Both the Hub and servers support both types of invocations. On the server side, the functions GalSS_EnvWriteFrame provides an asynchronous invocation, while the function GalSS_EnvDispatchFrame provides a synchronous invocation:

Gal_Frame message_f, reply_f; GalIO_MsgType t; GalSS_Environment *env; /* ... */ GalSS_EnvWriteFrame(env, f, 0); /* ... */ reply_f = GalSS_EnvDispatchFrame(env, f, &t);

On the Hub side, there are special control directives and OUT: values which indicate that the Hub should make an asynchronous invocation:

SERVER: foo OPERATION: bar ;; Synchronous interaction RULE: --> bar IN: :key1 OUT: :key2 ;; Asynchronous interaction RULE: --> bar IN: :key1 OUT: none!

Interactions

Interactions are a bit more global, and are most relevant to the server side. Even when a server makes asynchronous invocations exclusively (which corresponds, roughly, to a strict message-passing paradigm), it still may need to get information back. That is, while the server only makes asynchronous invocations (and may expect only asynchronous invocations), it will still probably support synchronous interactions, by sending a new message and receiving another message which "counts" as the reply, or by sending a new message instead of a reply in response to a request.

Hub/server expectation mismatches

Sometimes, the Hub programmer will have to deal with circumstances where a server which the programmer either cannot or doesn't want to change has different synchrony expectations than what the programmer requires. These conflicts will all originate on the server side. For concreteness, we'll use the case of a dialogue manager requiring information from the database.

Asynchronous caller, synchronous callee

In this situation, the caller invokes GalSS_EnvWriteFrame and anticipates a new message in response, but the server which ultimately provides the information provides the information as a reply. That is, the caller's interaction is asynchronous, but the callee supports this exchange with a synchronous invocation.

This case is trivial, because the Hub scripting language can easily transform a reply into a new message. Let's say the caller sends the DBQuery message, and expects the DBResult message in return:

SERVER: Dialogue OPERATIONS: DBResult SERVER: Database OPERATIONS: Query ... PROGRAM: DBQuery RULE: ... --> Database.Query IN: :query OUT: :columns :tuples RULE: :columns & :tuples --> Dialogue.DBResult IN: :columns :tuples OUT: none!

Synchronous caller, asynchronous callee

In this situation, the caller invokes GalSS_EnvDispatchFrame, but the server which ultimately provides the information provides the information as a new message instead of a reply. That is, the caller makes a synchronous invocation, but the callee supports this exchange with an asynchronous interaction.

This case is a little less trivial, but still straightforward. In this case, you can use the CONTINUE_REPLY: directive to capture a new message as a reply. Let's say the caller sends the DBQuery message as above, but this time expects a reply, and the callee accepts the Query message and issues the DBResult message in response:

SERVER: Dialogue SERVER: Database OPERATIONS: Query ... PROGRAM: DBQuery RULE: ... --> Database.Query IN: :query CONTINUE_REPLY: {c DBResult } OUT: :columns :tuples

When the program ends, it will send the current token state back to the caller as the reply. The programmer can use multiple CONTINUE_REPLY: and CONTINUE_ERROR: directives in the same rule.

For a somewhat different interface to the same functionality, you can also use the Hub Builtin function hub_continue. This function should be called immediately after a rule which does not wait for a reply, so it will be processed essentially simultaneously. This function allows the programmer to specify a list of possible reply and continuation frames, as well as a service type and/or service provider to monitor. While on the one hand, this mechanism allows the programmer to treat as replies new messages which come from other servers, it does not allow the programmer to automatically "inherit" the identity of the server the previous message was sent to:

PROGRAM: DBQuery RULE: ... --> Recognizer.Recognize IN: :query OUT: none! RULE: --> Builtin.hub_continue IN: (:reply_matches ( {c DBResult } ) ) (:service_type "Database") OUT: :columns :tuples

The Hub will monitor any provider of the Database service for a new message (in the current session) named DBResult, and treat it as the reply to the call to Builtin.hub_continue. The processing proceeds normally at that point.

Continuations

In addition to synchrony/asynchrony in invocations, the Galaxy Communicatof infrastructure also supports continuations on the server side. In the case of a server-side continuation, the Hub makes a synchronous invocation of a dispatch function. The dispatch function in the server, however, postpones the reply. The effect of this postponement is to inform the Hub that the server is done processing the dispatch function (so the Hub can now send the server more messages), but that it will provide the reply at a later time (e.b., when a particular callback fires). Let's consider a couple situations where this behavior may be useful.

Situation 1

Consider a case where the Hub sends a message to a recognizer that audio input is available via brokering. The recognizer server, in the appropriate dispatch function, sets up an incoming broker to capture the audio and send the result to the Hub. In the typical arrangement, exemplified by the example for GalSS_EnvBrokerDataInInit, the server writes a new message to the Hub. This new message is associated with a new token; that is, the recognizer server supports a this interaction via asynchronous invocations:

PROGRAM: FromAudio ... RULE: :audio_host & :audio_port & :call_id --> Recognizer.Recognize IN: :audio_host :audio_port :call_id OUT: none! PROGRAM: FromRecognizer RULE: :input_string --> Parser.Parse ....

However, the programmer might prefer that the call to the recognizer appear to the Hub to be a synchronous call; that is, that the input string be the reply to the Recognize message:

PROGRAM: FromAudio ... RULE: :audio_host & :audio_port & :call_id --> Recognizer.Recognize IN: :audio_host :audio_port :call_id OUT: :input_string RULE: :input_string --> Parser.Parse ....

The programmer could implement this behavior on the Hub side using CONTINUE_REPLY:, but it's also simple to do on the server side, using the function GalSS_EnvPostponeReply.

int GalSS_EnvPostponeReply(GalSS_Environment *env)
Informs the Hub that the response to its message will be delayed, but that in the meantime it's available for other incoming messages. It does this by sending a pacifier message of type GAL_POSTPONE_MSG_TYPE.

The programmer would then set up the broker as follows:

Gal_Frame Recognize(Gal_Frame f, void *server_data) { GalSS_Environment *env = (GalSS_Environment *) server_data; GalIO_BrokerStruct *b; /* ... */ GalSS_EnvPostponeReply(env); b = GalSS_EnvBrokerDataInInit(env, host, port, f, env_recognition_handler, 0, (void *) NULL, NULL); if (b) { GalIO_AddBrokerCallback(b, GAL_BROKER_DATA_DONE_EVENT, env_recognition_finalizer, (void *) NULL); GalIO_SetBrokerActive(b); } return (Gal_Frame) NULL; } static void env_recognition_handler(GalSS_Environment *env, GalIO_BrokerStruct *broker_struct, void *data, Gal_ObjectType data_type, int n_samples) { if (data_type == GAL_INT_16) { /* ... gather the audio ... */ } } static void env_recognition_finalizer(GalIO_BrokerStruct *broker_struct, void *caller_data) { /* Send the reply. The name doesn't matter because it will be set by the environment as the original name of the incoming message. */ GalSS_Environment *env = GalSS_BrokerGetEnvironment(broker_struct); Gal_Frame f = Gal_MakeFrame("foo", GAL_CLAUSE); /* ... */ Gal_SetProp(f, ":input_string", Gal_StringObject(recognized_string)); GalSS_EnvReply(env, f); Gal_FreeFrame(f); }

Observe that the dispatch function postpones the response, and then the environment-aware finalizer explicitly sends the reply when recognition is done. This same strategy could be used with timed task callbacks as well, if the appropriate situation arose.

For more details about environments, see the session documentation.

Note: there is an important interaction between GalSS_EnvPostponeReply and GalSS_EnvCopy. Inside a dispatch function, a call to GalSS_EnvPostponeReply counts as a reply. This is to ensure that all other replies sent from the dispatch function are ignored, including the return value. Once the dispatch function execution is completed, the environment is marked as still needing a reply, and it's assumed that the appropriate callback will provide it (as the recognition finalizer does in this example). What this means is that if you copy an environment after you write the postponement, the copy will never send another reply. It's entirely possible that the right thing to do is not to copy the reply flag when the postponement flag is set, but we're not willing to make that assumption yet. So if you want to copy a reply when you're going to send a postponement, copy the environment first, and then send the postponement through the original environment.

Situation 2

Consider a case where the server sends a request to the Hub using GalSS_EnvDispatchFrame. This function returns when the Hub returns a reply. However, during that time, the server is inaccessible for other dispatch function invocations from that Hub, and in addition, a deadlock will result if the Hub needs to contact the originating server in the course of satisfying the request (if, for instance, the program that is invoked by the incoming message ends up calling a dispatch function in the originating server). In this situation, the programmer might prefer to dispatch the request, and postpone the processing of the reply to the request using a continuation function. The programmer can accomplish this using the function GalSS_EnvDispatchFrameWithContinuation.

typedef Gal_Frame (*GalSS_ContinuationFn)(Gal_Frame, GalIO_MsgType, GalSS_Environment *, void *);
This is the type of the continuation function.

int GalSS_EnvDispatchFrameWithContinuation(GalSS_Environment *env, Gal_Frame frame, GalSS_ContinuationFn fn, void *continuation_state, void (*continuation_state_free_fn)(void *))
This function sends frame to the Hub using the environment env, and indicates that it expects a reply. It then notifies the Hub that the dispatch server response will be postponed using GalSS_EnvPostponeReply, and stores away the environment, along with the continuation function fn and an arbitrary state continuation_state, which the programmer can use to store arbitrary data for use in the continuation function. The data will be freed using the continuation_state_free_fn. The continuation function is invoked as the continuation of the dispatch function; in particular, if the continuation function returns a frame, it will be treated as the reply to the original dispatch function. It is called with the frame and message type of the reply to the original request to the Hub, the environment env, and the continuation_state.

int GalSS_EnvDispatchFrameToProviderWithContinuation(GalSS_Environment *env, Gal_Frame frame, const char *provider, GalSS_ContinuationFn fn, void *continuation_state, void (*continuation_state_free_fn)(void *))
Like GalSS_EnvDispatchFrameWithContinuation, but directs the message to the specific provider specified by provider (see the documentation on provider IDs for more details).