cache_create(3)

NAME
cache_create - Creates an in memory cache

SYNOPSIS
#include <cache.h>
int
cache_create(const char *name, cache_attributes_t *attrs, cache_t **cache_out);
int
cache_destroy(cache_t *cache);

DESCRIPTION

cache_create() 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.

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

CACHE ATTRIBUTES
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 cache_set_and_retain() 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 cache_get_and_retain() 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.

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

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

    #include <cache.h>
    #include <cache_callbcaks.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);

SEE ALSO
cache(3) cache_set_and_retain(3) cache_callbacks(3)