prefix internal functions with '_'. renamed g_signal_connect_closure() to

Fri Nov  3 07:35:00 2000  Tim Janik  <timj@gtk.org>

        * gsignal.[hc]: prefix internal functions with '_'. renamed
        g_signal_connect_closure() to g_signal_connect_closure_by_id().
        added g_signal_parse_name() to retrive signal_id and detail quark
        from a signal name (internal).

Fri Nov  3 07:33:15 2000  Tim Janik  <timj@gtk.org>

        * gobject/gobject-docs.sgml: added &gobject-closures; section.

        * gobject/Makefile.am (tmpl_sources): add tmpl/clsoures.sgml

        * gobject/gobject-sections.txt: added Closure section.

        * gobject/tmpl/closures.sgml: new file with template description
        for GClosure functions.

docs/reference/ChangeLog

@@ -1,3 +1,14 @@
+Fri Nov  3 07:33:15 2000  Tim Janik  <timj@gtk.org>
+
+	* gobject/gobject-docs.sgml: added &gobject-closures; section.
+
+	* gobject/Makefile.am (tmpl_sources): add tmpl/clsoures.sgml
+
+	* gobject/gobject-sections.txt: added Closure section.
+	
+	* gobject/tmpl/closures.sgml: new file with template description
+	for GClosure functions.
+
 2000-11-02  Sebastian Wilhelmi  <wilhelmi@ira.uka.de>
 
 	* glib/tmpl/glib-unused.sgml: Remove superfluous GSearchFunc.

docs/reference/glib/tmpl/caches.sgml

@@ -51,10 +51,11 @@ 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_compare_func: 
+@Returns: a new #GCache.
+<!-- # Unused Parameters # -->
 @key_equal_func: a function to compare two keys. It should return TRUE if
 the two keys are equivalent.
-@Returns: a new #GCache.
-
 
 
 <!-- ##### FUNCTION g_cache_insert ##### -->

docs/reference/glib/tmpl/glib-unused.sgml

@@ -65,6 +65,17 @@ Turns the argument into a string literal by using the '#' stringizing operator.
 </para>
 
 
+<!-- ##### USER_FUNCTION GEqualFunc ##### -->
+<para>
+Specifies the type of a function used to test two values for
+equality. The function should return TRUE if both values are equal and
+FALSE otherwise.
+</para>
+
+@a: a value.
+@b: a value to compare with.
+@Returns: TRUE if @a = @b; FALSE otherwise.
+
 <!-- ##### FUNCTION g_convert_error_quark ##### -->
 <para>
 

docs/reference/glib/tmpl/hash_tables.sgml

@@ -69,13 +69,15 @@ Hash values are used to determine where keys are stored within the
 #GHashTable data structure.
 The g_direct_hash(), g_int_hash() and g_str_hash() functions are provided for
 some common types of keys. If hash_func is NULL, g_direct_hash() is used.
+@key_compare_func: 
+@Returns: a new #GHashTable.
+<!-- # Unused Parameters # -->
 @key_equal_func: a function to check two keys for equality.  This is
 used when looking up keys in the #GHashTable.  The g_direct_equal(),
 g_int_equal() and g_str_equal() functions are provided for the most
 common types of keys. If @key_equal_func is NULL, keys are compared
 directly in a similar fashion to g_direct_equal(), but without the
 overhead of a function call.
-@Returns: a new #GHashTable.
 
 
 <!-- ##### USER_FUNCTION GHashFunc ##### -->
@@ -102,18 +104,6 @@ lookup.
 @Returns: the hash value corresponding to the key.
 
 
-<!-- ##### USER_FUNCTION GEqualFunc ##### -->
-<para>
-Specifies the type of a function used to test two values for
-equality. The function should return TRUE if both values are equal and
-FALSE otherwise.
-</para>
-
-@a: a value.
-@b: a value to compare with.
-@Returns: TRUE if @a = @b; FALSE otherwise.
-
-
 <!-- ##### FUNCTION g_hash_table_insert ##### -->
 <para>
 Inserts a new key and value into a #GHashTable.

docs/reference/glib/tmpl/relations.sgml

@@ -83,6 +83,8 @@ Note that this must be called before any records are added to the #GRelation.
 @relation: a #GRelation.
 @field: the field to index, counting from 0.
 @hash_func: a function to produce a hash value from the field data.
