Mac Developer Library

Developer

libcache Reference

Options
Deployment Target:

On This Page

libcache Reference

UNIX-level caching API.

Provides a dictionary associating keys with values. The cache determines its size and may remove keys at any time. Cache keeps reference counts for cache values and preserves values until unreferenced. Unreferenced values may be removed at any time.

All API functions return 0 for success, non-zero for failure. Most functions can return EINVAL for malformed arguments and ENOMEM for allocation failures. See function descriptions for other return values.

Cache functions rely upon a per-cache lock to provide thread safety. Calling cache functions from cache callbacks should be avoided to prevent deadlock.

Included Headers

  • <TargetConditionals.h>

  • <stddef.h>

  • <stdint.h>

  • <stdbool.h>

  • <sys/cdefs.h>

Functions

  • Creates a cache object.

    Declaration

    Objective-C

    __attribute__((__visibility__("default"))) int cache_create( const char *name, cache_attributes_t *attrs, cache_t **cache_out);

    Parameters

    name

    Cache name used for debugging and performance tools. Name should be in reverse-DNS form, e.g. "com.mycompany.myproject.mycache" and must not be NULL. Name is copied.

    attrs

    Cache attributes used to customize cache behavior. Attributes are defined below and must not be NULL.

    cache_out

    Cache object is stored here if cache is successfully created. Must not be NULL.

    Return Value

    Returns 0 for success, non-zero for failure.

  • Destroys cache

    Declaration

    Objective-C

    __attribute__((__visibility__("default"))) int cache_destroy( cache_t *cache);

    Parameters

    cache

    Pointer to cache. Must not be NULL.

    Return Value

    Returns 0 for success, non-zero for failure. Returns EAGAIN if the cache was not destroyed because retained cache values exist.

    Discussion

    Invokes cache_remove_all(). If there are no retained cache values then the cache object is freed. If retained cache values exist then returns EAGAIN.

  • Fetches value for key.

    Declaration

    Objective-C

    __attribute__((__visibility__("default"))) int cache_get_and_retain( cache_t *cache, void *key, void **value_out);

    Parameters

    cache

    Pointer to cache. Must not be NULL.

    key

    Key used to lookup value. Must not be NULL.

    value_out

    Value is stored here if found. Must not be NULL.

    Return Value

    Returns 0 for success, ENOENT if not found, other non-zero for failure.

    Discussion

    Fetches value for key, retains value, and stores value in value_out. Caller should release value using cache_release_value().

  • Releases a previously retained cache value.

    Declaration

    Objective-C

    __attribute__((__visibility__("default"))) int cache_release_value( cache_t *cache, void *value);

    Parameters

    cache

    Pointer to cache. Must not be NULL.

    value

    Value to release. Must not be NULL.

    Return Value

    Returns 0 for success, non-zero for failure.

    Discussion

    Releases a previously retained cache value. When the reference count reaches zero the cache may make the value purgeable or destroy it.

  • Removes a key and its value.

    Declaration

    Objective-C

    __attribute__((__visibility__("default"))) int cache_remove( cache_t *cache, void *key);

    Parameters

    cache

    Pointer to cache. Must not be NULL.

    key

    Key to remove. Must not be NULL.

    Return Value

    Returns 0 for success, non-zero for failure.

    Discussion

    Removes a key and its value from the cache such that cache_get_and_retain() will fail. Invokes the key release callback immediately. Invokes the value release callback once value's retain count is zero.

  • Invokes cache_remove on all keys.

    Declaration

    Objective-C

    __attribute__((__visibility__("default"))) int cache_remove_all( cache_t *cache);

    Parameters

    cache

    Pointer to cache. Must not be NULL.

    Return Value

    Returns 0 for success, non-zero for failure.

  • Sets value for key.

    Declaration

    Objective-C

    __attribute__((__visibility__("default"))) int cache_set_and_retain( cache_t *cache, void *key, void *value, cache_cost_t cost);

    Parameters

    cache

    Pointer to cache. Must not be NULL.

    key

    Key to add. Must not be NULL.

    value

    Value to add. If value is NULL, key is associated with the value NULL.

    cost

    Cost of maintaining value in cache.

    Return Value

    Returns 0 for success, non-zero for failure.

    Discussion

    Sets value for key. Value is retained until released using cache_release_value(). The key retain callback (if provided) is invoked on key.

    Replaces previous key and value if present. Invokes the key release callback immediately for the previous key. Invokes the value release callback once the previous value's retain count is zero.

    Cost indicates the relative cost of maintaining value in the cache (e.g., size of value in bytes) and may be used by the cache under memory pressure to select which cache values to evict. Zero is a valid cost.

