[glib] docs: Clarify costs of using the generic GObject C closure marshaller

[Philip Withnall <pwithnall src gnome org>]

commit 57d0ec57e43ce9b98a76fc7d07b3b5827481e516
Author: Philip Withnall <philip withnall collabora co uk>
Date:   Tue Feb 24 08:50:53 2015 +0000

    docs: Clarify costs of using the generic GObject C closure marshaller
    
    The libffi one is slower than type-specific generated ones, but is
    generally better to use.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=744060

 docs/reference/gobject/tut_gsignal.xml |    3 ++-
 docs/reference/gobject/tut_howto.xml   |   19 +++++++++++++++----
 2 files changed, 17 insertions(+), 5 deletions(-)
---
diff --git a/docs/reference/gobject/tut_gsignal.xml b/docs/reference/gobject/tut_gsignal.xml
index 4277fe7..6a1420a 100644
--- a/docs/reference/gobject/tut_gsignal.xml
+++ b/docs/reference/gobject/tut_gsignal.xml
@@ -124,7 +124,8 @@ return_type function_callback (… , gpointer user_data);
         A generic C closure marshaller is available as
         <link linkend="g-cclosure-marshal-generic"><function>g_cclosure_marshal_generic</function></link>
         which implements marshalling for all function types using libffi. Custom
-        marshallers for different types are not needed.
+        marshallers for different types are not needed apart from performance
+        critical code where the libffi-based marshaller may be too slow.
       </para>
 
       <para>
diff --git a/docs/reference/gobject/tut_howto.xml b/docs/reference/gobject/tut_howto.xml
index 2bb1264..701551d 100644
--- a/docs/reference/gobject/tut_howto.xml
+++ b/docs/reference/gobject/tut_howto.xml
@@ -1369,7 +1369,7 @@ file_signals[CHANGED] =
                  NULL /* closure */,
                  NULL /* accumulator */,
                  NULL /* accumulator data */,
-                 g_cclosure_marshal_generic,
+                 NULL /* C marshaller */,
                  G_TYPE_NONE /* return_type */,
                  0     /* n_params */,
                  NULL  /* param_types */);
@@ -1396,11 +1396,22 @@ maman_file_write (MamanFile    *self,
     </para>
 
     <para>
-      The C signal marshaller should always be
+      The C signal marshaller should always be <literal>NULL</literal>, in which
+      case the best marshaller for the given closure type will be chosen by
+      GLib. This may be an internal marshaller specific to the closure type, or
       <function>g_cclosure_marshal_generic</function>, which implements generic
       conversion of arrays of parameters to C callback invocations. GLib used to
-      use type-specific generated marshallers, but that has been deprecated in
-      favour of the generic marshaller.
+      require the user to write or generate a type-specific marshaller and pass
+      that, but that has been deprecated in favour of automatic selection of
+      marshallers.
+    </para>
+
+    <para>
+      Note that <function>g_cclosure_marshal_generic</function> is slower than
+      non-generic marshallers, so should be avoided for performance critical
+      code. However, performance critical code should rarely be using signals
+      anyway, as emitting a signal blocks on emitting it to all listeners, which
+      has potentially unbounded cost.
     </para>
   </sect1>
 </chapter>