InitializeEx Method

Method: Cache::InitializeEx

Summary:

InitializeEx() creates and initializes a cache object.

Syntax:

int InitializeEx (enum KeyType keyType,
                  unsigned int lenMaxStringKeyInUnits,
                  enum KeyStorageMethod keyStorageMethod,
                  bool fReplaceDuplicateKeyCacheEntry,
                  const unsigned int numSecondsTTLDefault,
                  const UINTEGER32 numDirectoryElementsToAllocate,
                  struct HashFunctionStructure pHashFunctionStructure,
                  const UINTEGER32 sizeCache,
                  enum ReplacementPolicy replacementPolicy,
                  struct GlobalConfiguration pGlobalConfiguration,
                  bool fDEBUG,
                  CLogger *pLogger);

Parameters:

1) keyType: the key type: KeyTypeByteString and KeyTypeWordString are currently supported.

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

3) keyStorageMethod: the data structure that is used when the Directory is
   instantiated. (MapHashTable is the only value that is currently supported).

4) fReplaceDuplicateKeyCacheEntry: a global setting that causes the Insert
    methods to replace duplicate key cache entries.

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

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

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

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

9) replacementPolicy: LeastRecentlyUsed or LeastFrequentlyUsed.

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

11) fDEBUG: for debugging: this will generate additional debug output.

12) pLogger: a pointer to an initialized CLogger object.

Return values:

  E_CACHE_INITIALIZATION_INVALID_KEYTYPE_FOR_MAPHASHTABLE
  E_INSUFFICIENTMEMORY
  E_CACHE_INITIALIZATION_INVALID_KEYSTORAGEMETHOD
  E_KEY_INVALIDKEYTYPE
  E_CACHE_INITIALIZATION_CACHESIZE_TOO_SMALL
  E_CACHE_INITIALIZATION_INVALID_REPLACEMENTPOLICY
  E_LOGGINGFUNCTION_MISSING
  E_SUCCESS

Remarks:

The InitializeEx() method is used to create and initialize a cache. This method also creates and initializes an internal Directory that is used by the cache.

Example

Cache *pCache = NULL;

try
{
    pCache = Cache::CacheFactory();
}
catch (std::bad_alloc)
{
    cout << "Error: insufficient memory" << endl;
}
struct HashFunctionStructure hashFunctionStructure;
hashFunctionStructure.HashFunction = &BasicHashFunction;

int iResult = pCache->InitializeEx (KeyTypeByteString,
                                    25 + 1,  // 25 characters + trailing NULL
                                    MapHashTable, // keyStorageMethod
                                    true, // fReplaceDuplicateKeyCacheEntry
                                    300,  // numSecondsTTLDefault
                                    1333, // numDirectoryElementsToAllocate
                                    &hashFunctionStructure,
                                    1000, // sizeCache
                                    LeastRecentlyUsed,
                                    NULL, // pGlobalConfiguration
                                    false, // fDEBUG
                                    NULL); // pLogger
if (iResult != E_SUCCESS)
{
    // error handling here
}