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 final‐
ized 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 argument
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 ALSOcache(3)Darwin May 7, 2009 Darwin