Home

	Expand Search

Open Client Client-Library/C Reference Manual

Chapter 2 Topics

Asynchronous programming

Asynchronous programming

Asynchronous applications are designed to make constructive use of time that would otherwise be spent waiting for certain operations to complete. Typically, reading from and writing to a network or external device is much slower than straightforward program execution. Also, it takes time for a server to process commands and send results back to the client application.

Some applications execute several tasks that involve idle time. For example, an interactive application might:

1. Wait for user input

2. Execute commands on a connection to Server X

3. Execute commands on a connection to Server Y

Client-Library's asynchronous modes help such an application to execute these tasks concurrently. When executing server commands, routines that send commands or read results return immediately. This means the application calls another routine to start command operations on another connection, and the application responds more quickly to user input.

Client-Library's asynchronous mode is one method for achieving concurrent task execution. The other is to use multiple threads. For information on using Client-Library in a multithreaded environment, see "Multithreaded programming".

Asynchronous applications

By default, Client-Library applications are synchronous. Routines that read from or write to the network do not return control to the caller until all the necessary I/O requests are complete.

When writing an asynchronous application, the application programmer must enable asynchronous Client-Library behavior at the context or connection level by setting the Client-Library property CS_NETIO. The possible network I/O modes are:

• Fully asynchronous (CS_ASYNC_IO) - Asynchronous routines return CS_PENDING immediately. When the requested operation completes, the connection's completion callback is invoked automatically.

• Deferred asynchronous (CS_DEFER_IO) - Asynchronous routines return CS_PENDING immediately. The application must periodically call ct_poll to check whether the operation has completed. If the operation is finished, ct_poll invokes the connection's completion callback. ct_poll also indicates which operation (if any) completed, so a deferred-asynchronous application can operate without a completion callback if desired.

• Synchronous (CS_SYNC_IO) - All Client-Library routines do not return until the requested operation is complete. This mode is the default.

When fully asynchronous or deferred-asynchronous mode is enabled, all Client-Library routines that read from or write to the network either:

• Initiate the requested operation and return CS_PENDING immediately, or

• Return CS_BUSY to indicate that an asynchronous operation is already pending for this connection. Non-asynchronous routines also return CS_BUSY if they are called when an asynchronous operation is pending for a connection.

By returning CS_PENDING, a routine indicates that the requested operation has begun and will complete asynchronously. The application receives the completion status from the call either by polling (that is, calling ct_poll periodically) or when Client-Library invokes the application's completion callback. Both methods are described under "Completions".

Asynchronous routines

The following Client-Library routines behave asynchronously:

• ct_cancel

• ct_close

• ct_connect

• ct_ds_lookup

• ct_fetch

• ct_get_data

• ct_options

• ct_recvpassthru

• ct_results

• ct_send

• ct_send_data

• ct_sendpassthru

The CS_BUSY return code

Any Client-Library routine that takes a command or connection structure as a parameter returns CS_BUSY. CS_BUSY indicates that a routine cannot perform because the relevant connection is currently busy, waiting for an asynchronous operation to complete.

An application calls the following routines while an asynchronous operation is pending:

• Any routine that takes a CS_CONTEXT structure as a parameter. If the CS_CONTEXT structure is an optional parameter, it must be non-NULL.

• ct_cancel(CS_CANCEL_ATTN)

• ct_cmd_props(CS_USERDATA)

• ct_con_props(CS_USERDATA)

• ct_poll

Completions

Every asynchronous mode Client-Library call that returns CS_PENDING produces a . This value corresponds to the return code that would have been returned by a synchronous-mode call to the routine (for example, CS_SUCCEED or CS_FAIL).

An application determines when an asynchronous routine completes either by polling or via completion callbacks. For polling, the application periodically calls ct_poll to determine if the asynchronous call has completed. With completion callbacks, the application is automatically notified when asynchronous calls complete.

To properly exit Client-Library, wait until all asynchronous operations are complete, then call ct_exit.

If an asynchronous operation is in progress when ct_exit is called, the routine returns CS_FAIL and does not exit Client-Library properly, even when CS_FORCE_EXIT is used.

The application polls for the completion status by calling ct_poll periodically until ct_poll indicates that the operation is complete. This mode of operation is called and corresponds to setting the CS_NETIO property to CS_DEFER_IO.

If the application installs a completion callback, the callback routine is called by ct_poll when ct_poll detects the completion. The application itself must call ct_poll.

The application learns the completion status of the asynchronous call from ct_poll. If a completion callback is installed, it also receives the completion status as an input parameter.

The Client-Library chapter in the Open Client/Server Programmer's Supplement describes the asynchronous modes, if any, that are supported on your platform.

On platforms where Client-Library uses signal-driven or thread-driven I/O, Client-Library automatically calls the application's completion callback routine when an asynchronous routine completes. This mode of operation is called and corresponds to setting the CS_NETIO property to CS_ASYNC_IO.

When a connection is fully asynchronous, the application does not have to poll for the completion status. Client-Library automatically invokes the application's completion callback, which receives the completion status as an input parameter. Completion callbacks are described under "Defining a completion callback".

