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 fully asynchronous 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.
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.
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”.
