Resources required to complete a function or activity are allocated implicitly when the function is called, if licensed resources are available. Resources are licensed on a specified number of channels for each feature. The following functions implicitly allocate resources:

• irStartEcho(3IRAPI) – Allocates echo cancellation resources
• irStartRecog(3IRAPI) – Allocates recognition resources
• irEnd(3IRAPI) – Allocates speech play or TTS resources depending on whether play or say requests have been queued
• irRecord(3IRAPI) – Allocates speech record resources

Resources are allocated when the function is called and freed when the activity completes, as indicated through an event.

The IRP_RESOURCE_RETURNMODE parameter determines the behavior of the IRAPI when all licensed resources are busy during resource allocation. The following are valid settings for IRP_RESOURCE_RETURNMODE and the result of resource allocation failure if all resources of the requested type are busy:

• IRD_IMMEDIATE – Return IRR_FAIL
• IRD_BLOCKFOREVER – Return IRR_PENDING and wait indefinitely for IRE_GRANT
• N (where N is a timeout in milliseconds) – Return IRR_PENDING and wait up to N msec for IRE_GRANT, IRE_DENY, or corresponding IRE_<activity>_DONE event with an IREM_DENY modifier.

When a function returns IRR_PENDING, the IRAPI generates the IRE_GRANT event when the resource is granted. At that point no action is required from the application. The IRE_GRANT simply informs the application that the activity is now proceeding. If IRP_RESOURCE_RETURNMODE was set to some positive number and resources were not granted within the timeout represented by that number, the IRE_DENY event or the function specific IRE_<activity>_DONE event with the IREM_DENY modifier is generated. At that point, an application might perform some error processing under the assumption that resources will never become available.

Application developers must decide which resource return mode works best for their application. One setting may not be appropriate for all resource allocations. IRP_RESOURCE_RETURNMODE may be modified before each function call if an application is willing to wait for some resources but not for others. The following describes possible settings of IRP_RESOURCE_RETURNMODE based on application needs:

• IRD_IMMEDIATE

  If licensed resources for a feature are not available, the function call fails and the application proceeds with its normal error processing at that point. However, IRD_IMMEDIATE may force applications to fail requests that may have been blocked only for a short period of time. An application that only occasionally encounters resource contention may drop calls unnecessarily. A simple application might use this value.

• IRD_BLOCKFOREVER

  Using IRD_BLOCKFOREVER may leave callers waiting around too long rather than dropping callers too quickly (as with IRD_IMMEDIATE).

• A timeout value reasonable for the application

  Specifying a reasonable time value is perhaps the best method for an application. It allows an application to incur some delays under fairly heavy loads and to take alternate action under extreme loads. The application must be able to effectively deal with delayed resource denial.

Allocation of channels via irInit(3IRAPI) and irInitGroup(3IRAPI) follows the same resource allocation strategy. Setting the return_mode argument to these functions determines their behavior with respect to delayed channel allocation. With channel allocation, however, the IRE_CHAN_GRANT and IRE_CHAN_DENY events are used to indicate a channel grant and deny, respectively.

© 2006 Avaya Inc. All Rights Reserved.