2.2.2 Asynchronous Mode Programming

Programming in asynchronous mode in Windows is described in the following topics:

• Asynchronous Model Overview
• Asynchronous Model with Event Handlers
• Asynchronous with Windows Callback Model
• Asynchronous with Win32 Synchronization Model
• Extended Asynchronous Programming Model

2.2.2.1 Asynchronous Model Overview

Asynchronous mode programming is characterized by the calling thread performing other processing while a function executes. At completion, the application receives event notification from the SRL and then the thread continues processing the call on a particular channel.

A function called in the asynchronous mode returns control immediately after the request is passed to the device driver and allows thread processing to continue. A termination event is returned when the requested operation completes, thus allowing the Intel® Dialogic operation (state machine processing) to continue.

Caution: In general, when a function is called in asynchronous mode, and an associated termination event exists, the gc_Close( ) function should not be called until the termination event has been received. In order to disable gc_WaitCall( ), gc_ResetLineDev( ) should be called. If this is not done, there are potential race conditions under which the application may crash with a segmentation fault.

Functions may be initiated asynchronously from a single thread and/or the completion (termination) event can be picked up by the same or a different thread that calls the sr_waitevt( ) and gc_GetMetaEvent( ) functions. When these functions return with an event, the event information is stored in the METAEVENT data structure. The event information retrieved determines the exact event that occurred and is valid until the sr_waitevt( ) and gc_GetMetaEvent( ) functions are called again.

For Windows environments, the asynchronous models provided for application development also include:

• combined synchronous and asynchronous programming; see Section 2.2.1, "Synchronous Mode Programming"
• asynchronous model with event handlers
• asynchronous with Windows callback
• asynchronous with Win32 synchronization
• extended asynchronous programming

The asynchronous programming models are recommended for more complex applications that require coordinating multiple tasks. Asynchronous model applications typically run faster than synchronous models and require lower levels of system resources. Asynchronous models reduce processor loading because of the reduced number of threads inherent in asynchronous models and the elimination of scheduling overhead. Asynchronous models use processor resources more efficiently because multiple channels are handled in a single thread or in a few threads. See Section 6.1, "General Programming Tips" for details. Of the asynchronous models, the asynchronous with SRL callback model and the asynchronous with Windows callback model provide the tightest integration with the Windows message/event mechanism. Asynchronous model applications are typically more complex than corresponding synchronous model applications due to a higher level of resource management (that is, the number of channels managed by a thread and the tracking of completion events) and the development of a state machine.

After the application issues an asynchronous function, the application uses the sr_waitevt( ) function to wait for events on Intel® Dialogic devices. All event coding can be accomplished using switch statements in the main thread. When an event is available, event information may be retrieved using the gc_GetMetaEvent( ) function. Retrieved event information is valid until the sr_waitevt( ) function is called again. The asynchronous model does not use event handlers to process events.

In this model, the SRL handler thread must be initiated by the application by setting the SR_MODELTYPE value to SR_STASYNC.

2.2.2.2 Asynchronous Model with Event Handlers

The asynchronous with event handlers model uses the sr_enbhdlr( ) function to automatically create the SRL handler thread. The application does not need to call the sr_waitevt( ) function since the thread created by the sr_enbhdlr( ) already calls the sr_waitevt( ) function to get events. Each call to the sr_enbhdlr( ) function allows the Intel® Dialogic events to be serviced when the operating system schedules the SRL handler thread for execution.

Note: The SR_MODELTYPE value must not be set to SR_STASYNC because the SRL handler thread must be created by the sr_enbhdlr( ) call. The event handler must not call the sr_waitevt( ) function or any synchronous Intel® Dialogic function.

Individual handlers can be written to handle events for each channel. The SRL handler thread can be used when porting applications developed for other operating systems.

2.2.2.3 Asynchronous with Windows Callback Model

The asynchronous with Windows callback model allows an asynchronous application to receive SRL event notification through the standard Windows message handling scheme. This model is used to achieve the tightest possible integration with the Windows messaging scheme. Using this model, the entire Intel® Dialogic portion of the application could be run on a single thread. This model calls the sr_NotifyEvt( ) function once to define a user-specified application window handle and a user-specified message type. When an event is detected, a message is sent to the application window. The application responds by calling the sr_waitevt( ) function with a 0 timeout value. For Global Call events and optionally for non-Global Call events, the application must then call the gc_GetMetaEvent( ) function before servicing the event.

In this model, the SRL event handler thread must be initiated by the application by setting the SR_MODELTYPE value to SR_STASYNC. For detailed information on this programming model, see the Standard Runtime Library (SRL) Programming Guide for your operating system.

2.2.2.4 Asynchronous with Win32 Synchronization Model

The asynchronous with Win32 synchronization model allows an asynchronous application to receive SRL event notification through standard Windows synchronization mechanisms. This model uses one thread to run all Intel® Dialogic devices and thus requires a lower level of system resources than the synchronous model. This model allows for greater scalability in growing systems. For detailed information on this programming model, see the Standard Runtime Library (SRL) Programming Guide for your operating system.

2.2.2.5 Extended Asynchronous Programming Model

The extended asynchronous programming model is basically the same as the asynchronous model except that the application uses multiple asynchronous threads, each of which controls multiple devices. In this model, each thread has its own specific state machine for the devices that it controls. Thus, a single thread can look for separate events for more than one group of channels. This model may be useful, for example, when you have one group of devices that provides fax services and another group that provides interactive voice response (IVR) services, while both groups share the same process space and database resources. The extended asynchronous model can be used when an application needs to wait for events from more than one group of devices and requires a state machine.

Because the extended asynchronous model uses only a few threads for all Intel® Dialogic devices, it requires a lower level of system resources than the synchronous model. This model also enables using only a few threads to run the entire Intel® Dialogic portion of the application.

Whereas default asynchronous programming uses the sr_waitevt( ) function to wait for events specific to one device, extended asynchronous programming uses the sr_waitevtEx( ) function to wait for events specific to a number of devices (channels).

Note: Do not use the sr_waitevtEx( ) function in combination with either the sr_waitevt( ) function or event handlers.

This model can run an entire application using only a few threads. When an event is available, the gc_GetMetaEventEx( ) function must be used to retrieve event-specific information. The values returned are valid until the sr_waitevtEx( ) function is called again. Event commands can be executed from the main thread through switch statements; the events are processed immediately.

The extended asynchronous model calls the sr_waitevtEx( ) function for a group of devices (channels) and polls for (waits for) events specific to that group of devices. In this model, the SRL event handler thread is not created (the SR_MODELTYPE value is set to SR_STASYNC) and the sr_enbhdlr( ) function in not used.

In the extended asynchronous model, functions are initiated asynchronously from different threads. A thread waits for events using the sr_waitevtEx( ) function. The event information can be retrieved using the gc_GetMetaEventEx( ) function. When this function returns, the event information is stored in the METAEVENT data structure.

Caution: When calling the gc_GetMetaEventEx( ) function from multiple threads, ensure that your application uses unique thread-related METAEVENT data structures (thread local variables or local variables), or ensure that the METAEVENT data structure is not overwritten until all processing of the current event has completed.

The event information retrieved determines the exact event that occurred and is valid until the sr_waitevtEx( ) function returns with another event.

Click here to contact Telecom Support Resources