GNOME.org
 

[glib] Deprecate GCache

commit 2da83bbd36efd4adb1f4c036fe4793befbb8d120
Author: Matthias Clasen <mclasen redhat com>
Date:   Wed Oct 12 19:55:02 2011 -0400

    Deprecate GCache
    
    Ryan said it would be 'deprecated soon in GLib', when he removed
    the use of this in GTK+. That was a year ago, so its about time
    we act on it.

 docs/reference/glib/glib-docs.sgml |    2 +-
 glib/Makefile.am                   |    4 +-
 glib/{ => deprecated}/gcache.c     |  100 ++++++++++++++++++++---------------
 glib/{ => deprecated}/gcache.h     |    9 ++-
 glib/glib.h                        |    2 +-
 5 files changed, 67 insertions(+), 50 deletions(-)
---
diff --git a/docs/reference/glib/glib-docs.sgml b/docs/reference/glib/glib-docs.sgml
index b58f633..992c542 100644
--- a/docs/reference/glib/glib-docs.sgml
+++ b/docs/reference/glib/glib-docs.sgml
@@ -119,7 +119,6 @@ synchronize their operation.
       <xi:include href="xml/quarks.xml" />
       <xi:include href="xml/datalist.xml" />
       <xi:include href="xml/datasets.xml" />
-      <xi:include href="xml/caches.xml" />
       <xi:include href="xml/gvarianttype.xml"/>
       <xi:include href="xml/gvariant.xml"/>
       <xi:include href="gvariant-varargs.xml"/>
@@ -129,6 +128,7 @@ synchronize their operation.
   <chapter id="deprecated">
       <title>Deprecated APIs</title>
       <xi:include href="xml/threads-deprecated.xml"/>
+      <xi:include href="xml/caches.xml" />
       <xi:include href="xml/relations.xml" />
       <xi:include href="xml/completion.xml" />
   </chapter>
diff --git a/glib/Makefile.am b/glib/Makefile.am
index 012ab08..f18a542 100644
--- a/glib/Makefile.am
+++ b/glib/Makefile.am
@@ -113,6 +113,7 @@ uninstall-ms-lib:
 
 deprecated_sources = \
 	deprecated/gallocator.c		\
+	deprecated/gcache.c		\
 	deprecated/gcompletion.c	\
 	deprecated/grel.c		\
 	deprecated/gthread-deprecated.c
@@ -131,7 +132,6 @@ libglib_2_0_la_SOURCES = 	\
 	gbsearcharray.h		\
 	gbuffer.c		\
 	gbufferprivate.h	\
-	gcache.c		\
 	gchecksum.c		\
 	gconvert.c		\
 	gdataset.c		\
@@ -241,6 +241,7 @@ glibinclude_HEADERS =   \
 deprecatedincludedir=$(includedir)/glib-2.0/glib/deprecated
 deprecatedinclude_HEADERS = \
 	deprecated/gallocator.h		\
+	deprecated/gcache.h		\
 	deprecated/gcompletion.h	\
 	deprecated/grel.h		\
 	deprecated/gthread.h
@@ -255,7 +256,6 @@ glibsubinclude_HEADERS =   \
 	gbase64.h	\
 	gbitlock.h	\
 	gbookmarkfile.h \
-	gcache.h	\
 	gchecksum.h	\
 	gconvert.h	\
 	gdataset.h	\
diff --git a/glib/gcache.c b/glib/deprecated/gcache.c
similarity index 85%
rename from glib/gcache.c
rename to glib/deprecated/gcache.c
index e155bb7..4968c32 100644
--- a/glib/gcache.c
+++ b/glib/deprecated/gcache.c
@@ -45,14 +45,12 @@
  * 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.
  *
- * #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.
+ */
 
 typedef struct _GCacheNode  GCacheNode;
 
@@ -69,7 +67,9 @@ struct _GCacheNode
  * The #GCache struct is an opaque data structure containing
  * information about a #GCache. It should only be accessed via the
  * following functions.
