Callback Functions

Callback functions are an essential component of your program’s code. They do the actual application-specific work of responding to events—processing inbound messages, timer events and I/O conditions.

For example, inbound messages carry information from other program processes. As each message arrives, the receiving program must take appropriate actions, such as these:

•

Display the message to an end-user.

•

Store the message in a database.

•

Use message elements in calculations.

•

Forward the message across a gateway to another network.

•

Compose and send a reply message.

In essence, an event object represents a request to run program-specific code whenever a matching event occurs. Event interest persists until the program explicitly cancels its interest by destroying the event object.

While an event object exists, the event that it specifies can occur many times; consequently the event object reappears in its event queue as matching events occur and recur. The callback function runs once for each occurrence of the event (that is, each time the event appears in its queue, and the program dispatches it).

Dispatch Thread

A callback function always runs in the thread that dispatched its event.

For example, the dispatcher convenience feature (see Dispatcher Threads) runs callback functions outside of program control (usually, in a separate dispatcher thread). In a contrasting example, when a program explicitly calls a dispatch function, the callback function runs in the thread that called the dispatch function.

Closure Data

When creating an event, a program can supply closure data. Rendezvous software neither examines nor modifies the closure. Instead, the event creation call stores the data with the event, and presents it to the event callback function.

A similar mechanism passes closure data to ledger review callback functions.

In C and C++ programs, the closure argument is a pointer (of type void*); it can point to any type of data.

In Java programs, the closure argument is a reference to any object.

Return Promptly

In releases 5 and earlier, we warned programmers to ensure that callback functions return promptly and do not block. Callback functions that did not observe these precautions would obstruct important internal mechanisms of Rendezvous software. Starting in release 6, the event driver is entirely separate from the event dispatch mechanism. Consequently, blocking and long-running callback functions cannot interfere with Rendezvous internal mechanisms.

Warning

However, programmers must recognize that blocking and longing-running callback functions can delay dispatch of other events. Avoid these behaviors. When callback functions must block, or must run for long periods of time, it is good practice to dispatch from several threads to ensure prompt processing of all events.

Top