Callbacks

  • Calculates a hash value using key.

    Declaration

    Objective-C

    typedef uintptr_t ( *cache_key_hash_cb_t)( void *key, void *user_data);

    Parameters

    key

    Key to user to calculate hash.

    user_data

    User-provided value passed during cache creation.

    Discussion

    Calculates and returns a key hash. If the callback is NULL then a key will be converted from a pointer to an integer to compute the hash code.

  • Determines if two keys are equal.

    Declaration

    Objective-C

    typedef bool ( *cache_key_is_equal_cb_t)( void *key1, void *key2, void *user_data);

    Parameters

    key1

    First key

    key2

    Second key

    user_data

    User-provided value passed during cache creation.

    Return Value

    Returns true if equal, false if not equal.

    Discussion

    Determines if two keys are equal. If the callback is NULL then the cache uses pointer equality to test equality for keys.

  • Retains a key.

    Declaration

    Objective-C

    typedef void ( *cache_key_retain_cb_t)( void *key_in, void **key_out, void *user_data);

    Parameters

    key_in

    Key provided in cache_set_and_retain()

    key_out

    Set key to add here. If NULL, cache_set_and_retain() will fail.

    user_data

    User-provided value passed during cache creation.

    Discussion

    Called when it is added to the cache through cache_set_and_retain. The cache will add the key stored in key_out and may release it at any time by calling the key release callback. If key_out is NULL then no key will be added. If callback is NULL then the cache adds key_in.

  • Releases or deallocates a cache value.

    Declaration

    Objective-C

    typedef void ( *cache_release_cb_t)( void *key_or_value, void *user_data);

    Parameters

    key_or_value

    Key or value to release

    user_data

    User-provided value passed during cache creation.

    Discussion

    Called when a key or value is removed from the cache, ie. when the cache no longer references it. In the common case the key or value should be deallocated, or released if reference counted. If the callback is NULL then the cache calls free() on key_or_value.

  • Makes a cache value nonpurgeable and tests to see if value is still valid.

    Declaration

    Objective-C

    typedef bool ( *cache_value_make_nonpurgeable_cb_t)( void *value, void *user_data);

    Parameters

    value
    user_data

    User-provided value passed during cache creation.

    Return Value

    Should return true if value is valid, or false if it was purged.

    Discussion

    Purged cache values will be removed. If the callback is NULL then the cache does not make value nonpurgeable.

  • Makes a cache value purgeable.

    Declaration

    Objective-C

    typedef void ( *cache_value_make_purgeable_cb_t)( void *value, void *user_data);

    Parameters

    value

    Cache value to make purgeable.

    user_data

    User-provided value passed during cache creation.

    Discussion

    Called when the cache determines that no cache clients reference the value. If the callback is NULL then the cache does not make value purgeable.

  • Retains a value.

    Declaration

    Objective-C

    typedef void ( *cache_value_retain_cb_t)( void *value_in, void *user_data);

    Parameters

    value_in

    Value provided in cache_set_and_retain()

    user_data

    User-provided value passed during cache creation.

    Discussion

    Called when a unique value is added to the cache through cache_set_and_retain(). Allows the client to retain value_in before it is added to the cache. The cache will call any value_release_cb after removing a cache value.

Data Types

See the Overview section above for header-level documentation.

  • Cache attributes

    Declaration

    Objective-C

    typedef struct cache_attributes_s cache_attributes_t;

    Discussion

    Collection of callbacks used by cache_create() to customize cache behavior.

    Import Statement

  • Cost of maintaining a value in the cache.

    Declaration

    Objective-C

    typedef size_t cache_cost_t;

    Discussion

    Cache uses cost when deciding which value to evict. Usually related to a value's memory size in bytes. Zero is a valid cost.

    Import Statement

  • Opaque cache object.

    Declaration

    Objective-C

    typedef struct cache_s cache_t;

    Discussion

    Dictionary associating keys with values.

    Import Statement

  • Callbacks passed to cache_create() to customize cache behavior.

    Declaration

    Objective-C

    struct __attribute__((__visibility__("default"))) 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; // Added in CACHE_ATTRIBUTES_VERSION_2 cache_value_retain_cb_t value_retain_cb; };

    Fields

    key_hash_cb

    Key hash callback

    key_is_equal_cb

    Key is equal callback

    key_retain_cb

    Key retain callback

    key_release_cb

    Key release callback

    value_retain_cb

    Value retain callback

    value_release_cb

    Value release callback

    value_make_nonpurgeable_cb

    Value make nonpurgeable callback

    value_make_purgeable_cb

    Value make purgeable callback

    version

    Attributes version number used for binary compatibility.

    user_data

    Passed to all callbacks. May be NULL.