Main Page | Modules | Namespace List | Class Hierarchy | Class List | File List | Class Members | File Members

Cache Interface


Detailed Description

Abstract interface for accessing caching functionality, which 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.

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...


Define Documentation

#define CACHE_CLOSEEX_SUPPORTED cacheIntf   )     (cacheIntf->GetVersion( ) >= 0x00010001)
 

#define CACHE_CREATION_COST   L"cache.creationCost"
 

#define CACHE_CREATION_COST_DEFAULT   CACHE_CREATION_COST_LOW
 

Default cache creation cost.

#define CACHE_FLAG_LOCK   0x2
 

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().

#define CACHE_FLAG_LOCK_MEMORY   0x4
 

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.

#define CACHE_FLAG_NONBLOCKING_IO   0x8
 

Non-blocking reads/writes.

Do all I/O using non-blocking operations.

#define CACHE_FLAG_NULL   0x0
 

Null flag.

This causes the cache to use its default behavior on cache locking and management

#define CACHE_INFO_FINAL_KEY   L"cache.info.finalKey"
 

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.

#define CACHE_INFO_LAST_MODIFIED   L"cache.info.lastModified"
 

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.

#define CACHE_INFO_SIZE_BYTES   L"cache.info.sizeBytes"
 

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.

#define CACHE_MODE_READ_CREATE_SUPPORTED cacheIntf   )     (cacheIntf->GetVersion( ) >= 0x00010001)
 

#define CACHE_OPENEX_SUPPORTED cacheIntf   )     (cacheIntf->GetVersion( ) >= 0x00010001)
 

#define CACHE_UNLOCKEX_SUPPORTED cacheIntf   )     (cacheIntf->GetVersion( ) >= 0x00010001)
 


Typedef Documentation

typedef enum VXIcacheCreationCost VXIcacheCreationCost
 

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.

typedef struct VXIcacheInterface VXIcacheInterface
 

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.

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.

Result codes less then zero are severe errors (likely to be platform faults), those greater then zero are warnings (likely to be application issues)


Enumeration Type Documentation

enum VXIcacheCreationCost
 

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.

Enumeration values:
CACHE_CREATION_COST_EXTREME  Extremely high.
CACHE_CREATION_COST_HIGH  High.
CACHE_CREATION_COST_MEDIUM  Medium.
CACHE_CREATION_COST_LOW  Low.
CACHE_CREATION_COST_FETCH  Only the cost of a fetch.

enum VXIcacheOpenMode
 

Mode values for VXIcache::Open( ) Open supports ANSI/ISO C standard I/O open modes.

Enumeration values:
CACHE_MODE_READ  Open for reading.
CACHE_MODE_WRITE  Open for writing.
CACHE_MODE_READ_CREATE  Atomic operation to open for reading if the entry exists (VXIcache_RESULT_SUCCESS returned), otherwise open it for writing (VXIcache_RESULT_ENTRY_CREATED returned).

This is only available as of version 1.1 of the VXIcacheInterface, use CACHE_MODE_READ_CREATE_SUPPORTED( ) to determine availability.

enum VXIcacheResult
 

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)

Enumeration values:
VXIcache_RESULT_FATAL_ERROR  Fatal error, terminate call.
VXIcache_RESULT_IO_ERROR  I/O error.
VXIcache_RESULT_OUT_OF_MEMORY  Out of memory.
VXIcache_RESULT_SYSTEM_ERROR  System error, out of service.
VXIcache_RESULT_PLATFORM_ERROR  Errors from platform services.
VXIcache_RESULT_BUFFER_TOO_SMALL  Return buffer too small.
VXIcache_RESULT_INVALID_PROP_NAME  Property name is not valid.
VXIcache_RESULT_INVALID_PROP_VALUE  Property value is not valid.
VXIcache_RESULT_INVALID_ARGUMENT  Invalid function argument.
VXIcache_RESULT_SUCCESS  Success.
VXIcache_RESULT_FAILURE  Normal failure, nothing logged.
VXIcache_RESULT_NON_FATAL_ERROR  Non-fatal non-specific error.
VXIcache_RESULT_NOT_FOUND  Named data not found.
VXIcache_RESULT_WOULD_BLOCK  I/O operation would block.
VXIcache_RESULT_END_OF_STREAM  End of stream.
VXIcache_RESULT_EXCEED_MAXSIZE  Buffer exceeds maximum size.
VXIcache_RESULT_ENTRY_LOCKED  Entry in the cache in currently in used and is locked.
VXIcache_RESULT_ENTRY_CREATED  CACHE_MODE_READ_WRITE requested and the entry did not exist so a write stream to the new entry is being returned.
VXIcache_RESULT_UNSUPPORTED  Operation is not supported.


Generated on Wed Jun 1 12:50:19 2005 for OpenVXI by  doxygen 1.4.2