* Modified by the GLib Team and others 1997-2000. See the AUTHORS
* file for a list of people on the GLib Team. See the ChangeLog
* files for a list of changes. These files are distributed with
- * GLib at ftp://ftp.gtk.org/pub/gtk/.
+ * GLib at ftp://ftp.gtk.org/pub/gtk/.
*/
-/*
+/*
* MT safe
*/
#include "config.h"
-#include "glib.h"
+#include "gcache.h"
+
+#include "ghash.h"
+#include "gtestutils.h"
+/**
+ * SECTION:caches
+ * @title: Caches
+ * @short_description: caches allow sharing of complex data structures
+ * to save resources
+ *
+ * A #GCache allows sharing of complex data structures, in order to
+ * save system resources.
+ *
+ * GTK+ uses caches for #GtkStyles and #GdkGCs. These consume a lot of
+ * resources, so a #GCache is used to see if a #GtkStyle or #GdkGC with
+ * the required properties already exists. If it does, then the
+ * existing object is used instead of creating a new one.
+ *
+ * #GCache uses keys and values. A #GCache key describes the properties
+ * of a particular resource. A #GCache value is the actual resource.
+ **/
typedef struct _GCacheNode GCacheNode;
gint ref_count;
};
+/**
+ * GCache:
+ *
+ * The #GCache struct is an opaque data structure containing
+ * information about a #GCache. It should only be accessed via the
+ * following functions.
+ **/
struct _GCache
{
/* Called to create a value from a key */
GHashTable *value_table;
};
+static inline GCacheNode*
+g_cache_node_new (gpointer value)
+{
+ GCacheNode *node = g_slice_new (GCacheNode);
+ node->value = value;
+ node->ref_count = 1;
+ return node;
+}
-static GCacheNode* g_cache_node_new (gpointer value);
-static void g_cache_node_destroy (GCacheNode *node);
-
-
-static GMemChunk *node_mem_chunk = NULL;
-G_LOCK_DEFINE_STATIC (node_mem_chunk);
+static inline void
+g_cache_node_destroy (GCacheNode *node)
+{
+ g_slice_free (GCacheNode, node);
+}
+/**
+ * g_cache_new:
+ * @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.
+ *
+ * Creates a new #GCache.
+ **/
+/**
+ * GCacheNewFunc:
+ * @key: a #GCache key.
+ * @Returns: a new #GCache value corresponding to the key.
+ *
+ * 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.
+ **/
+/**
+ * GCacheDestroyFunc:
+ * @value: the #GCache value to destroy.
+ *
+ * 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.
+ **/
+/**
+ * GCacheDupFunc:
+ * @value: the #GCache key to destroy (<emphasis>not</emphasis> a
+ * #GCache value as it seems).
+ * @Returns: a copy of the #GCache key.
+ *
+ * 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.
+ **/
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)
+ GCacheDestroyFunc value_destroy_func,
+ GCacheDupFunc key_dup_func,
+ GCacheDestroyFunc key_destroy_func,
+ GHashFunc hash_key_func,
+ GHashFunc hash_value_func,
+ GEqualFunc key_equal_func)
{
GCache *cache;
g_return_val_if_fail (hash_value_func != NULL, NULL);
g_return_val_if_fail (key_equal_func != NULL, NULL);
- cache = g_new (GCache, 1);
+ cache = g_slice_new (GCache);
cache->value_new_func = value_new_func;
cache->value_destroy_func = value_destroy_func;
cache->key_dup_func = key_dup_func;
return cache;
}
+/**
+ * g_cache_destroy:
+ * @cache: a #GCache.
+ *
+ * Frees the memory allocated for the #GCache.
+ *
+ * Note that it does not destroy the keys and values which were
+ * contained in the #GCache.
+ **/
void
g_cache_destroy (GCache *cache)
{
g_hash_table_destroy (cache->key_table);
g_hash_table_destroy (cache->value_table);
- g_free (cache);
+ g_slice_free (GCache, cache);
}
+/**
+ * g_cache_insert:
+ * @cache: a #GCache.
+ * @key: a key describing a #GCache object.
+ * @Returns: a pointer to a #GCache value.
+ *
+ * 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.
+ **/
gpointer
g_cache_insert (GCache *cache,
- gpointer key)
+ gpointer key)
{
GCacheNode *node;
gpointer value;
return node->value;
}
+/**
+ * g_cache_remove:
+ * @cache: a #GCache.
+ * @value: the value to remove.
+ *
+ * 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().
+ **/
void
g_cache_remove (GCache *cache,
- gconstpointer value)
+ gconstpointer value)
{
GCacheNode *node;
gpointer key;
}
}
+/**
+ * g_cache_key_foreach:
+ * @cache: a #GCache.
+ * @func: the function to call with each #GCache key.
+ * @user_data: user data to pass to the function.
+ *
+ * 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 !
+ **/
void
g_cache_key_foreach (GCache *cache,
- GHFunc func,
- gpointer user_data)
+ GHFunc func,
+ gpointer user_data)
{
g_return_if_fail (cache != NULL);
g_return_if_fail (func != NULL);
g_hash_table_foreach (cache->value_table, func, user_data);
}
+/**
+ * g_cache_value_foreach:
+ * @cache: a #GCache.
+ * @func: the function to call with each #GCache value.
+ * @user_data: user data to pass to the function.
+ *
+ * Calls the given function for each of the values in the #GCache.
+ *
+ * Deprecated:2.10: The reason is that it passes pointers to internal
+ * data structures to @func; use g_cache_key_foreach()
+ * instead
+ **/
void
g_cache_value_foreach (GCache *cache,
- GHFunc func,
- gpointer user_data)
+ GHFunc func,
+ gpointer user_data)
{
g_return_if_fail (cache != NULL);
g_return_if_fail (func != NULL);
g_hash_table_foreach (cache->key_table, func, user_data);
}
-
-
-static GCacheNode*
-g_cache_node_new (gpointer value)
-{
- GCacheNode *node;
-
- G_LOCK (node_mem_chunk);
- if (!node_mem_chunk)
- node_mem_chunk = g_mem_chunk_new ("cache node mem chunk", sizeof (GCacheNode),
- 1024, G_ALLOC_AND_FREE);
-
- node = g_chunk_new (GCacheNode, node_mem_chunk);
- G_UNLOCK (node_mem_chunk);
-
- node->value = value;
- node->ref_count = 1;
-
- return node;
-}
-
-static void
-g_cache_node_destroy (GCacheNode *node)
-{
- G_LOCK (node_mem_chunk);
- g_mem_chunk_free (node_mem_chunk, node);
- G_UNLOCK (node_mem_chunk);
-}