cache_create(3) Library Functions Manual cache_create(3)

cache_create — Creates an in memory cache

#include <cache.h>

int
cache_create(const char *name, cache_attributes_t *attrs, cache_t **cache_out);

int
cache_destroy(cache_t *cache);

() Creates a cache using attributes attrs (see below) and name name and if successful stores it in cache_out. name is a NULL-terminated cstring in reverse-DNS form (e.g. "com.mycompany.imagecache") and is used for debugging and performance tools. It must not be NULL.

() Removes all unreferenced values in cache and deallocates it.

Cache attributes are callbacks passed to cache_create() to support different types of keys and values and to configure cache behavior. The cache framework provides preexisting cache_callbacks(3) functions that can be used for these callbacks to support common key and value types

typedef struct cache_attributes_s {
    uint32_t version;
    cache_key_hash_cb_t key_hash_cb;
    cache_key_is_equal_cb_t key_is_equal_cb;

    cache_key_retain_cb_t  key_retain_cb;
    cache_release_cb_t key_release_cb;
    cache_release_cb_t value_release_cb;

    cache_value_make_nonpurgeable_cb_t value_make_nonpurgeable_cb;
    cache_value_make_purgeable_cb_t value_make_purgeable_cb;

    void *user_data;
    cache_value_retain_cb_t value_retain_cb;
} cache_attributes_t;
#define CACHE_ATTRIBUTES_VERSION_2 2
key_hash_cb
Calculates a hash value using key
key_is_equal_cb
Determines if two keys are equal
key_retain_cb
Called when a key is added to a cache using () to allow key to be copied, or retained if it is a reference-counted object.
key_release_cb
Called when a key is removed or evicted from a cache to allow the key to be deallocated, or released if it is a reference-counted object.
value_retain_cb
Called when a value is added to a cache using cache_set_and_retain() to allow value to be retained if it is a reference-counted object.
value_release_cb
Called when a value is removed or evicted from a cache to allow the key to be deallocated, or released if it is a reference-counted object.
value_make_nonpurgeable_cb
Called when a value is referenced using () to allow it to be made nonpurgeable or uncompressed.
value_make_purgeable_cb
Called when a value is unreferenced to allow it to be made purgeable or compressed.
version
Attributes version number used for binary compatibility.
user_data
This value will be passed to all other callbacks for this cache. May be NULL.

All functions return 0 for success and non-zero for failure.

The following example uses pre-existing cache_callbacks(3) to create a cache with cstring keys and malloc(3) allocated values.

#include <cache.h>
#include <cache_callbacks.h>

cache_t *im_cache;
cache_attributes_t attrs = {
    .version = CACHE_ATTRIBUTES_VERSION_2,
    .key_hash_cb = cache_key_hash_cb_cstring,
    .key_is_equal_cb = cache_key_is_equal_cb_cstring,
    .key_retain_cb = my_copy_string,
    .key_release_cb = cache_release_cb_free,
    .value_release_cb = cache_release_cb_free,
};
cache_create("com.acme.im_cache", &attrs, &im_cache);

libcache(3) cache_set_and_retain(3) cache_callbacks(3)

May 7, 2009 Darwin