GLib Reference Manual: Caches

## Caches Caches — caches allow sharing of complex data structures to save resources |

## Functions

GCache * | g_cache_new ()
gpointer | g_cache_insert ()
void | g_cache_remove ()
void | g_cache_destroy ()
void | g_cache_key_foreach ()
void | g_cache_value_foreach ()
void | (*GCacheDestroyFunc) ()
gpointer | (*GCacheDupFunc) ()
gpointer | (*GCacheNewFunc) ()

## Types and Values

| GCache

## Includes

    #include <glib.h>

## Description

A GCache allows sharing of complex data structures, in order to save system resources.

GCache uses keys and values. A GCache key describes the properties of a particular resource. A GCache value is the actual resource.

GCache has been marked as deprecated, since this API is rarely used and not very actively maintained.

## Functions

### g_cache_new ()

    GCache *
    g_cache_new (GCacheNewFunc value_new_func,
                 GCacheDestroyFunc value_destroy_func,
                 GCacheDupFunc key_dup_func,
                 GCacheDestroyFunc key_destroy_func,
                 GHashFunc hash_key_func,
                 GHashFunc hash_value_func,
                 GEqualFunc key_equal_func);

`g_cache_new` has been deprecated since version 2.32 and should not be used in newly-written code.

Use a GHashTable instead

Creates a new GCache.

#### Parameters

value_new_func | a function to create a new object given a key. This is called by `g_cache_insert()` if an object with the given key does not already exist |
value_destroy_func | a function to destroy an object. It is called by `g_cache_remove()` when the object is no longer needed (i.e. its reference count drops to 0) |
key_dup_func | a function to copy a key. It is called by `g_cache_insert()` if the key does not already exist in the GCache |
key_destroy_func | a function to destroy a key. It is called by `g_cache_remove()` when the object is no longer needed (i.e. its reference count drops to 0) |
hash_key_func | a function to create a hash value from a key |
hash_value_func | a function to create a hash value from a value |
key_equal_func | a function to compare two keys. It should return `TRUE` if the two keys are equivalent |

#### Returns

a new GCache

### g_cache_insert ()

    gpointer
    g_cache_insert (GCache *cache,
                    gpointer key);

`g_cache_insert` has been deprecated since version 2.32 and should not be used in newly-written code.

Use a GHashTable instead

Gets the value corresponding to the given key, creating it if necessary. It first checks if the value already exists in the GCache, by using the `key_equal_func` function passed to `g_cache_new()`. If it does already exist it is returned, and its reference count is increased by one. If the value does not currently exist, if is created by calling the `value_new_func` . The key is duplicated by calling `key_dup_func` and the duplicated key and value are inserted into the GCache.

#### Parameters

cache | a GCache |
key | a key describing a GCache object |

#### Returns

a pointer to a GCache value

### g_cache_remove ()

    void
    g_cache_remove (GCache *cache,
                    gconstpointer value);

`g_cache_remove` has been deprecated since version 2.32 and should not be used in newly-written code.

Use a GHashTable instead

Decreases the reference count of the given value. If it drops to 0 then the value and its corresponding key are destroyed, using the `value_destroy_func` and `key_destroy_func` passed to `g_cache_new()`.

#### Parameters

cache | a GCache |
value | the value to remove |

### g_cache_destroy ()

    void
    g_cache_destroy (GCache *cache);

`g_cache_destroy` has been deprecated since version 2.32 and should not be used in newly-written code.

Use a GHashTable instead

Frees the memory allocated for the GCache.

Note that it does not destroy the keys and values which were contained in the GCache.

#### Parameters

cache | a GCache |

### g_cache_key_foreach ()

    void
    g_cache_key_foreach (GCache *cache,
                         GHFunc func,
                         gpointer user_data);

`g_cache_key_foreach` has been deprecated since version 2.32 and should not be used in newly-written code.

Use a GHashTable instead

Calls the given function for each of the keys in the GCache.

NOTE `func` is passed three parameters, the value and key of a cache entry and the `user_data` . The order of value and key is different from the order in which `g_hash_table_foreach()` passes key-value pairs to its callback function !

#### Parameters

cache | a GCache |
func | the function to call with each GCache key |
user_data | user data to pass to the function |

### g_cache_value_foreach ()

    void
    g_cache_value_foreach (GCache *cache,
                           GHFunc func,
                           gpointer user_data);

`g_cache_value_foreach` has been deprecated since version 2.10 and should not be used in newly-written code.

The reason is that it passes pointers to internal data structures to `func` ; use `g_cache_key_foreach()` instead

Calls the given function for each of the values in the GCache.

#### Parameters

cache | a GCache |
func | the function to call with each GCache value |
user_data | user data to pass to the function |

### GCacheDestroyFunc ()

    void
    (*GCacheDestroyFunc) (gpointer value);

`GCacheDestroyFunc` is deprecated and should not be used in newly-written code.

Specifies the type of the `value_destroy_func` and `key_destroy_func` functions passed to `g_cache_new()`. The functions are passed a pointer to the GCache key or GCache value and should free any memory and other resources associated with it.

#### Parameters

value | the GCache value to destroy |

### GCacheDupFunc ()

    gpointer
    (*GCacheDupFunc) (gpointer value);

`GCacheDupFunc` is deprecated and should not be used in newly-written code.

Specifies the type of the `key_dup_func` function passed to `g_cache_new()`. The function is passed a key (<emphasis>not</emphasis> a value as the prototype implies) and should return a duplicate of the key.

#### Parameters

value | the GCache key to destroy (<emphasis>not</emphasis> a GCache value as it seems) |

#### Returns

a copy of the GCache key

### GCacheNewFunc ()

    gpointer
    (*GCacheNewFunc) (gpointer key);

`GCacheNewFunc` is deprecated and should not be used in newly-written code.

Specifies the type of the `value_new_func` function passed to `g_cache_new()`. It is passed a GCache key and should create the value corresponding to the key.

#### Parameters

key | a GCache key |

#### Returns

a new GCache value corresponding to the key.

## Types and Values

### GCache

    typedef struct _GCache GCache;

`GCache` has been deprecated since version 2.32 and should not be used in newly-written code.

Use a GHashTable instead

The GCache struct is an opaque data structure containing information about a GCache. It should only be accessed via the following functions.