Priority	Description
CTA_PRIORITY_HIGH	CT Access gives the application's wait object a higher priority than it gives to internal CT Access wait objects
CTA_PRIORITY_NORMAL	CT Access wait objects are given higher priority than the application's wait objects.

(Page 5 of 9 in this chapter)

3.4 Using Wait Objects

An asynchronous programming model requires that applications be able to wait for events from multiple sources without blocking on any particular one. CT Access manages a list of wait objects internally for all of the devices that could generate events. CT Access exposes two mechanisms for integrating application wait objects with the wait objects that CT Access manages internally without requiring extra threads of execution.
The first mechanism gives control to CT Access to wait for application and CT Access wait object signals. The second mechanism allows the application to wait for these signals and then call CT Access when a CT Access wait object was signaled.
For example, an application could be waiting for a network event to arrive on a socket, input from a user via a keyboard or mouse, and an event from CT Access. The first mechanism that CT Access provides allows the application to register the network socket and the keyboard and mouse objects with CT Access so that the user application is called when there is an event on any of these.
The second mechanism provided by CT Access allows the application to access the CT 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 CT Access internal objects.
Wait objects in CT 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 which 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 NT and OS/2, a wait object is equivalent to the MUX_HANDLE type defined in nmstypes.h.
In Windows NT, a wait object is the same type as HANDLE and is passed to either WaitForSingleObject() or WaitForMultipleObjects().
In OS/2, the wait object is the same as HEV and is passed to DosWaitEventSem(). If multiple wait objects must be waited on, then an OS/2 MuxWait Semaphore object must be created using DosCreateMuxWaitSem(). The wait objects must then be added to the list of wait objects used by the MuxWait Semaphore by calling DosAddMuxWaitSem(). The application can then wait on the list of wait objects by calling DosWaitMuxWaitSem() with the MuxWait Semaphore.

3.4.1 Wait Object Functions

The following table lists the wait object functions: If you want to... Then use this function... Obtain an operating system specific array of wait objects that CT Access is managing internally ctaQueryWaitObjects Register a wait object with CT Access ctaRegisterWaitObject Unregister a previously registered wait object ctaUnregisterWaitObject

If you want to...	Then use this function...
Obtain an operating system specific array of wait objects that CT Access is managing internally	`ctaQueryWaitObjects`
Register a wait object with CT Access	`ctaRegisterWaitObject`
Unregister a previously registered wait object	`ctaUnregisterWaitObject`

3.4.2 Wait Objects and Events Managed by CT Access

ctaRegisterWaitObject allows applications to add wait objects to the list of wait objects that it 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

CT Access gives the application's wait object a higher priority than it gives to internal CT Access wait objects

CTA_PRIORITY_NORMAL

CT Access wait objects are given higher priority than the application's wait objects.
After registering the application wait objects with CT Access, the application calls ctaWaitEvent. Whenever the application wait object is signaled, CT Access gives up the queue lock and calls the application specified callback function to handle the event. The user callback function may call any CT Access API function except ctaWaitEvent or ctaDestroyQueue. Refer to ctaRegisterWaitObject in the CT Access Function Reference Manual for more information.
The application may call ctaUnregisterWaitObject to unregister an application wait object from CT Access. Any events on the application wait object will be ignored by CT Access after it has been unregistered.

3.4.3 Wait Objects and Events Managed by the Application

CT Access also provides for a mechanism where applications may manage wait objects. On initialization, the application may specify a flag of CTA_NOTIFY_UPDATE_WAITOBJS to ctaInitialize. This flag tells CT Access to notify the application via an event whenever CT Access changes its list of internal wait objects. The event CTAEVN_UPDATE_WAITOBJS is returned to the application whenever there is a change in the list of wait objects being managed by CT Access. The application calls ctaQueryWaitObjects to get the list of wait objects that are being used by CT Access internally. The application subsequently calls the operating system dependent wait functions on their own wait objects as well as CT Access wait objects returned by ctaQueryWaitObjects.
Whenever one of the CT Access wait objects is signaled, the application should detect it and call ctaWaitEvent with a zero (0) timeout. CT Access processes the event and returns control to the application. The application must ensure that ctaWaitEvent is called promptly after a CT Access wait object is signaled.

(Page 5 of 9 in this chapter)

Tech_Support@nmss.com