Files
file	AlcLRUCache.c
	A cache allowing rank and key access to it's entries. The cache is maintained using a maximum number of items and maximum total entry size.

Data Structures
struct	_AlcLRUCItem
	A cache item for a AlcLRUCache. Typedef: AlcLRUCItem. More...

struct	_AlcLRUCache
	A least recent use removal cache allowing rank and random access to it's entries. Rank access is via a doubly linked list (using rankPrv and rankNxt), while random access is via hash table (using the item's key and hashNxt). The cache will unlink items as required to maintain the set maximum number of entries and maximum total entry size. Typedef: AlcLRUCache. More...

Typedefs
typedef unsigned int(*	AlcLRUCKeyFn) (struct _AlcLRUCache , void )
	Function called to compute a AlcLRUCache item's numeric key given it's entry. The required function parameters are the cache and the entry. More...

typedef int(*	AlcLRUCCmpFn) (const void , const void )
	Function called to compare two entries in a AlcLRUCache. This function must return zero only iff the two entries match. The required function parameters are the two cache entry data structures with sufficient fields set to make a comparison. More...

Functions
AlcLRUCache *	AlcLRUCacheNew (unsigned int maxItem, size_t maxSz, AlcLRUCKeyFn keyFn, AlcLRUCCmpFn cmpFn, AlcLRUCUnlinkFn unlinkFn, AlcErrno *dstErr)
	Allocates a new least recent use removal cache. More...

void	AlcLRUCacheFree (AlcLRUCache *cache, int unlink)
	Frees a least recent use removal cache. More...

void *	AlcLRUCEntryGet (AlcLRUCache cache, void entry)
	Given a cache entry (with sufficient data in the entry for the cache key generation function) this function attempts to find a matching entry in the cache. The partical entry could for example contain only an identification string if that is all that is required for key generation and entry comparison. If the entry exists in the cache then it become the most recently used entry. See AlcLRUCEntryGetWithKey(). More...

void *	AlcLRUCEntryGetWithKey (AlcLRUCache cache, unsigned int key, void entry)
	Given a cache entry with sufficient data in the entry for the cache key generation function, this function attempts to find the matching cache entry. The partical entry could for example contain only an identification string if that is all that is required for entry comparison. If The given key is used to search the cache for entries with the same key. These are then checked using the cache entry comparison function. If the entry exists in the cache then it become the most recently used entry. More...

AlcLRUCItem *	AlcLRUCEntryAdd (AlcLRUCache cache, size_t entrySz, void entry, int *dstNewFlg)
	Attempts to add the given entry to the cache. If the entry already exists in the cache then it become the most recently used entry, but is not modified. More...

AlcLRUCItem *	AlcLRUCEntryAddWithKey (AlcLRUCache cache, size_t entrySz, void entry, unsigned int key, int *dstNewFlg)
	Attempts to add the given entry to the cache. If the entry already exists in the cache then it become the most recently used entry. More...

void	AlcLRUCEntryRemove (AlcLRUCache cache, void entry)
	Removes the matching cache entry from the queue. See AlcLRUCEntryGet() for the entry use. More...

void	AlcLRUCEntryRemoveWithKey (AlcLRUCache cache, unsigned int key, void entry)
	Removes the matching cache entry from the queue. See AlcLRUCEntryGetWithKey() for the entry use. More...

void	AlcLRUCEntryRemoveAll (AlcLRUCache *cache)
	Removes all cache entries. More...

unsigned int	AlcLRUCKeyGetNHashItem (AlcLRUCache *cache, unsigned int key)
	Returns the number of items in the hash bin corresponding to the given item key value. This is probably only useful for debug and tuning. More...

void	AlcLRUCacheMaxSz (AlcLRUCache *cache, size_t newMaxSz)
	Set a new maximum total cache entry size. More...

void	AlcLRUCacheFacts (AlcLRUCache cache, FILE fP)
	Prints a dump of the current cache status to a file. This is only intended for debug and tuning. More...

AlcLRUCItem *	AlcLRUCItemFind (AlcLRUCache cache, unsigned int key, void entry)
	Finds the cache item which matches the given entry. More...

Detailed Description

Typedef Documentation

AlcLRUCKeyFn

Function called to compute a AlcLRUCache item's numeric key given it's entry. The required function parameters are the cache and the entry.

AlcLRUCCmpFn

Function called to compare two entries in a AlcLRUCache. This function must return zero only iff the two entries match. The required function parameters are the two cache entry data structures with sufficient fields set to make a comparison.

Function called when a AlcLRUCache item is unlinked and removed from the cache. It may be used, for example, to free the item's entry. The required function parameters are the cache and the entry that will be unlinked and removed.

