From 57d0ec57e43ce9b98a76fc7d07b3b5827481e516 Mon Sep 17 00:00:00 2001
From: Philip Withnall <philip.withnall@collabora.co.uk>
Date: Tue, 24 Feb 2015 08:50:53 +0000
Subject: [PATCH] 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 4277fe755..6a1420a63 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 2bb1264e0..701551d2a 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>