Controlling grammar caches

The voice browser can control grammar caches via the following means:

Setting Recognizer configuration parameters (listed below)
Setting VXIMap properties when loading, activating, and freeing grammars (properties listed below)
Setting HTTP configuration parameters on servers that supply grammars to the Recognizer (not discussed in detail below)

Configuration parameters for grammar caching

To control caching behavior, modify the following cache parameters.

Parameter
swirec_default_optimization	Specifies a default optimization level for the initial compilation of a grammar
swirec_disk_cache_enabled	Enables (or disables) the disk and inet caches.
swirec_disk_cache_low_water_mark	Largest size of the disk and inet caches after cache cleanup.
swirec_disk_cache_min_entry_size	Minimum size for entries (grammars) in the disk and inet caches.
swirec_disk_cache_size	Desired maximum size of the disk and inet caches.
swirec_full_optimization	Default optimization level for fully-optimized grammars.
swirec_hits_before_full_optimize	The number of times a grammar can be activated before the grammar gets recompiled for full optimization.
swirec_memory_cache_low_water_mark	Maximum size of the memory cache after removing grammars to create available space.
swirec_memory_cache_min_entry_size	Minimum size for memory cache entries (grammars).
swirec_memory_cache_size	Desired size of the memory cache.

Properties for grammar caching

The following cache properties can be set by VoiceXML applications or via voice browser by specifying these properties in the swirec_preload_file when loading grammars.

Property	Description
swirec_disk_cache_lock	Locks the grammar into the disk cache. When the system needs space, it will not remove locked grammars (even if swirec_disk_cache_size is exceeded) unless they become outdated and need to be updated. The default is 0. To lock, set to 1.
swirec_memory_cache_lock	Locks the grammar into the memory cache. When the system needs space, it will not remove locked grammars (even if swirec_disk_cache_size is exceeded) unless they become outdated and need to be updated. The default is 0. To lock, set to 1.
swirec_mem_flush_on_free	Circumvents the default cache management scheme by forcing the system to remove the grammar from memory as soon as the application frees the grammar; for example, at the end of a telephone call.

Locking grammars into the disk or memory cache

When loading a grammar, you can lock it into the disk or memory cache (so that it is not removed by the default caching mechanism). Locking is useful, for example, for large grammars that are costly to re-load (for example, a stock quote grammar). To do this, use, the swirec_disk_cache_lock or swirec_memory_cache_lock properties.

In general, when you lock a grammar into cache, you want to avoid unnecessary updates to the grammar. For this reason, you might want to ensure that the expiration time for the grammar is reasonably long, or use swirec_default_loadfree_properties to set the inet.maxstale property to prevent the grammar from expiring.

How the cache updates grammars automatically

When a grammar is cached, the caching mechanism must be able to determine (during load and activate operations) whether data referenced by the grammar URI has changed. If so, the cache entry become invalid and the grammar must be reloaded from the URI.

To determine cache entry validity when using file-based (non-HTTP) grammar URIs, the Nuance Recognizer implementation of the caches maintains information on the last-modified time of the grammar and its dependencies (URIs referenced in <ruleref> tags, imported grammars, and lexicons). When checking whether a grammar is in cache, modification times of the grammar file and its dependencies are also checked against modification times when the grammar was originally cached. If modification time of the grammar or any dependencies is different, then the entry is invalidated.

To determine cache validity when using HTTP-based grammar URIs, the HTTP 1.1 cache validity protocol is used by the Nuance Recognizer implementation. HTTP specifies two methods for verifying whether cache entries are invalid:

First, each cache entry contains an expiration time that was read with the original URI. A cache entry is assumed to be valid if it has not expired (if its expiration time is later than the current time).
Second, if a cache entry is expired, then HTTP can be used to determine whether the cache entry is still valid by sending the cached last-modified-time and ETAGS, a hash result of the cache entry contents, to the web server.

If the server determines that the last-modified-time of the cached entry matches the current last-modified-time of the URI contents, or if the ETAGS hash value of the cached entry matches that of the URI contents, then the server informs the inet and disk caches that the URL is still valid. If the URI of the grammar or any of its dependencies is invalid, then the inet and disk caches invalidate the cached entry and re-fetch the URI.

To minimize network traffic, configure the web server to set appropriate expiration times for most grammar files. Since no communication occurs between the inet and disk caches and the web server if a cache entry is not expired, setting non-zero expiration times can reduce HTTP polling significantly.

Forcing cache flushes

When freeing a grammar, you can force it to be flushed (removed) from the memory cache (and effectively circumvent the default cache management scheme).

To do this, specify the swirec_mem_flush_on_free property in the VXIMap argument to SWIrecGrammarFree.