Function Documentation

AlcLRUCache* AlcLRUCacheNew	(	unsigned int	maxItem,
		size_t	maxSz,
		AlcLRUCKeyFn	keyFn,
		AlcLRUCCmpFn	cmpFn,
		AlcLRUCUnlinkFn	unlinkFn,
		AlcErrno *	dstErr
	)

Allocates a new least recent use removal cache.

Returns: New least recent use cache or NULL on error.

Parameters

maxItem	Maximum number of items in cache.
maxSz	Maximum total cache entry size.
keyFn	Supplied function for computing a numeric key from cache entries.
cmpFn	Supplied function for matching cache entries.
unlinkFn	Optional supplied function that is called prior to unlinking a cache item and removing it from the cache.
dstErr	Destination error pointer, may be NULL.

References ALC_ER_ALLOC, ALC_ER_NONE, AlcCalloc(), AlcFree(), _AlcLRUCache::cmpFn, _AlcLRUCache::hashTbl, _AlcLRUCache::hashTblSz, _AlcLRUCache::itemBlkSz, _AlcLRUCache::keyFn, _AlcLRUCache::maxItem, _AlcLRUCache::maxSz, and _AlcLRUCache::unlinkFn.

void AlcLRUCacheFree	(	AlcLRUCache *	cache,
		int	unlink
	)

Frees a least recent use removal cache.

Parameters

cache	The cache.
unlink	Flag, which if non-zero, will remove all items from the cache before freeing the cache. If the unlink function is to be called for the item entries as they are removed from the cache then this flag must be set.

References AlcBlockStackFree(), AlcFree(), AlcLRUCEntryRemoveAll(), _AlcLRUCache::freeStack, and _AlcLRUCache::hashTbl.

void* AlcLRUCEntryGet	(	AlcLRUCache *	cache,
		void *	entry
	)

Given a cache entry (with sufficient data in the entry for the cache key generation function) this function attempts to find a matching entry in the cache. The partical entry could for example contain only an identification string if that is all that is required for key generation and entry comparison. If the entry exists in the cache then it become the most recently used entry. See AlcLRUCEntryGetWithKey().

Returns: Cache entry or NULL if not found.

Parameters

cache	The cache.
entry	Given partial cache entry to be matched.

References AlcLRUCEntryGetWithKey(), and _AlcLRUCache::keyFn.

void* AlcLRUCEntryGetWithKey	(	AlcLRUCache *	cache,
		unsigned int	key,
		void *	entry
	)

Given a cache entry with sufficient data in the entry for the cache key generation function, this function attempts to find the matching cache entry. The partical entry could for example contain only an identification string if that is all that is required for entry comparison. If The given key is used to search the cache for entries with the same key. These are then checked using the cache entry comparison function. If the entry exists in the cache then it become the most recently used entry.

Returns: Cache entry or NULL if not found.

Parameters

cache	The cache.
key	Key generated by the cache key generation function for the entry.
entry	Given partial cache entry to be matched.

References AlcLRUCItemFind(), and _AlcLRUCItem::entry.

Referenced by AlcLRUCEntryGet().

AlcLRUCItem* AlcLRUCEntryAdd	(	AlcLRUCache *	cache,
		size_t	entrySz,
		void *	entry,
		int *	dstNewFlg
	)

Attempts to add the given entry to the cache. If the entry already exists in the cache then it become the most recently used entry, but is not modified.

Returns: The cache item or NULL if not in cache on return.

Parameters

cache	The cache.
entrySz	Size of cache entry for use in limiting total cache entry size.
entry	Given entry to be added to the cache.
dstNewFlg	Destination pointer set to zero or non-zero. Set to non-zero only if a new item is created. May be NULL.

References AlcLRUCItemFind(), _AlcLRUCache::curSz, _AlcLRUCItem::entry, _AlcLRUCItem::key, _AlcLRUCache::keyFn, _AlcLRUCache::maxSz, _AlcLRUCache::numItem, and _AlcLRUCItem::sz.

AlcLRUCItem* AlcLRUCEntryAddWithKey	(	AlcLRUCache *	cache,
		size_t	entrySz,
		void *	entry,
		unsigned int	key,
		int *	dstNewFlg
	)

Attempts to add the given entry to the cache. If the entry already exists in the cache then it become the most recently used entry.

Returns: The cache item or NULL if not in cache on return.

Parameters

cache	The cache.
entrySz	Size of cache entry for use in limiting total cache entry size.
entry	Given entry to be added to the cache.
key	Key for entry.
dstNewFlg	Destination pointer set to zero or non-zero. Set to non-zero only if a new item is created. May be NULL.

