Initialize Method

Method: Cache::Initialize

Summary:

Initialize() creates and initializes a cache object.

Syntax:

int Initialize (unsigned int lenMaxStringKeyInUnits,
                const unsigned int numSecondsTTLDefault,
                const UINTEGER32 numDirectoryElementsToAllocate,
                struct HashFunctionStructure *pHashFunctionStructure,
                const UINTEGER32 sizeCache,
                enum ReplacementPolicy replacementPolicy,
                struct GlobalConfiguration *pGlobalConfiguration) = 0;

Parameters:

1) lenMaxStringKeyInUnits: the maximum length of a key that is passed as a parameter
   to a basic operation method; for Initialize() this is a length in bytes. This value
   must include space for a null-terminator byte if one is needed. For example: if the
   max key length in bytes is 128, including space for a null terminator, 
   lenMaxStringKeyInUnits must be 128.

2) numSecondsTTLDefault: the default Time-to-live (TTL) value.

3) numDirectoryElementsToAllocate: (for the Directory, when instantiated as a hash
   table) - the size of the directory (map). A typical value would be 133% the size
   of the cache. (E.g. if cache size = 1000, this would be 1333).

4) pHashFunctionStructure: this pointer must point to a HashFunctionStructure that has
    been initialized with a hash function.

5) sizeCache: the number of entries (array elements) of the cache.

6) replacementPolicy: LeastRecentlyUsed or LeastFrequentlyUsed.

7) pGlobalConfiguration: a pointer to a GlobalConfiguration structure (this value may be
    NULL if custom global configuration settings are not needed).

Return values:

  E_INSUFFICIENTMEMORY
  E_KEY_INVALIDKEYTYPE
  E_CACHE_INITIALIZATION_CACHESIZE_TOO_SMALL
  E_CACHE_INITIALIZATION_INVALID_REPLACEMENTPOLICY
  E_SUCCESS

Remarks:

The Initialize() method is used to create and initialize a cache. This method also creates and initializes an internal Directory that is used by the cache. The Initialize() method creates a cache that only accepts byte (character) string keys; to use wide char string keys the InitializeEx() method must be used.

Example

Cache *pCache = NULL;

try
{
    pCache = Cache::CacheFactory();
}
catch (std::bad_alloc)
{
    cout << "Error: insufficient memory" << endl;
}

pCache = Cache::CacheFactory();

int iResult = pCache->Initialize (25 + 1, // lenMaxStringKey
                                          // (25 characters + trailing NULL)
                                  300,    // numSecondsTTLDefault
                                  20,     // numDirectoryElementsToAllocate
                                  NULL,   // pHashFunctionStructure
                                  10,     // sizeCache
                                  LeastRecentlyUsed, // replacementPolicy
                                  NULL);  // pGlobalConfiguration
if (iResult != E_SUCCESS)
{
    // error handling here
}