Home

	Expand Search

Open Client Client-Library/C Reference Manual

Chapter 2 Topics

Asynchronous programming

Layered applications

Layered applications

Asynchronous applications are often layered. In these types of applications, the lower layer protects the higher layer from low-level asynchronous detail.

The higher-level layer typically consists of:

• Mainline code

• Routines that asynchronously perform large operations.

  In this discussion, a "large" operation is a task that requires several Client-Library calls to complete. For example, updating a database table is a large operation because an application calls ct_command, ct_send, and ct_results to perform the update.

The lower-level layer typically consists of:

• The Client-Library routines required to perform a large operation

• Code to handle low-level asynchronous operation completions

ct_wakeup and the CS_DISABLE_POLL property are used in layered asynchronous applications as follows:

• A layered application uses CS_DISABLE_POLL to prevent ct_poll from reporting asynchronous Client-Library routine completions.

• A layered application uses ct_wakeup to let the higher layer know when a large asynchronous operation is complete.

A layered application that is using a routine to perform a large operation typically uses ct_wakeup and CS_DISABLE_POLL as follows:

1. The application performs any necessary initialization, installs callback routines, opens connections, and so on.

2. The application calls the routine that is performing the large operation.

3. If the application uses ct_poll to check for asynchronous completions, then the routine must disable polling. This prevents ct_poll from reporting lower-level asynchronous completions to the higher-level layer. To disable polling, the routine sets CS_DISABLE_POLL to CS_TRUE.

   If the application does not call ct_poll, the routine does not need to disable polling.

4. The routine calls ct_callback to replace the higher-level layer's completion callback with its own completion callback.

5. The routine performs its work.

6. The routine reinstalls the higher-level layer's completion callback.

7. If polling has been disabled, the routine enables it again by setting the CS_DISABLE_POLL property to CS_FALSE.

8. The routine calls ct_wakeup to trigger the higher-level layer's completion callback routine.

An application that performs asynchronous database updates might include the routine do_update, where do_update calls all of the Client-Library routines that are necessary to perform a database update.

The main application calls do_update asynchronously and go on with its other work.

When called, do_update replaces the main application's completion callback routine with its own callback (so that the main application's callback routine is not triggered by low-level asynchronous completions). It then proceeds with the work of the update. To perform the update, do_update calls several Client-Library routines, including ct_send and ct_results, which behave asynchronously. When each asynchronous routine completes, it triggers do_update's completion callback.

When do_update has finished the update operation, it reinstalls the main application's completion callback and calls ct_wakeup with function as its own function ID. This triggers the main application's completion callback, letting the main application know that do_update has completed.