libcache Reference

Declared in
cache.h

Overview

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

See the Overview section above for header-level documentation.

cache_create

Creates a cache object.

__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.

cache_destroy

Destroys cache

__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.

cache_get_and_retain

Fetches value for key.

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

cache_release_value

Releases a previously retained cache value.

__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.

cache_remove

Removes a key and its value.

__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.

cache_remove_all

Invokes cache_remove on all keys.

__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.

cache_set_and_retain

Sets value for key.

__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

See the Overview section above for header-level documentation.

cache_key_hash_cb_t

Calculates a hash value using key.

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.

cache_key_is_equal_cb_t

Determines if two keys are equal.

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.

cache_key_retain_cb_t

Retains a key.

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.

cache_release_cb_t

Releases or deallocates a cache value.

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.

cache_value_make_nonpurgeable_cb_t

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
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.

cache_value_make_purgeable_cb_t

Makes a cache value purgeable.

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.

cache_value_retain_cb_t

Retains a value.

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_t

Cache attributes

typedef struct cache_attributes_s cache_attributes_t;
Discussion

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

cache_cost_t

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.

cache_t

Opaque cache object.

typedef struct cache_s cache_t;
Discussion

Dictionary associating keys with values.

cache_attributes_s

Callbacks passed to cache_create() to customize cache behavior.

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.