In some scenarios, Pegasus may send an intermediate response to the application before the requested operation is completed and the final response (RES_DONE or RES_ERROR) is sent.
The application can choose between two different modes of receiving and handling these intermediate responses from Pegasus:
Callback function (DeferFn) mode.
- Application provides a response-handling (call back) function pointer in the PIC_PARM data. The function is called by Pegasus to send an intermediate response back to the application.
- The application logic to process the intermediate response is coded in the call back function. A nonzero return value from the call back function to Pegasus is a signal to Pegasus to abort processing. A zero return value indicates that Pegasus should continue processing
- This mode is available in all platforms and CPU architectures.
- This mode is selected by setting the F_UseDeferFn flag in PIC_PARM.Flags and assigning a value to PIC_PARM.DeferFn.
Coroutine mode.
- In this mode, the application's call to Pegasus returns whenever an intermediate response is to be sent back to the application. If the return code is different from RES_DONE or RES_ERROR, then it is an intermediate response.
- The application performs any required action, if needed, and continues processing by calling Pegasus again using a REQ_CONT request parameter or aborts processing by calling Pegasus again using a REQ_TERM request parameter.
- This is the mode whenever the F_UseDeferFn flag is not set in PIC_PARM.Flags. However, there are three different implementations of this mode:
- Based on a stack switching scheme where the opcode uses an internally-allocated stack that is distinct from the application stack (Stack Based Coroutine).
- Using a different thread to perform the opcode processing (Thread Based Coroutine).
- Using a Windows fiber to perform the opcode processing (Fiber Based Coroutine)
Not all these implementations are available in all platforms. Furthermore, the implementation that is used by default is also platform specific. Below we discuss each platform and provide basic information about trade-offs between the implementations.
- MS Window 32 and 64bit:
- Default implementation is the Stack Based Coroutine.
- Win32 Fiber Based Coroutine can be selected by setting the F_UseAlternateCoroutine flag. Of course this is available only if the OS supports Win32 fibers (Windows 2000 and later).
- Windows SEH doesn't work with Stack Based Coroutine. SEH works fine with Win32 Fiber Based Coroutine. In some scenarios, the Win32 Fiber mode could be slightly more complicated. See the F_UseAlternateCoroutine description for additional details.
- Linux 32 and 64 bit versions:
- Default implementation is the Thread Based Coroutine.
- Stack Based Coroutine can be selected by setting the F_UseStackSwitchCoroutine flag and not setting F_UseAlternateCoroutine. However Stack Based Coroutine is available only in Linux Kernels 2.4 and newer.
- Stack Based Coroutine has better speed and may use less resources than the Thread Based mode. However, Stack Based coroutine may cause spurious error reports with tools such as memory profilers.
- Solaris Intel 32 and 64 bit versions, Solaris Sparc 32 and 64 bit versions, AIX, OS X, and iOS:
- Stack Based Coroutine is the only implementation supported in these platforms.