+@key_compare_func: 
+<!-- # Unused Parameters # -->
 @key_equal_func: a function to compare two values of the given field.
 
 

docs/reference/gobject/Makefile.am

@@ -22,6 +22,7 @@ tmpl_sources =				\
 	tmpl/objects.sgml		\
 	tmpl/param_specs.sgml		\
 	tmpl/signals.sgml		\
+	tmpl/closures.sgml		\
 	tmpl/standard_params.sgml	\
 	tmpl/types.sgml			\
 	tmpl/value_collection.sgml	\

docs/reference/gobject/gobject-docs.sgml

@@ -4,6 +4,7 @@
 <!entity gobject-objects SYSTEM "sgml/objects.sgml">
 <!entity gobject-param-specs SYSTEM "sgml/param_specs.sgml">
 <!entity gobject-signals SYSTEM "sgml/signals.sgml">
+<!entity gobject-closures SYSTEM "sgml/closures.sgml">
 <!entity gobject-standard-params SYSTEM "sgml/standard_params.sgml">
 <!entity gobject-types SYSTEM "sgml/types.sgml">
 <!entity gobject-value-collection SYSTEM "sgml/value_collection.sgml">
@@ -71,6 +72,7 @@
       &gobject-param-specs;
       &gobject-standard-params;
       &gobject-signals;
+      &gobject-closures;
   </reference>
   
 </book>

docs/reference/gobject/gobject-sections.txt

@@ -336,7 +336,7 @@ g_signal_lookup
 g_signal_name
 g_signal_query
 g_signal_list_ids
-g_signal_connect_closure
+g_signal_connect_closure_by_id
 g_signal_handler_block
 g_signal_handler_unblock
 g_signal_handler_disconnect
@@ -349,6 +349,33 @@ g_signal_stop_emission
 g_signal_type_closure_new
 g_signal_add_emission_hook_full
 g_signal_remove_emission_hook
-g_signal_handlers_destroy
+g_signal_parse_name
-g_signals_destroy
+</SECTION>
+
+<SECTION>
+<TITLE>Closures</TITLE>
+<FILE>closures</FILE>
+GClosureMarshal
+GClosureNotify
+GClosure
+GCClosure
+GClosureNotifyData
+G_CLOSURE_NEEDS_MARSHAL
+G_CCLOSURE_SWAP_DATA
+g_cclosure_new
+g_cclosure_new_swap
+g_cclosure_new_object
+g_cclosure_new_object_swap
+g_closure_ref
+g_closure_unref
+g_closure_invoke
+g_closure_invalidate
+g_closure_add_fnotify
+g_closure_remove_fnotify
+g_closure_add_inotify
+g_closure_remove_inotify
+g_closure_new_simple
+g_closure_set_marshal
+g_closure_add_marshal_guards
+g_closure_set_meta_marshal
 </SECTION>

docs/reference/gobject/tmpl/closures.sgml

