|
|
|
|
The method that an application uses to schedule asynchronous events depends on which of the following types of application it is:
Applications that are based around a single main thread of execution to receive and process requests
Applications that can have several threads of execution receiving and processing requests
Applications that use the Motif interface and for which the application code consists mainly of callbacks from the Motif libraries
To schedule asynchronous events, single-threaded applications use the application scheduling mode or the signal-based 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. Use this mode in new applications.
Signal-based scheduling mode provides binary compatibility for existing SNAP-IX Version 5 applications. It should not be used in new applications.
Application scheduling mode provides a way for callback functions to be called from the application's main thread of execution. With this mode of operation, the MS API library has no need for multiple threads or signals.
Application scheduling mode works on the assumption that at the heart of an application there is a scheduling loop which includes a call to select or poll to determine whether there is work from one or more work sources. Application scheduling provides access to the file descriptor the MS API library uses to communicate with the SNAP-IX node. The application adds this file descriptor to its main scheduling select call, and when select indicates events on that file descriptor, the application calls a function to process the events and, if necessary, make the MS API callbacks. For more information about callbacks, see The Callback Routine Specified on the ms_async Entry Point.
SNA callbacks are not restricted to the event processor. Callbacks can be made from within any SNA library functions.
To use application scheduling mode, incorporate the following steps into your application code:
In the initialization section of the application, indicate that you want to use application scheduling mode by adding the following function call before the first call into any SNA library:
SNA_USE_FD_SCHED();
The SNA_USE_FD_SCHED call has no return value.
Write the main scheduling loop to set up the file descriptors and call select according to the following logic. Note that SNA_GET_FD returns an integer which is either a valid SNA file descriptor or -1 if there is no open SNA file descriptor. (The return of -1 indicates either that there has been no call into any SNA library, or that there has been a serious error resulting in the file descriptor being closed.)
fd= SNA_GET_FD();
if (fd != -1)
{
FD_SET(fd, &fdset);
}
select(nfds, *fdset, *fdset, *fdset, timeout);
If the select call returns with an indication of events on the SNA file descriptor, the application simply calls SNA_EVENT_FD. This function (which has no return value) processes all the events on the SNA file descriptor. If these events cause any MS verbs to complete, the MS API callback functions will be issued from within SNA_EVENT_FD.
Note that there is not a one-to-one mapping between calls to SNA_EVENT_FD and callbacks. There may be no callbacks (if the event does not complete a verb), or there may be many callbacks (because SNA_EVENT_FD processes all events before it returns).
SNA_EVENT_FD();
In general, SNA_GET_FD returns the same file descriptor each time you call it. However, you should call it before each call to select or poll, because there are some situations (such as when your application has issued the fork call, or in error cases) when the file descriptor may change.
The SNA event handler processes internal control messages between SNAP-IX components, which do not result in a call to your application's callback routine, in addition to processing MS indications and the completion of MS verbs. In addition, if there are multiple MS verbs outstanding, the SNA event handler may call the callback routine for any of these verbs (because the same file descriptor is used for all verbs).
Because of this, you cannot assume that an event on the SNA file descriptor corresponds to the completion of a particular verb. The correlator information passed to the callback routine is the correct method of checking which verb has completed, or whether this is an indication rather than a verb completion. The callback routine may either handle the verb completion or indication itself, or pass information to the main processing loop to indicate how the verb completion or indication should be processed. For more details of how the callback routine should operate, see The Callback Routine Specified on the ms_async Entry Point.
SNAP-IX 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 SNAP-IX 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_MS_APPLICATION or UNREGISTER_NMVT_APPLICATION, as appropriate, and issuing DISCONNECT_MS_NODE) before a thread terminates. The MS library does not maintain any correlation between threads and MS verb usage and does not perform this processing automatically when a thread terminates.
Applications that use the Motif interface, and whose code therefore consists mainly of callbacks from the Motif libraries, are required to add SNA events to the main Xt library scheduling loop. The SNA events enable the SNAP-IX 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.
SNA callbacks can also be made from within other calls into the SNA library.
|
|
|
 |
|