MICACHE Class Reference

Cache manager. More...

#include <mi32/micache.h>

Classes
class	ITEMINFO
	Information about cache item passed to ReadFunc/WriteFunc and returned by Select(). More...
Public Types
enum	SELECTFLAGS { SELECTFLAG_None = 0x0000, SELECTFLAG_NewItem = 0x0001, SELECTFLAG_NoRead = 0x0002 }
Public Member Functions
	MICACHE ()
	~MICACHE ()
ERRVALUE	Create (INT32 NumCache, MICACHEIO &ioref, INT32 NumHash=0, bool bSynchronizeAccess=false)
ERRVALUE	Create (INT32 NumCache, INT32 ItemSize, MICACHEIO &ioref, INT32 NumHash=0, bool bSynchronizeAccess=false)
ERRVALUE	Flush ()
ERRVALUE	FlushItem (INT32 ItemID)
void	Free ()
bool	IsCreated () const
ERRVALUE	Read (INT32 ItemID, INT32 Offset, INT32 NumBytes, void buffer, void UserDataPtr=0)
ERRVALUE	Read (INT32 ItemID, INT32 NumBytes, void buffer, void UserDataPtr=0)
ERRVALUE	Resize (INT32 NumCache, INT32 NumHash=0)
ERRVALUE	Select (INT32 ItemID, ITEMINFO &iteminfo, SELECTFLAGS flags=SELECTFLAG_None, void *UserDataPtr=0)
ERRVALUE	Write (INT32 ItemID, INT32 Offset, INT32 NumBytes, const void buffer, void UserDataPtr=0)
ERRVALUE	Write (INT32 ItemID, INT32 NumBytes, const void buffer, void UserDataPtr=0)

Detailed Description

Cache manager.

This class is exported from a DLL. Do not attempt to inherit from it. This class is thread safe if the Create() method is passed 'true' for the bSynchronizeAccess parameter. Thread safety is enhanced by use of exclusive locks based on the itemID passed to the Select() call. This means that only one thread at a time can access the cache item given its itemID value. Therefore it may not be necessary to use synchronization objects above the MICACHE interface. However the MICACHEIO virtual methods should use such synchronization objects as necessary, even though the itemID will be locked during the MICACHEIO::CacheLoad() and MICACHEIO::CacheSave() calls. To avoid deadlock, do not use the same synchronization objects ahead of MICACHE and in MICACHEIO.

Member Enumeration Documentation

enum MICACHE::SELECTFLAGS

Flags for Select() method.

Enumerator:

SELECTFLAG_None
SELECTFLAG_NewItem	Item is new, add to cache without checking for existence or reading.
SELECTFLAG_NoRead	Don't read item (use if plan to overwrite entirely).

Constructor & Destructor Documentation

MICACHE::MICACHE ( )

Default constructor.

This performs initialization only. Use the appropriate Create() method to actually create the cache.

MICACHE::~MICACHE ( )

Destructor.

Member Function Documentation

ERRVALUE MICACHE::Create	(	INT32	NumCache,
		MICACHEIO &	ioref,
		INT32	NumHash = `0`,
		bool	bSynchronizeAccess = `false`
	)

Create cache with entry allocation handled by programmer.

The CACHEIO.CacheLoad() method is responsible for allocating the memory for the item and must use ITEMINFO::SetMemPtr() to set the memory pointer. The CACHEIO.CacheSave() method must be implemented and is responsible for freeing the memory for the item. 'NumCache' needs to be at least as much as the number of threads that will use the cache, otherwise an ECacheItemsExhausted error may result.

Parameters:

	NumCache	Number of items to retain in cache
	NumHash	Hash table size, 0 for default
	bSynchronizeAccess	Set to 'true' if multiple threads will use this cache

ERRVALUE MICACHE::Create	(	INT32	NumCache,
		INT32	ItemSize,
		MICACHEIO &	ioref,
		INT32	NumHash = `0`,
		bool	bSynchronizeAccess = `false`
	)

Create cache with equal-sized entries.