@@ -0,0 +1,237 @@
+<!-- ##### SECTION Title ##### -->
+Closures
+
+<!-- ##### SECTION Short_Description ##### -->
+
+
+<!-- ##### SECTION Long_Description ##### -->
+<para>
+
+</para>
+
+<!-- ##### SECTION See_Also ##### -->
+<para>
+
+</para>
+
+<!-- ##### USER_FUNCTION GClosureMarshal ##### -->
+<para>
+
+</para>
+
+@closure: 
+@return_value: 
+@n_param_values: 
+@param_values: 
+@invocation_hint: 
+@marshal_data: 
+
+
+<!-- ##### USER_FUNCTION GClosureNotify ##### -->
+<para>
+
+</para>
+
+@data: 
+@closure: 
+
+
+<!-- ##### STRUCT GClosure ##### -->
+<para>
+
+</para>
+
+@is_invalid: 
+
+<!-- ##### STRUCT GCClosure ##### -->
+<para>
+
+</para>
+
+@closure: 
+@callback: 
+
+<!-- ##### STRUCT GClosureNotifyData ##### -->
+<para>
+
+</para>
+
+@data: 
+@notify: 
+
+<!-- ##### MACRO G_CLOSURE_NEEDS_MARSHAL ##### -->
+<para>
+
+</para>
+
+@closure: 
+
+
+<!-- ##### MACRO G_CCLOSURE_SWAP_DATA ##### -->
+<para>
+
+</para>
+
+@cclosure: 
+
+
+<!-- ##### FUNCTION g_cclosure_new ##### -->
+<para>
+
+</para>
+
+@callback_func: 
+@user_data: 
+@destroy_data: 
+@Returns: 
+
+
+<!-- ##### FUNCTION g_cclosure_new_swap ##### -->
+<para>
+
+</para>
+
+@callback_func: 
+@user_data: 
+@destroy_data: 
+@Returns: 
+
+
+<!-- ##### FUNCTION g_cclosure_new_object ##### -->
+<para>
+
+</para>
+
+@callback_func: 
+@object: 
+@Returns: 
+
+
+<!-- ##### FUNCTION g_cclosure_new_object_swap ##### -->
+<para>
+
+</para>
+
+@callback_func: 
+@object: 
+@Returns: 
+
+
+<!-- ##### FUNCTION g_closure_ref ##### -->
+<para>
+
+</para>
+
+@closure: 
+@Returns: 
+
+
+<!-- ##### FUNCTION g_closure_unref ##### -->
+<para>
+
+</para>
+
+@closure: 
+
+
+<!-- ##### FUNCTION g_closure_invoke ##### -->
+<para>
+
+</para>
+
+@closure: 
+@return_value: 
+@n_param_values: 
+@param_values: 
+@invocation_hint: 
+
+
+<!-- ##### FUNCTION g_closure_invalidate ##### -->
+<para>
+
+</para>
+
+@closure: 
+
+
+<!-- ##### FUNCTION g_closure_add_fnotify ##### -->
+<para>
+
+</para>
+
+@closure: 
+@notify_data: 
+@notify_func: 
+
+
+<!-- ##### FUNCTION g_closure_remove_fnotify ##### -->
+<para>
+
+</para>
+
+@closure: 
+@notify_data: 
+@notify_func: 
+
+
+<!-- ##### FUNCTION g_closure_add_inotify ##### -->
+<para>
+
+</para>
+
+@closure: 
+@notify_data: 
+@notify_func: 
+
+
+<!-- ##### FUNCTION g_closure_remove_inotify ##### -->
+<para>
+
+</para>
+
+@closure: 
+@notify_data: 
+@notify_func: 
+
+
+<!-- ##### FUNCTION g_closure_new_simple ##### -->
+<para>
+
+</para>
+
+@sizeof_closure: 
+@data: 
+@Returns: 
+
+
+<!-- ##### FUNCTION g_closure_set_marshal ##### -->
+<para>
+
+</para>
+
+@closure: 
+@marshal: 
+
+
+<!-- ##### FUNCTION g_closure_add_marshal_guards ##### -->
+<para>
+
+</para>
+
+@closure: 
+@pre_marshal_data: 
+@pre_marshal_notify: 
+@post_marshal_data: 
+@post_marshal_notify: 
+
+
+<!-- ##### FUNCTION g_closure_set_meta_marshal ##### -->
+<para>
+
+</para>
+
+@closure: 
+@marshal_data: 
+@meta_marshal: 
+
+

docs/reference/gobject/tmpl/gobject-unused.sgml

@@ -10,3 +10,29 @@
 @G_SIGNAL_ACTION: 
 @G_SIGNAL_NO_HOOKS: 
 
+<!-- ##### FUNCTION g_signal_connect_closure ##### -->
+<para>
+
+</para>
+
+@instance: 
+@signal_id: 
+@detail: 
+@closure: 
+@after: 
+@Returns: 
+
+<!-- ##### FUNCTION g_signal_handlers_destroy ##### -->
+<para>
+
+</para>
+
+@instance: 
+
+<!-- ##### FUNCTION g_signals_destroy ##### -->
+<para>
+
+</para>
+
+@itype: 
+

docs/reference/gobject/tmpl/signals.sgml

