cache_create(3) [osx man page]

cache_create(3) 					   BSD Library Functions Manual 					   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 uncom-
				    pressed.

     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)

Darwin								    May 7, 2009 							    Darwin

Check Out this Related Man Page

cache_set_and_retain(3) 				   BSD Library Functions Manual 				   cache_set_and_retain(3)

NAME

     cache_set_and_retain, cache_get_and_retain, cache_release_value, cache_remove -- Routines used to manage cached values

SYNOPSIS

     #include <cache.h>

     int
     cache_set_and_retain(cache_t *cache, void *key, void *value, size_t cost);

     int
     cache_get_and_retain(cache_t *cache, void *key, void **value_out);

     int
     cache_release_value(cache_t *cache, void *value);

     int
     cache_remove(cache_t *cache, void *key);

DESCRIPTION

     These routines are used to manipulate values added to an in memory cache created by cache_create(3).

     cache_set_and_retain() Adds value with cost to cache and associates it with key.  The caller retains a reference to value that will prevent
     value from being evicted from the cache until value is released in cache_release_value().

     cache_get_and_retain() Fetches value for key from cache and places value in value_out.  The caller retains a reference to value that will
     prevent value from being evicted from the cache until value is release in cache_release_value().

     cache_release_value() Releases a reference on value back to cache so that value may be evicted.  Signals that the client is not actively
     using value and will use cache_get_and_retain() before using again.

     cache_remove() Removes the value associated with key from cache.  Note that if the value is referenced by a client, the value will not be
     finalized until the reference is released using cache_release_value().

RETURN VALUES

     All functions return 0 for success and non-zero for failure.  The value ENOENT (see errno.h) indicates that a key or value passed as an argu-
     ment does not exist in the cache.	EINVAL is used for invalid arguments.

EXAMPLE

     The following example attempts to fetch a value from a cache using a key.	If the value is not present in the cache then it is created and
     added to the cache.  The value is then used and released back to the cache to allow the cache to evict it when needed.

	   cache_t *mycache;
	   cache_create("com.mycompany.mycache", &cache_attributes, &mycache);

	   void *mykey = my_create_key();
	   void *myvalue = NULL;

	   if (cache_get_and_retain(mycache, mykey, &myvalue) != 0) {
	       myvalue = my_create_value_from_key(mykey);
	       cache_set_and_retain(mycache, mykey, myvalue, 0);
	   }

	   my_use_value(value);
	   cache_release_value(mycache, myvalue);

SEE ALSO

     cache(3)

Darwin								    May 7, 2009 							    Darwin

Linux and UNIX Man Pages

cache_create(3) [osx man page]

Check Out this Related Man Page