Allocation will be handled by the MICACHE class. If items are only to be read and not modified then the CACHEIO.CacheSave() method does not need to do anything but return 0. 'NumCache' needs to be at least as much as the number of threads that will use the cache, otherwise an ECacheItemsExhausted error may result.

Parameters:

	NumCache	Number of items to retain in cache.
	ItemSize	Size of each cache item in bytes
	NumHash	Hash table size, 0 for default
	bSynchronizeAccess	Set to 'true' if multiple threads will use this cache

ERRVALUE MICACHE::Flush ( )

Flush all modified entries to external storage.

This may cause the WriteFunc callback to be invoked.

ERRVALUE MICACHE::FlushItem ( INT32 ItemID )

Flush specified item from cache.

The item may be flushed depending on the outstanding ITEMINFO instances that reference the item are still in scope. If no ITEMINFO instances referencing the item are in scope, the item will be flushed, otherwise the item will be flushed when the last ITEMINFO that references the item goes out of scope.

void MICACHE::Free ( )

Free the cache.

bool MICACHE::IsCreated ( ) const

Determine if cache has been created.

ERRVALUE MICACHE::Read	(	INT32	ItemID,
		INT32	Offset,
		INT32	NumBytes,
		void *	buffer,
		void *	UserDataPtr = `0`
	)

Read data from cache item.

An EInvalidCacheResize error will be returned if this method is called while another thread is calling Resize().

Parameters:

	ItemID	Item number to read
	Offset	Offset from start of cache item
	NumBytes	Number of bytes to read
	buffer	Buffer to read into
	UserDataPtr	User data pointer to attach to the cache item before reading

ERRVALUE MICACHE::Read	(	INT32	ItemID,
		INT32	NumBytes,
		void *	buffer,
		void *	UserDataPtr = `0`
	)

Read data from cache item.

An EInvalidCacheResize error will be returned if this method is called while another thread is calling Resize().

Parameters:

	ItemID	Item number to read
	NumBytes	Number of bytes to read
	buffer	Buffer to read into
	UserDataPtr	User data pointer to attach to the cache item before reading

ERRVALUE MICACHE::Resize	(	INT32	NumCache,
		INT32	NumHash = `0`
	)

Resize the cache.

If the number of items is less than the current number of items then the WriteFunc may be invoked. An EInvalidCacheResize error will be returned if this method is called while there are outstanding ITEMINFO instances in this or other threads.

ERRVALUE MICACHE::Select	(	INT32	ItemID,
		ITEMINFO &	iteminfo,
		SELECTFLAGS	flags = `SELECTFLAG_None`,
		void *	UserDataPtr = `0`
	)

Select cache entry for direct access.

Items selected for direct access are "locked" into memory until released. For this reason an application should not select more items than necessary and should not retain the selection outside of the function in which it is done. The selection is automatically released when the ITEMINFO is destroyed or goes out of scope. An EInvalidCacheResize error will be returned if this method is called while the Resize() method is called from another thread. An ECacheItemsExhausted error will be returned if the number of outstanding ITEMINFO's exceed the number of cache items.

Parameters:

UserDataPtr

User data pointer to attach to the cache item before reading

ERRVALUE MICACHE::Write	(	INT32	ItemID,
		INT32	Offset,
		INT32	NumBytes,
		const void *	buffer,
		void *	UserDataPtr = `0`
	)

Write data to cache item.

An EInvalidCacheResize error will be returned if this method is called while another thread is calling Resize().

Parameters:

	ItemID	Item number to write
	Offset	Offset from start of cache item
	NumBytes	Number of bytes to write
	buffer	Buffer to write from
	UserDataPtr	User data pointer to attach to the cache item before writing

ERRVALUE MICACHE::Write	(	INT32	ItemID,
		INT32	NumBytes,
		const void *	buffer,
		void *	UserDataPtr = `0`
	)

Write data to cache item.

An EInvalidCacheResize error will be returned if this method is called while another thread is calling Resize().

Parameters:

	ItemID	Item number to write
	NumBytes	Number of bytes to write
	buffer	Buffer to write from
	UserDataPtr	User data pointer to attach to the cache item before writing

The documentation for this class was generated from the following file:

mi32/micache.h

MICACHE Class Reference

Classes

Public Types

Public Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation