[gtk+] Improve threading documentation

[Matthias Clasen <matthiasc src gnome org>]

commit b936666b52bc07bb7ad9349f10f6849744ffb59d
Author: Matthias Clasen <mclasen redhat com>
Date:   Mon Jul 30 10:44:22 2012 +0200

    Improve threading documentation
    
    This commit just adds a small section to the threading documentation
    about the deprecation. More is needed here, including a migration
    example.

 gdk/gdk.c |   17 +++++++++++++----
 1 files changed, 13 insertions(+), 4 deletions(-)
---
diff --git a/gdk/gdk.c b/gdk/gdk.c
index cf81863..752625e 100644
--- a/gdk/gdk.c
+++ b/gdk/gdk.c
@@ -448,10 +448,6 @@ gdk_init (int *argc, char ***argv)
  * which protects all use of GTK+. That is, only one thread can use GTK+
  * at any given time.
  *
- * Unfortunately the above holds with the X11 backend only. With the
- * Win32 backend, GDK calls should not be attempted from multiple threads
- * at all.
- *
  * You must call gdk_threads_init() before executing any other GTK+ or
  * GDK functions in a threaded GTK+ program.
  *
@@ -653,6 +649,19 @@ gdk_init (int *argc, char ***argv)
  * }
  * </programlisting>
  * </informalexample>
+ *
+ * Unfortunately, all of the above documentation holds with the X11
+ * backend only. With the Win32 backend, GDK and GTK+ calls should not
+ * be attempted from multiple threads at all. Combining the GDK lock
+ * with other locks such as the Python global interpreter lock can be
+ * complicated.
+ *
+ * For these reason, the threading support has been deprecated in
+ * GTK+ 3.6. Instead of calling GTK+ directly from multiple threads,
+ * it is recommended to use g_idle_add(), g_main_context_invoke()
+ * and similar functions to make these calls from the main thread
+ * instead. The main thread is the thread which has called gtk_init()
+ * and is running the GTK+ mainloop.
  */