When Client-Library is used within an Open Server, the CS_NETIO property cannot be set to CS_ASYNC_IO. The Open Server thread scheduler allows multitasking in an Open Server application.

On asynchronous connections, it is possible for Client-Library to complete an asynchronous operation and call the callback routine before the initiating routine returns. When this happens, the initiating routine still returns CS_PENDING, and the application's completion callback receives the completion status.

Client-Library's fully asynchronous operation is either thread-driven or signal-driven. On platforms that do not support either multiple threads or signal-driven I/O, Client-Library cannot be fully asynchronous.

Signal-driven completion handling

On some platforms such as UNIX, Client-Library uses operating system signals (also called interrupts) to read results and send commands over the network. Internally, Client-Library interacts with the network using non-blocking system calls and installs its own internal signal handler to receive the completion status for these system calls.

Note that on signal-driven I/O platforms, Client-Library may be signal-driven even when the CS_NETIO property is not CS_ASYNC_IO. On signal-driven I/O platforms, Client-Library uses signal-driven I/O if any of the following is true:

• The value of the CS_NETIO connection property is CS_ASYNC_IO.

• The value of the CS_ASYNC_NOTIFS connection property is CS_TRUE. The default is CS_FALSE. See "Asynchronous notifications" for a description of this property.

• The application has specified a finite timeout limit for the CS_TIMEOUT or CS_LOGIN_TIMEOUT context properties. The default is CS_NO_LIMIT, which is equivalent to infinity. See "Login timeout" and "Timeout" for a description of these properties.

Warning!

When Client-Library uses signal-driven I/O, a signal can interrupt the processing of system calls made by the application. If an error code indicates that a system call was interrupted, reissue the call.

On platforms where signal-driven I/O is used to implement Client-Library's fully asynchronous mode, fully asynchronous applications have the following restrictions:

• Any signal handlers required by the application must be installed using ct_callback. See "Signal callbacks" for more information.

• The application must provide a safe way for Client-Library to obtain memory at the interrupt level. See "Client-Library's interrupt-level memory requirements" for more information.

• On systems where Client-Library uses signal-driven I/O in fully asynchronous mode (UNIX), be sure to check the return value and error code after each system call to make sure that it completed properly. Some system calls fail when interrupted by a signal. If an error code indicates that the call was interrupted, issue the call again. This restriction is not an issue on platforms such as Windows NT where Client-Library does not use signals.

Thread-driven completion handling

On some platforms, such as Windows NT, Client-Library uses thread-driven I/O to operate in fully asynchronous mode.

When this I/O strategy is used, Client-Library spawns internal worker threads to interact with the network. When the application calls a routine that requires network I/O, the I/O request is passed to the worker thread. The asynchronous routine then returns CS_PENDING and the worker thread waits for the completion. When the I/O request completes, the worker thread calls the application's completion callback.

On platforms where thread-driven I/O is used, fully asynchronous applications have the following restrictions:

• All of the application's callback functions installed for each fully asynchronous connection must be thread-safe.

• Because the application's completion callback is invoked by a Client-Library worker thread, the application logic must be designed so that the completion callback communicates with mainline code in a thread-safe manner.

On thread-driven I/O platforms such as Windows NT, a fully asynchronous program is multithreaded in its callback execution even if the mainline code is single-threaded. For thread-driven I/O, a Client-Library worker thread interacts with the network for each fully asynchronous connection. The worker thread invokes the connection's callbacks for any callback events that it discovers. See "Fully asynchronous completions".

When fully asynchronous I/O is in effect on platforms where Client-Library uses thread-driven I/O, the application's callbacks are invoked by a Client-Library worker thread. On these platforms, a fully asynchronous application's callbacks are multithreaded even if the application itself uses a single-threaded design.

Issues affecting multithreaded application design are discussed in "Multithreaded programming".

Client-Library's interrupt-level memory requirements

On operating systems where Client-Library uses signal-driven I/O, such as UNIX-based systems and Digital OpenVMS VAX, fully asynchronous applications must provide a way for Client-Library to satisfy its interrupt-level memory requirements.

Ordinarily, Client-Library routines satisfy their memory requirements by calling malloc. However, not all implementations of malloc are safely called at the interrupt level. For this reason, fully asynchronous applications are required to provide an alternate way for Client-Library to satisfy its memory requirements.

Client-Library provides two mechanisms by which an asynchronous application satisfies Client-Library's memory requirements:

• The application uses the CS_MEM_POOL property to provide Client-Library with a memory pool.

• The application uses the CS_USER_ALLOC and CS_USER_FREE properties to install memory allocation routines that Client-Library safely calls at the interrupt level.

On platforms that use signal-driven I/O, Client-Library's behavior is undefined if a fully asynchronous application fails to provide a safe way for Client-Library to satisfy memory requirements.

Client-Library attempts to satisfy memory requirements from the following sources in the following order:

1. Memory pool

2. User-supplied allocation and free routines

3. System routines

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.