Callback and Message Processing

Callback Method

A program that creates a subscriber must define a callback method to process its messages. You can define a separate callback for each subscriber, or reuse a callback for several subscribers.

Adding a subscriber to an event queue also associates the subscriber with a callback method, which processes all the messages that arrive through that subscriber.

A callback method receives an array of messages to process. The array might contain only one message, or several messages.

Processing usually involves getting values from the fields of a message, and doing some action (for example, storing values or sending another message).

It is good practice to code callbacks to return promptly.

In a straightforward scenario, in which processing is quick, developers code the callback method to process the messages and return after completing the message processing.

In a complex scenario, in which processing could involve delays, developers can code the callback method to transfer processing to another thread. Processing continues in the other thread, even as the callback method returns and the dispatch thread dispatches the next message event.

These two scenarios imply different behavior in the final phase, release.

Processing

The processing phase begins when the dispatch call invokes the callback method on a message.

In either of the two scenarios, all processing remains completely within the control of application code.

Release

Release is the final phase of the delivery cycle. The inbound message is no longer needed, and can be destroyed to reclaim resources.

In the straightforward scenario, FTL library code owns the message, and automatically destroys the message after the callback returns.

In the complex scenario, a subscriber can release all of its messages to the callback. Application program code must explicitly destroy each such message after processing completes.

Key Points for Developers

• You can code as many different callback methods as you need.
• Every message is processed using only one callback method. You associate the callback with the subscriber when you add the subscriber to an event queue.
• Code callback methods to return promptly.
• A callback runs within a dispatch thread, within your program's control flow.
• Message processing can continue in other threads, also within your program's control flow.
• Message release can be automatic or explicit.