Scheduling Asynchronous Events

The method that an application uses to schedule asynchronous events depends on which of the following types of application it is:

Single-threaded applications: Applications that are based around a single main thread of execution to receive and process requests
Multithreaded applications: Applications that can have several threads of execution receiving and processing requests
Motif applications: Applications that use the Motif interface and for which the application code consists mainly of callbacks from the Motif libraries

Single-Threaded Applications

To schedule asynchronous events, single-threaded applications can use either the application scheduling mode or the signal-based scheduling mode.

Application Scheduling Mode

Application scheduling mode gives the application full control over event scheduling from different sources by integrating SNA callbacks with the application's main processing loop. The application calls an SNA event handler entry point in the SNA library when work is available for the library to process, and the handler makes the necessary callbacks to the application.




	NOTE: SNA callbacks can also be made from within other calls into the SNA library.

To receive notification of SNA events, the application accesses the file descriptor on which SNA events arrive. The application then calls the SNA event handler to process events received on this file descriptor and generate any subsequent callbacks. For more information about callbacks, see “The Callback Routine Specified on the nof_async Entry Point”.

The application scheduling mode assumes that the application is structured as a main loop consisting of a call to either select or poll followed by code to process event information returned by the select or poll call.

To use application scheduling mode, incorporate the following steps into your application code:

Indicate that you want to use application scheduling mode by adding the following function call to your code before the first call into any SNA library:
SNA_USE_FD_SCHED();
The SNA_USE_FD_SCHED call has no error return values.
Add code to obtain and track any changes to the SNA file descriptor. Call the following function from your code before any call to select or poll that can be used to detect SNA events:
Fd= SNA_GET_FD();
The SNA_GET_FD call returns either a valid file descriptor or a -1 indicating that no valid SNA file descriptor is available.
If the return is valid, the application then must register for “read” events on the SNA file descriptor in the select or poll call. When an event is detected, the application must call the SNA event handler.
To call the SNA event handler, add the following function call to your code:
SNA_EVENT_FD();
The SNA_EVENT_FD call has no error return values.

Signal-Based Scheduling Mode

Signal-based scheduling mode provides binary compatibility for existing SNAplus2 Release 4 and SNAplus2 Release 5; applications. It is not recommended for new applications because support for signal-based scheduling mode may be discontinued in future versions of SNAplus2.

Asynchronous verbs are implemented by making callbacks to the application from signal catcher context. The disadvantages of signal-based scheduling mode are:

Applications that receive work from multiple sources are difficult to write.
Applications are required to use HP-UX V.3 signal calls.
Applications can use only a subset of system calls made from signal catcher context and therefore from the API callback context.
Signaling mode is not thread-safe

Use of Signals

To detect work arriving from other components of SNAplus2, the NOF library makes use of the SIGPOLL signal. Applications can require the SIGPOLL signal for other purposes. Therefore, the library daisy-chains to any existing signal catchers. The first verb issued by the application initializes the library's signal catcher.

When the SIGPOLL signal arrives, either it indicates work for SNAplus2 or it was generated for some other reason. The NOF library's signal catcher processes the signal and then calls the previous signal catcher to allow the signal to be used for other purposes.

The following restrictions apply to SIGPOLL usage:

Applications must not permanently disable this signal. The sighold and sigrelse signal calls can be used to protect a critical region of code, provided that no SNA verbs are issued between sighold and sigrelse.
Applications must preserve the address of the SNAplus2 signal catchers returned by the sigset call when adding signal catchers to applications. Applications must then arrange to call these routines from within the new signal catchers.
Applications must not use the POSIX signal mechanism SIGACTN, which can cause problems in SNAplus2 applications.

HP-UX Sleep Call

The HP-UX operating system call sleep can cause problems if applications or their libraries also use signal catchers. Because the SNAplus2 NOF library operates using a signal catcher, do not use the sleep call within a NOF application that uses signal-based scheduling. If necessary, you can use the alarm with a timer to provide the same function.

Multithreaded Applications

SNAplus2 API libraries are available for linking with multithreaded applications. When you develop applications to operate in a multithreaded environment, the following restrictions apply:

When an application uses the asynchronous entry point, the application is required to maintain the consistency of its data structures when callbacks are invoked. Consistency of data structures can be maintained using the multithreading lock or mutex facilities. The callbacks are made in the context of a separate thread created and managed from within the SNAplus2 API library. Since asynchronous callbacks run using a separate thread, the application is not required to provide a source of scheduling to enable the callbacks. Do not use application scheduling mode in a multithreaded application.
The application must perform any required cleanup processing (for example, issuing UNREGISTER_INDICATION_SINK and issuing DISCONNECT_NODE or CLOSE_FILE) before a thread terminates. The NOF library does not maintain any correlation between threads and NOF verb usage and does not perform this processing automatically when a thread terminates.

For the HP-UX 10.20 operating system, kernel threads are not supported.

Back Level Applications

New applications will use dynamic libraries in /opt/sna/lib/hpux32 or /opt/sna/lib/hpux64. SNAplus2 release 6.2 also includes a set of dynamic libraries to support existing applications that have been built with previous version of SNAplus2 on PA-Risc. These libraries are on /opt/sna/lib or /opt/sna/lib/pa20_64. There are multiple copies of some libraries to support different levels of the interfaces.

Motif Applications

Applications that use the Motif interface and whose code consists mainly of callbacks from the Motif libraries are required to add SNA events to the main Xt library scheduling loop. The SNA events allow the SNAplus2 library to run callbacks in order to process asynchronous verb completions.

Add the following lines to your code before the first call into any SNA library:

#include <Xt.h>
int app_context;
...
XtAppInitialize(app_context...)
...
SNA_USE_XT_SCHED(app_context);

The SNA_USE_XT_SCHED call has no return values. It calls the XtAppAddInput function to register the SNA work sources. When work subsequently arrives on the SNA file descriptor, the Xt library scheduling loop calls the SNA event handler, which then makes any required API callbacks to the application.




	NOTE: SNA callbacks can also be made from within other calls into the SNA library