Normally the cache implementation can choose to discard the data between the write and the read when necessary (due to running out of cache space, etc.), but it is also possible for clients to lock data in the cache to support built-in grammars and other data that is explicitly provisioned by system administrators and thus must not be removed unless by explicit system administrator command.
The interface is a synchronous interface based on the ANSI/ISO C standard file I/O interface. The client of the interface may use this in an asynchronous manner by using non-blocking I/O operations, creating threads, or by invoking this from a separate server process.
Typically the key name specified by clients will be the URL to the source form of the data that is being written back, such as the URL to the grammar text being used as the key name for the compiled grammar. In the case where the VXIinet and VXIcache implementations share the same underlying cache storage, it is thus necessary to use prefixes or some other namespace mechanism to avoid collisions with the cache entry for the original URL.
However, the key names specified by clients may be very large in some cases. This is most common when writing back data generated from in-memory source text, such as when writing back the compiled grammar for a VoiceXML document in-line grammar. One possible VXIcache implementation approach is to use the MD5 algorithm as used in HTTP message headers (specified in RFC 1321 with a full implementation provided) to convert long key names to a 16 byte MD5 value for indexing purposes, using Base64 encoding to convert the binary MD5 value to ASCII text if desired (as done in HTTP message headers).
There is one cache interface per thread/line.
Classes | |
struct | VXIcacheInterface |
Abstract interface for accessing caching functionality. More... | |
Cache Flags | |
Set of flags which control the caching behavior of the data put into the cache.
The Open() call takes bitwise or of cache flags which control the caching behavior of data which is written or read from the cache. | |
#define | CACHE_FLAG_NULL 0x0 |
Null flag. | |
#define | CACHE_FLAG_LOCK 0x2 |
Never flush from the cache. | |
#define | CACHE_FLAG_LOCK_MEMORY 0x4 |
Never flush from memory. | |
#define | CACHE_FLAG_NONBLOCKING_IO 0x8 |
Non-blocking reads/writes. | |
Cache Open Properties | |
Set of properties that are returned on the Open() of an existing cache entry.
The Open() call returns a VXIMap which contains a set of key/value properties. This set of defines provides the definition of the properties that must be supported by an implementation of Open(). | |
#define | CACHE_INFO_FINAL_KEY L"cache.info.finalKey" |
Final key name used for storing the cache entry. | |
#define | CACHE_INFO_LAST_MODIFIED L"cache.info.lastModified" |
Last Modifed time. | |
#define | CACHE_INFO_SIZE_BYTES L"cache.info.sizeBytes" |
Size in bytes. | |
Defines | |
#define | CACHE_CREATION_COST L"cache.creationCost" |
#define | CACHE_CREATION_COST_DEFAULT CACHE_CREATION_COST_LOW |
Default cache creation cost. | |
#define | CACHE_OPENEX_SUPPORTED(cacheIntf) (cacheIntf->GetVersion( ) >= 0x00010001) |
#define | CACHE_CLOSEEX_SUPPORTED(cacheIntf) (cacheIntf->GetVersion( ) >= 0x00010001) |
#define | CACHE_UNLOCKEX_SUPPORTED(cacheIntf) (cacheIntf->GetVersion( ) >= 0x00010001) |
#define | CACHE_MODE_READ_CREATE_SUPPORTED(cacheIntf) (cacheIntf->GetVersion( ) >= 0x00010001) |
Typedefs | |
typedef enum VXIcacheCreationCost | VXIcacheCreationCost |
Provides a hint on how much CPU/time went into creating the object being written cache. | |
typedef enum VXIcacheOpenMode | VXIcacheOpenMode |
Mode values for VXIcache::Open( ) Open supports ANSI/ISO C standard I/O open modes. | |
typedef enum VXIcacheResult | VXIcacheResult |
VXIcache return codes. | |
typedef VXIcacheInterface | VXIcacheInterface |
Abstract interface for accessing caching functionality. | |
Enumerations | |
enum | VXIcacheCreationCost { CACHE_CREATION_COST_EXTREME = 40, CACHE_CREATION_COST_HIGH = 30, CACHE_CREATION_COST_MEDIUM = 20, CACHE_CREATION_COST_LOW = 10, CACHE_CREATION_COST_FETCH = 0 } |
Provides a hint on how much CPU/time went into creating the object being written cache. More... | |
enum | VXIcacheOpenMode { CACHE_MODE_READ = 0x0, CACHE_MODE_WRITE = 0x1, CACHE_MODE_READ_CREATE = 0x2 } |
Mode values for VXIcache::Open( ) Open supports ANSI/ISO C standard I/O open modes. More... | |
enum | VXIcacheResult { VXIcache_RESULT_FATAL_ERROR = -100, VXIcache_RESULT_IO_ERROR = -8, VXIcache_RESULT_OUT_OF_MEMORY = -7, VXIcache_RESULT_SYSTEM_ERROR = -6, VXIcache_RESULT_PLATFORM_ERROR = -5, VXIcache_RESULT_BUFFER_TOO_SMALL = -4, VXIcache_RESULT_INVALID_PROP_NAME = -3, VXIcache_RESULT_INVALID_PROP_VALUE = -2, VXIcache_RESULT_INVALID_ARGUMENT = -1, VXIcache_RESULT_SUCCESS = 0, VXIcache_RESULT_FAILURE = 1, VXIcache_RESULT_NON_FATAL_ERROR = 2, VXIcache_RESULT_NOT_FOUND = 50, VXIcache_RESULT_WOULD_BLOCK = 53, VXIcache_RESULT_END_OF_STREAM = 54, VXIcache_RESULT_EXCEED_MAXSIZE = 55, VXIcache_RESULT_ENTRY_LOCKED = 56, VXIcache_RESULT_ENTRY_CREATED = 57, VXIcache_RESULT_UNSUPPORTED = 100 } |
VXIcache return codes. More... |
|
|
|
|
|
Default cache creation cost.
|
|
Never flush from the cache. This locks the file on disk for the duration of the process. This flag may be bitwise combined through OR with the other CACHE_FLAG defines in the call to Open(). |
|
Never flush from memory. This locks the data in memory. This lock option is only a hint, some implementations may ignore this and interpret it as CACHE_FLAG_LOCK. |
|
Non-blocking reads/writes. Do all I/O using non-blocking operations. |
|
Null flag. This causes the cache to use its default behavior on cache locking and management |
|
Final key name used for storing the cache entry. This may differ from the original key name specified for Open( ) in cases where that original key name was very large and the implementation used a MD5 digest or other mechanism to compress it. While the user may still obtain access to the entry using the original key name, it may opt to use this final key name instead in order to reduce its own memory use. This is returned as a VXIString. |
|
Last Modifed time. This is a property in the VXIMap used to return cache information on Open(). It returns the last modified date and time for the entry. This is returned as a VXIInteger. |
|
Size in bytes. This property of the VXIMap is used to return cache information on the size of the cache entry in bytes as a VXIInteger. |
|
|
|
|
|
|
|
Provides a hint on how much CPU/time went into creating the object being written cache. Enumerated CACHE_CREATION_COST property values. The creation costs property permits prioritizing the cache so low cost objects are flushed before high cost objects (for example, try to keep compiled grammars which have a high creation cost over keeping audio recordings that were simply fetched). Note that implementations may ignore this hint. |
|
Abstract interface for accessing caching functionality. Permits writing arbitrary data into the cache with a client supplied key name, then retrieving that data from the cache one or more times by reading against that key name. |
|
Mode values for VXIcache::Open( ) Open supports ANSI/ISO C standard I/O open modes.
|
|
VXIcache return codes. Result codes less then zero are severe errors (likely to be platform faults), those greater then zero are warnings (likely to be application issues) |
|
Provides a hint on how much CPU/time went into creating the object being written cache. Enumerated CACHE_CREATION_COST property values. The creation costs property permits prioritizing the cache so low cost objects are flushed before high cost objects (for example, try to keep compiled grammars which have a high creation cost over keeping audio recordings that were simply fetched). Note that implementations may ignore this hint. |
|
Mode values for VXIcache::Open( ) Open supports ANSI/ISO C standard I/O open modes.
|
|