Woolz Image Processing  Version 1.7.0
AlcLRUCache

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

AlcLRUCacheAlcLRUCacheNew (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...
 
AlcLRUCItemAlcLRUCEntryAdd (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...
 
AlcLRUCItemAlcLRUCEntryAddWithKey (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...
 
AlcLRUCItemAlcLRUCItemFind (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
maxItemMaximum number of items in cache.
maxSzMaximum total cache entry size.
keyFnSupplied function for computing a numeric key from cache entries.
cmpFnSupplied function for matching cache entries.
unlinkFnOptional supplied function that is called prior to unlinking a cache item and removing it from the cache.
dstErrDestination 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
cacheThe cache.
unlinkFlag, 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
cacheThe cache.
entryGiven 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
cacheThe cache.
keyKey generated by the cache key generation function for the entry.
entryGiven 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
cacheThe cache.
entrySzSize of cache entry for use in limiting total cache entry size.
entryGiven entry to be added to the cache.
dstNewFlgDestination 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
cacheThe cache.
entrySzSize of cache entry for use in limiting total cache entry size.
entryGiven entry to be added to the cache.
keyKey for entry.
dstNewFlgDestination 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
cacheThe cache.
entryGiven 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
cacheThe cache.
keyKey generated from given entry.
entryGiven 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)
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
cacheThe cache.
keyGiven 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
cacheThe cache.
newMaxSzGiven new maximum total cache entry size.

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

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
cacheThe cache
keyKey computed from the entry.
entryPartical 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().