- **/
+ *
+ * Deprecated:2.32: Use a #GHashTable instead
+ */
 struct _GCache
 {
   /* Called to create a value from a key */
@@ -110,54 +110,60 @@ g_cache_node_destroy (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.
+ *                  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).
+ *                      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.
+ *                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.
+ *                    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.
+ *                  %TRUE if the two keys are equivalent
  *
  * Creates a new #GCache.
- **/
+ *
+ * Returns: a new #GCache
+ *
+ * Deprecated:2.32: Use a #GHashTable instead
+ */
+
 /**
  * GCacheNewFunc:
- * @key: a #GCache key.
+ * @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.
+ * @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.
+ *         #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,
@@ -190,13 +196,15 @@ g_cache_new (GCacheNewFunc      value_new_func,
 
 /**
  * g_cache_destroy:
- * @cache: a #GCache.
+ * @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.
- **/
+ *
+ * Deprecated:2.32: Use a #GHashTable instead
+ */
 void
 g_cache_destroy (GCache *cache)
 {
@@ -209,9 +217,8 @@ g_cache_destroy (GCache *cache)
 
 /**
  * g_cache_insert:
- * @cache: a #GCache.
- * @key: a key describing a #GCache object.
- * @Returns: a pointer to a #GCache value.
+ * @cache: a #GCache
+ * @key: a key describing a #GCache object
  *
  * Gets the value corresponding to the given key, creating it if
  * necessary. It first checks if the value already exists in the
@@ -221,7 +228,11 @@ g_cache_destroy (GCache *cache)
  * 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.
- **/
+ *
+ * Returns: a pointer to a #GCache value
+ *
+ * Deprecated:2.32: Use a #GHashTable instead
+ */
 gpointer
 g_cache_insert (GCache   *cache,
                 gpointer  key)
@@ -250,13 +261,15 @@ g_cache_insert (GCache   *cache,
 
 /**
  * g_cache_remove:
- * @cache: a #GCache.
- * @value: the value to 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().
- **/
+ *
+ * Deprecated:2.32: Use a #GHashTable instead
+ */
 void
 g_cache_remove (GCache        *cache,
                 gconstpointer  value)
@@ -285,9 +298,9 @@ g_cache_remove (GCache        *cache,
 
 /**
  * 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.
+ * @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.
  *
@@ -295,7 +308,9 @@ g_cache_remove (GCache        *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 !
- **/
+ *
+ * Deprecated:2.32: Use a #GHashTable instead
+ */
 void
 g_cache_key_foreach (GCache   *cache,
                      GHFunc    func,
@@ -309,16 +324,15 @@ g_cache_key_foreach (GCache   *cache,
 
 /**
  * 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.
+ * @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
- **/
+ *    data structures to @func; use g_cache_key_foreach() instead
+ */
 void
 g_cache_value_foreach (GCache   *cache,
                        GHFunc    func,
diff --git a/glib/gcache.h b/glib/deprecated/gcache.h
similarity index 96%
rename from glib/gcache.h
rename to glib/deprecated/gcache.h
index ab1a333..2e5119b 100644
--- a/glib/gcache.h
+++ b/glib/deprecated/gcache.h
@@ -43,6 +43,7 @@ typedef void            (*GCacheDestroyFunc)    (gpointer       value);
 
 /* Caches
  */
+GLIB_DEPRECATED
 GCache*  g_cache_new           (GCacheNewFunc      value_new_func,
                                 GCacheDestroyFunc  value_destroy_func,
                                 GCacheDupFunc      key_dup_func,
@@ -50,20 +51,22 @@ GCache*  g_cache_new           (GCacheNewFunc      value_new_func,
                                 GHashFunc          hash_key_func,
                                 GHashFunc          hash_value_func,
                                 GEqualFunc         key_equal_func);
+GLIB_DEPRECATED
 void     g_cache_destroy       (GCache            *cache);
+GLIB_DEPRECATED
 gpointer g_cache_insert        (GCache            *cache,
                                 gpointer           key);
+GLIB_DEPRECATED
 void     g_cache_remove        (GCache            *cache,
                                 gconstpointer      value);
+GLIB_DEPRECATED
 void     g_cache_key_foreach   (GCache            *cache,
                                 GHFunc             func,
                                 gpointer           user_data);
-#ifndef G_DISABLE_DEPRECATED
-GLIB_DEPRECATED_FOR(g_cache_key_foreach)
+GLIB_DEPRECATED
 void     g_cache_value_foreach (GCache            *cache,
                                 GHFunc             func,
                                 gpointer           user_data);
-#endif
 
 G_END_DECLS
 
diff --git a/glib/glib.h b/glib/glib.h
index b8607b0..886fd80 100644
--- a/glib/glib.h
+++ b/glib/glib.h
@@ -37,7 +37,6 @@
 #include <glib/gbase64.h>
 #include <glib/gbitlock.h>
 #include <glib/gbookmarkfile.h>
-#include <glib/gcache.h>
 #include <glib/gchecksum.h>
 #include <glib/gconvert.h>
 #include <glib/gdataset.h>
@@ -96,6 +95,7 @@
 
 #ifndef G_DISABLE_DEPRECATED
 #include <glib/deprecated/gallocator.h>
+#include <glib/deprecated/gcache.h>
 #include <glib/deprecated/gcompletion.h>
 #include <glib/deprecated/grel.h>
 #include <glib/deprecated/gthread.h>
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]