Overview

UNIX-level caching API.

Discussion

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.

Updated:

2008-03-10

Cache Callbacks

Group members:

Functions

cache_create

Creates a cache object.

cache_destroy

Destroys cache

cache_get_and_retain

Fetches value for key.

cache_release_value

Releases a previously retained cache value.

cache_remove

Removes a key and its value.

cache_remove_all

Invokes cache_remove on all keys.

cache_set_and_retain

Sets value for key.

Creates a cache object.

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

Parameters

Return Value

Returns 0 for success, non-zero for failure.

Destroys cache

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

Parameters

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.

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

Parameters

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.

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

Parameters

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.

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

Parameters

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.

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

Parameters

Return Value

Returns 0 for success, non-zero for failure.

Sets value for key.

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

Parameters

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.

Typedefs

cache_attributes_t

Cache attributes

cache_cost_t

Cost of maintaining a value in the cache.

cache_key_hash_cb_t

Calculates a hash value using key.

cache_key_is_equal_cb_t

Determines if two keys are equal.

cache_key_retain_cb_t

Retains a key.

cache_release_cb_t

Releases or deallocates a cache value.

cache_t

Opaque cache object.

cache_value_make_nonpurgeable_cb_t

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

cache_value_make_purgeable_cb_t

Makes a cache value purgeable.

cache_value_retain_cb_t

Retains a value.

Cache attributes

typedef struct cache_attributes_s cache_attributes_t;  

Discussion

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

Cost of maintaining a value in the cache.

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.

Calculates a hash value using key.

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

Fields

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.

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

Parameters

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.

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

Fields

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.

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

Fields

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.

Opaque cache object.

typedef struct cache_s cache_t;  

Discussion

Dictionary associating keys with values.

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

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

Parameters

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.

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

Fields

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.

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

Fields

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.

Structs and Unions

cache_attributes_s

Callbacks passed to cache_create() to customize cache behavior.

Callbacks passed to cache_create() to customize cache behavior.

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

Fields

© Copyright (c) 2007-2008 Apple Inc. All rights reserved. Last Updated: 2008-03-10