Home

	Expand Search

Open Client Client-Library/C Reference Manual

Chapter 2 Topics

Asynchronous programming

Completions

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".