GHashTable ref counting

[Tim Janik <timj imendio com>]

hi all,

the GtkRC logical colors bug provides a motivation for reference counted 
GHashTables:
  http://bugzilla.gnome.org/show_bug.cgi?id=114355
several options exist to adress this situation:
1) implement an internal ref-counting wrapper for GHashTable, used in the
   implementation of #114355 solely.
   access to the hash table is awkward through an extra indirection and
   this doesn't scale beyond gtk internals, i.e. other apps are likely to
   have to duplicate this solution.
2) introduce a GObject-based GHashTable wrapper (the approach choosen in
   the attached implementation, called GtkHashTable).
   access to the hash table is awkward through a GtkHashTable->hash
   indirection, and Gtk isn't really the right place for a GLib hash
   table wrapper.
3) implement hash table reference counting in GLib natively, also allowing
   the use of hash tables as boxed types.

i consider (3) to be the best solution, so i intend to implement the following:

@@ ghash.h
+/* keeping hash tables alive */
+GHashTable* g_hash_table_ref   (GHashTable *hash_table);
+void        g_hash_table_unref (GHashTable *hash_table);
@@ gboxed.h
 /* --- GLib boxed types --- */
 #define G_TYPE_GSTRING          (g_gstring_get_type ())
+#define G_TYPE_HASH_TABLE       (g_gstring_get_type ())

lifetime maintenance of hash tables will look like this:

  /* create a new hash table with a reference count of 1 */
  GHashTable* g_hash_table_new               (GHashFunc       hash_func,
                                              GEqualFunc      key_equal_func);

  /* remove all nodes from hash table, do a single unref() */
  void        g_hash_table_destroy           (GHashTable     *hash_table);

  /* increment reference count by 1 */
  GHashTable* g_hash_table_ref   (GHashTable *hash_table);

  /* decrement reference count by 1.
   * if it drops to 0, remove all nodes, free the hash table structure
   */
  void        g_hash_table_unref (GHashTable *hash_table);

this would mean the semantics of the existing API is preserved while adding
reference counting.

the G_TYPE_HASH_TABLE boxed type will use hash table reference counting to
implement boxed_copy and boxed_free, since copying of entire hash tables can
not be supported generically anyway (that is, without recursive type
information, which GType doesn't support).

---
ciaoTJ