@@ -24,7 +24,7 @@ handler" or "default (signal) handler", while user provided callbacks are
 usually just called "signal handler".
 The object method handler is provided at signal creation time (this most
 frequently happens at the end of an object class' creation), while user
-provided handlers are frequently @connected and @disconnected to/from a certain
+provided handlers are frequently connected and disconnected to/from a certain
 signal on certain object instances.
 </para>
 <para>
@@ -242,7 +242,7 @@ g_signal_query().
 @Returns: 	Newly allocated array of signal ids
 
 
-<!-- ##### FUNCTION g_signal_connect_closure ##### -->
+<!-- ##### FUNCTION g_signal_connect_closure_by_id ##### -->
 <para>
 
 </para>
@@ -271,6 +271,7 @@ to be a valid signal handler id, connected to a signal of
 @instance: 	The instance to block the signal handler of
 @handler_id: 	Handler id of the handler to be blocked
 
+
 <!-- ##### FUNCTION g_signal_handler_unblock ##### -->
 <para>
 g_signal_handler_unblock() undoes the effect of a previous
@@ -446,19 +447,18 @@ otherwise.
 @hook_id: 
 
 
-<!-- ##### FUNCTION g_signal_handlers_destroy ##### -->
+<!-- ##### FUNCTION g_signal_parse_name ##### -->
 <para>
-
+Internal function to parse a signal names into its @signal_id
+and @detail quark.
 </para>
 
-@instance: 
+@detailed_signal:	A string of the form "signal-name::detail"
-
+@itype: 		The interface/instance type taht introduced "signal-name"
-
+@signal_id_p: 		Location to store the signal id
-<!-- ##### FUNCTION g_signals_destroy ##### -->
+@detail_p: 		Location to stroe the detail quark
-<para>
+@force_detail_quark: 	%TRUE forces creation of a GQuark for the detail
-
+@Returns: 		Whether the signal name could successfully be parsed and
-</para>
+			@signal_id_p and @detail_p contain valid return values.
-
-@itype: 
 
 

gobject/ChangeLog

@@ -1,3 +1,10 @@
+Fri Nov  3 07:35:00 2000  Tim Janik  <timj@gtk.org>
+
+	* gsignal.[hc]: prefix internal functions with '_'. renamed
+	g_signal_connect_closure() to g_signal_connect_closure_by_id().
+	added g_signal_parse_name() to retrive signal_id and detail quark
+	from a signal name (internal).
+
 Wed Nov  1 03:36:54 2000  Tim Janik  <timj@gtk.org>
 
 	* gobject.c (g_object_base_class_finalize): destroy all signals that

gobject/gclosure.h

@@ -145,7 +145,7 @@ void		g_closure_invoke		(GClosure 	*closure,
 						 gpointer	 invocation_hint);
 
 
-/*
+/* FIXME:
   data_object::destroy		-> closure_invalidate();
   closure_invalidate()		-> disconnect(closure);
   disconnect(closure)		-> (unlink) closure_unref();

gobject/gobject.c

@@ -164,7 +164,7 @@ g_object_base_class_finalize (GObjectClass *class)
   
   g_message ("finallizing base class of %s", G_OBJECT_CLASS_NAME (class));
 
-  g_signals_destroy (G_OBJECT_CLASS_TYPE (class));
+  _g_signals_destroy (G_OBJECT_CLASS_TYPE (class));
   
   for (i = 0; i < class->n_param_specs; i++)
     {
@@ -295,7 +295,7 @@ g_object_do_shutdown (GObject *object)
 static void
 g_object_do_finalize (GObject *object)
 {
-  g_signal_handlers_destroy (object);
+  _g_signal_handlers_destroy (object);
   g_datalist_clear (&object->qdata);
   
 #ifdef	DEBUG_OBJECTS

gobject/gsignal.c

@@ -433,7 +433,7 @@ handler_unref_R (guint    signal_id,
     {
       if (handler->next)
         handler->next->prev = handler->prev;
-      if (handler->prev)	/* watch out for g_signal_handlers_destroy()! */
+      if (handler->prev)	/* watch out for _g_signal_handlers_destroy()! */
         handler->prev->next = handler->next;
       else
         {
@@ -568,7 +568,7 @@ g_signal_init (void) /* sync with gtype.c */
 }
 
 void
-g_signals_destroy (GType itype)
+_g_signals_destroy (GType itype)
 {
   guint i;
   
@@ -630,6 +630,80 @@ g_signal_stop_emission (gpointer instance,
   G_UNLOCK (g_signal_mutex);
 }
 
+static inline guint
+signal_parse_name (const gchar *name,
+		   GType        itype,
+		   GQuark      *detail_p,
+		   gboolean     force_quark)
+{
+  const gchar *colon = strchr (name, ':');
+  guint signal_id;
+  
+  if (!colon)
+    {
+      signal_id = signal_id_lookup (g_quark_try_string (name), itype);
+      if (signal_id && detail_p)
+	*detail_p = 0;
+    }
+  else if (colon[1] == ':')
+    {
+      gchar buffer[32];
+      guint l = colon - name;
+      
+      if (l < 32)
+	{
+	  memcpy (buffer, name, l);
+	  buffer[l] = 0;
+	  signal_id = signal_id_lookup (g_quark_try_string (buffer), itype);
+	}
+      else
+	{
+	  gchar *signal = g_new (gchar, l + 1);
+	  
+	  memcpy (signal, name, l);
+	  signal[l] = 0;
+	  signal_id = signal_id_lookup (g_quark_try_string (signal), itype);
+	  g_free (signal);
+	}
+      
+      if (signal_id && detail_p)
+	*detail_p = colon[2] ? (force_quark ? g_quark_from_string : g_quark_try_string) (colon + 2) : 0;
+    }
+  else
+    signal_id = 0;
+  return signal_id;
+}
+
+gboolean
+g_signal_parse_name (const gchar *detailed_signal,
+		     GType        itype,
+		     guint       *signal_id_p,
+		     GQuark      *detail_p,
+		     gboolean	  force_detail_quark)
+{
+  GQuark detail = 0;
+  guint signal_id;
+
+  g_return_val_if_fail (detailed_signal != NULL, FALSE);
+  g_return_val_if_fail (G_TYPE_IS_INSTANTIATABLE (itype) || G_TYPE_IS_INTERFACE (itype), FALSE);
+
+  G_LOCK (g_signal_mutex);
+  signal_id = signal_parse_name (detailed_signal, itype, &detail, force_detail_quark);
+  G_UNLOCK (g_signal_mutex);
+
+  if (signal_id)
+    {
+      if (signal_id_p)
+	*signal_id_p = signal_id;
+      if (detail_p)
+	*detail_p = detail;
+
+      return TRUE;
+    }
+  else
+    return FALSE;
+}
+
 guint
 g_signal_lookup (const gchar *name,
                  GType        itype)
@@ -871,7 +945,7 @@ signal_destroy_R (SignalNode *signal_node)
 }
 
 guint
-g_signal_connect_closure (gpointer  instance,
+g_signal_connect_closure_by_id (gpointer  instance,
 				guint     signal_id,
 				GQuark    detail,
 				GClosure *closure,
@@ -982,7 +1056,7 @@ g_signal_handler_disconnect (gpointer instance,
 }
 
 void
-g_signal_handlers_destroy (gpointer instance)
+_g_signal_handlers_destroy (gpointer instance)
 {
   GBSearchArray *hlbsa;
   

gobject/gsignal.h

@@ -122,7 +122,7 @@ gboolean g_signal_has_handler_pending	      (gpointer		  instance,
 					       guint		  signal_id,
 					       GQuark		  detail,
 					       gboolean		  may_be_blocked);
-guint	 g_signal_connect_closure	      (gpointer		  instance,
+guint	 g_signal_connect_closure_by_id	      (gpointer		  instance,
 					       guint		  signal_id,
 					       GQuark		  detail,
 					       GClosure		 *closure,
@@ -164,8 +164,13 @@ guint	 g_signal_handlers_disconnect_matched (gpointer		  instance,
 
 
 /*< private >*/
-void	g_signal_handlers_destroy	      (gpointer		  instance);
+gboolean g_signal_parse_name		      (const gchar	 *detailed_signal,
-void	g_signals_destroy		      (GType		  itype);
+					       GType		  itype,
+					       guint		 *signal_id_p,
+					       GQuark		 *detail_p,
+					       gboolean		  force_detail_quark);
+void	 _g_signal_handlers_destroy	      (gpointer		  instance);
+void	 _g_signals_destroy		      (GType		  itype);
 
 
 #ifdef __cplusplus