References AlcLRUCItemFind(), _AlcLRUCache::curSz, _AlcLRUCItem::entry, _AlcLRUCItem::key, _AlcLRUCache::maxSz, _AlcLRUCache::numItem, and _AlcLRUCItem::sz.

void AlcLRUCEntryRemove	(	AlcLRUCache *	cache,
		void *	entry
	)

Removes the matching cache entry from the queue. See AlcLRUCEntryGet() for the entry use.

Parameters

cache	The cache.
entry	Given partial cache entry to be matched.

References AlcLRUCEntryRemoveWithKey(), and _AlcLRUCache::keyFn.

void AlcLRUCEntryRemoveWithKey	(	AlcLRUCache *	cache,
		unsigned int	key,
		void *	entry
	)

Removes the matching cache entry from the queue. See AlcLRUCEntryGetWithKey() for the entry use.

Parameters

cache	The cache.
key	Key generated from given entry.
entry	Given partial cache entry to be matched.

References AlcLRUCItemFind(), _AlcLRUCache::curSz, _AlcLRUCItem::entry, _AlcLRUCache::numItem, _AlcLRUCItem::sz, and _AlcLRUCache::unlinkFn.

Referenced by AlcLRUCEntryRemove().

void AlcLRUCEntryRemoveAll ( AlcLRUCache * cache )

Removes all cache entries.

Parameters

cache The cache.

References _AlcLRUCache::curSz, _AlcLRUCItem::entry, _AlcLRUCache::hashTbl, _AlcLRUCache::hashTblSz, _AlcLRUCache::numItem, _AlcLRUCache::rankHead, _AlcLRUCItem::rankNxt, and _AlcLRUCache::unlinkFn.

Referenced by AlcLRUCacheFree().

unsigned int AlcLRUCKeyGetNHashItem	(	AlcLRUCache *	cache,
		unsigned int	key
	)

Returns the number of items in the hash bin corresponding to the given item key value. This is probably only useful for debug and tuning.

Returns: Number of items.

Parameters

cache	The cache.
key	Given item key value.

References _AlcLRUCItem::hashNxt, _AlcLRUCache::hashTbl, and _AlcLRUCache::hashTblSz.

void AlcLRUCacheMaxSz	(	AlcLRUCache *	cache,
		size_t	newMaxSz
	)

Set a new maximum total cache entry size.

Parameters

cache	The cache.
newMaxSz	Given new maximum total cache entry size.

References _AlcLRUCache::curSz, _AlcLRUCache::maxSz, and _AlcLRUCache::rankTail.

void AlcLRUCacheFacts	(	AlcLRUCache *	cache,
		FILE *	fP
	)

Prints a dump of the current cache status to a file. This is only intended for debug and tuning.

Parameters

cache	The cache.
fP	File pointer opened for writing.

References AlcBlockStackNew(), _AlcLRUCache::cmpFn, _AlcLRUCache::curSz, _AlcBlockStack::elements, _AlcLRUCItem::entry, _AlcLRUCache::freeList, _AlcLRUCache::freeStack, _AlcLRUCItem::hashNxt, _AlcLRUCache::hashTbl, _AlcLRUCache::hashTblSz, _AlcLRUCache::itemBlkSz, _AlcLRUCItem::key, _AlcLRUCache::keyFn, _AlcBlockStack::maxElm, _AlcLRUCache::maxItem, _AlcLRUCache::maxSz, _AlcLRUCache::numItem, _AlcLRUCache::rankHead, _AlcLRUCItem::rankNxt, _AlcLRUCItem::rankPrv, _AlcLRUCache::rankTail, _AlcLRUCItem::sz, and _AlcLRUCache::unlinkFn.

AlcLRUCItem* AlcLRUCItemFind	(	AlcLRUCache *	cache,
		unsigned int	key,
		void *	entry
	)

Finds the cache item which matches the given entry.

Returns: Found cache item or NULL if no match found.

Parameters

cache	The cache
key	Key computed from the entry.
entry	Partical entry to match which must have sufficient information for the cache entry comparison function.

References _AlcLRUCache::cmpFn, _AlcLRUCache::curSz, _AlcLRUCItem::entry, _AlcLRUCItem::hashNxt, _AlcLRUCache::hashTbl, _AlcLRUCache::hashTblSz, _AlcLRUCItem::key, _AlcLRUCache::numItem, _AlcLRUCItem::sz, and _AlcLRUCache::unlinkFn.

Referenced by AlcLRUCEntryAdd(), AlcLRUCEntryAddWithKey(), AlcLRUCEntryGetWithKey(), and AlcLRUCEntryRemoveWithKey().

Files

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation