An asynchronous programming model requires applications to be able to wait for events from multiple sources without blocking on any particular one. Natural Access manages a list of wait objects internally for all of the devices that can generate events. Natural Access exposes two mechanisms for integrating application wait objects with the wait objects that Natural Access manages internally without requiring extra threads of execution.
The first mechanism gives Natural Access control to wait for application and Natural Access wait object signals. For example, an application can wait for a network event to arrive on a socket, input from a user through a keyboard or mouse, and an event from Natural Access. Natural Access allows the application to register the network socket and the keyboard and mouse objects with Natural Access so that the user application is called when there is an event on any of these.
The second mechanism enables the application to access the Natural Access internal wait objects so that the application can use operating system-specific wait functions to wait on the network socket and keyboard and mouse objects, as well as Natural Access internal objects.
Wait objects in Natural Access are operating system specific and are defined to be of the same basic type as the operating system requires in its wait functions.
In UNIX, the wait object is the pollfd structure that is passed to the poll system call. It contains a field for the file descriptor that is the same as the MUX_HANDLE type defined in nmstypes.h. It also contains extra fields that need to be specified in the call to poll.
In Windows, a wait object is equivalent to the MUX_HANDLE type defined in nmstypes.h. It is the same type as HANDLE and is passed to either WaitForSingleObject or WaitForMultipleObjects.
This topic presents:
ctaRegisterWaitObject enables applications to add wait objects to the list of wait objects that Natural Access manages internally. This function requires the application to supply the wait object and a function to be called whenever the wait object is signaled by the operating system. The application must also specify a priority for the application events.
|
Priority |
Description |
|---|---|
|
CTA_PRIORITY_HIGH |
The application's wait object are given a higher priority than the internal Natural Access wait objects. |
|
CTA_PRIORITY_NORMAL |
Natural Access wait objects are given higher priority than the application's wait objects. |
After registering the application wait objects with Natural Access, the application calls ctaWaitEvent. Whenever the application wait object is signaled, Natural Access gives up the queue lock and calls the application specified callback function to handle the event. The user callback function can call any Natural Access function except ctaWaitEvent or ctaDestroyQueue. Refer to ctaRegisterWaitObject for more information.
The application can call ctaUnregisterWaitObject to unregister an application wait object from Natural Access. Natural Access ignores any events on the application wait object after it has been unregistered.
Natural Access also provides a mechanism for applications to manage wait objects. On initialization, the application can specify a flag of CTA_NOTIFY_UPDATE_WAITOBJS to ctaInitialize. This flag tells Natural Access to notify the application through an event whenever Natural Access changes its list of internal wait objects. CTAEVN_UPDATE_WAITOBJS returns to the application whenever there is a change in the list of wait objects being managed by Natural Access. The application calls ctaQueryWaitObjects to get the list of wait objects that are used by Natural Access internally. The application subsequently calls the operating system dependent wait functions on their own wait objects as well as Natural Access wait objects returned by ctaQueryWaitObjects.
Whenever one of the Natural Access wait objects is signaled, the application detects it and calls ctaWaitEvent with a zero (0) timeout. Natural Access processes the event and returns control to the application. The application must ensure that ctaWaitEvent is called promptly after a Natural Access wait object is signaled.