libcache(3) BSD Library Functions Manual libcache(3)NAME
libcache -- the caching framework
SYNOPSIS
#include <cache.h>
DESCRIPTION
The libcache framework provides a facility for creating in memory data caches. Each cache is a mutable dictionary that associates values
with their keys. A cache limits the number of values it keeps according to available system memory and selects values to evict when the
limit is exceeded. Recently and frequently used values are less likely to be selected for eviction.
Cache keys and values should be cast as pointers. The framework provides a callback interface for supporting arbitrary types of keys and
values and implements callback functions for common types. See cache_callbacks(3) for more information.
Clients retrieve a value previously added to a cache using the value's key. When the client gets a value, the cache increments a reference
count on the value. When the client finishes with a value retrieved from a cache they must release the value back to the cache. Referenced
values are considered in use and will not be evicted. The cache may evict unreferenced values (e.g. to make room for other values or reduce
its size).
The number of values allowed in a cache at one time is managed by the cache framework. Cache size will grow when the system has available
memory and shrink under memory pressure.
Libcache is thread-safe. It is not safe to call back into the cache API from cache callback functions.
SEE ALSO cache_create(3), cache_set_and_retain(3)Darwin May 7, 2009 Darwin
Check Out this Related Man Page
cache_set_and_retain(3) BSD Library Functions Manual cache_set_and_retain(3)NAME
cache_set_and_retain, cache_get_and_retain, cache_release_value, cache_remove -- Routines used to manage cached values
SYNOPSIS
#include <cache.h>
int
cache_set_and_retain(cache_t *cache, void *key, void *value, size_t cost);
int
cache_get_and_retain(cache_t *cache, void *key, void **value_out);
int
cache_release_value(cache_t *cache, void *value);
int
cache_remove(cache_t *cache, void *key);
DESCRIPTION
These routines are used to manipulate values added to an in memory cache created by cache_create(3).
cache_set_and_retain() Adds value with cost to cache and associates it with key. The caller retains a reference to value that will prevent
value from being evicted from the cache until value is released in cache_release_value().
cache_get_and_retain() Fetches value for key from cache and places value in value_out. The caller retains a reference to value that will
prevent value from being evicted from the cache until value is release in cache_release_value().
cache_release_value() Releases a reference on value back to cache so that value may be evicted. Signals that the client is not actively
using value and will use cache_get_and_retain() before using again.
cache_remove() Removes the value associated with key from cache. Note that if the value is referenced by a client, the value will not be
finalized until the reference is released using cache_release_value().
RETURN VALUES
All functions return 0 for success and non-zero for failure. The value ENOENT (see errno.h) indicates that a key or value passed as an argu-
ment does not exist in the cache. EINVAL is used for invalid arguments.
EXAMPLE
The following example attempts to fetch a value from a cache using a key. If the value is not present in the cache then it is created and
added to the cache. The value is then used and released back to the cache to allow the cache to evict it when needed.
cache_t *mycache;
cache_create("com.mycompany.mycache", &cache_attributes, &mycache);
void *mykey = my_create_key();
void *myvalue = NULL;
if (cache_get_and_retain(mycache, mykey, &myvalue) != 0) {
myvalue = my_create_value_from_key(mykey);
cache_set_and_retain(mycache, mykey, myvalue, 0);
}
my_use_value(value);
cache_release_value(mycache, myvalue);
SEE ALSO cache(3)Darwin May 7, 2009 Darwin