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 using Open Server libraries built with native threading
support, CS_NETIO can
be set to CS_ASYNC_IO and
full asynchronous behavior is supported. When using Open Server
libraries that are not built with native threading support, setting CS_NETIO to CS_ASYNC_IO results
in behavior that is similar to CS_DEFER_IO except
that instead of the application calling ct_poll to
complete I/O operations, Open Server invokes a poll routine
for the 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 value of CS_PROP_MIGRATABLE is CS_TRUE (the default), and the client has connected to a server that might migrate the client.
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”.
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”.
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 where Client-Library does not use signals.
On some platforms, such as Windows, 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, 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 can 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”.
