+
+
+/**
+ * SECTION:threads
+ * @Short_description: Functions for using GDK in multi-threaded programs
+ * @Title: Threads
+ *
+ * For thread safety, GDK relies on the thread primitives in GLib,
+ * and on the thread-safe GLib main loop.
+ *
+ * GLib is completely thread safe (all global data is automatically
+ * locked), but individual data structure instances are not automatically
+ * locked for performance reasons. So e.g. you must coordinate
+ * accesses to the same #GHashTable from multiple threads.
+ *
+ * GTK+ is "thread aware" but not thread safe — it provides a
+ * global lock controlled by gdk_threads_enter()/gdk_threads_leave()
+ * 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.
+ *
+ * Idles, timeouts, and input functions from GLib, such as g_idle_add(),
+ * are executed outside of the main GTK+ lock. So, if you need to call
+ * GTK+ inside of such a callback, you must surround the callback with
+ * a gdk_threads_enter()/gdk_threads_leave() pair or use
+ * gdk_threads_add_idle_full() which does this for you.
+ * However, event dispatching from the mainloop is still executed within
+ * the main GTK+ lock, so callback functions connected to event signals
+ * like #GtkWidget::button-press-event, do not need thread protection.
+ *
+ * In particular, this means, if you are writing widgets that might
+ * be used in threaded programs, you <emphasis>must</emphasis> surround
+ * timeouts and idle functions in this matter.
+ *
+ * As always, you must also surround any calls to GTK+ not made within
+ * a signal handler with a gdk_threads_enter()/gdk_threads_leave() pair.
+ *
+ * Before calling gdk_threads_leave() from a thread other
+ * than your main thread, you probably want to call gdk_flush()
+ * to send all pending commands to the windowing system.
+ * (The reason you don't need to do this from the main thread
+ * is that GDK always automatically flushes pending commands
+ * when it runs out of incoming events to process and has
+ * to sleep while waiting for more events.)
+ *
+ * A minimal main program for a threaded GTK+ application
+ * looks like:
+ * <informalexample>
+ * <programlisting role="C">
+ * int
+ * main (int argc, char *argv[])
+ * {
+ * GtkWidget *window;
+ *
+ * gdk_threads_init (<!-- -->);
+ * gdk_threads_enter (<!-- -->);
+ *
+ * gtk_init (&argc, &argv);
+ *
+ * window = create_window (<!-- -->);
+ * gtk_widget_show (window);
+ *
+ * gtk_main (<!-- -->);
+ * gdk_threads_leave (<!-- -->);
+ *
+ * return 0;
+ * }
+ * </programlisting>
+ * </informalexample>
+ *
+ * Callbacks require a bit of attention. Callbacks from GTK+ signals
+ * are made within the GTK+ lock. However callbacks from GLib (timeouts,
+ * IO callbacks, and idle functions) are made outside of the GTK+
+ * lock. So, within a signal handler you do not need to call
+ * gdk_threads_enter(), but within the other types of callbacks, you
+ * do.
+ *
+ * Erik Mouw contributed the following code example to
+ * illustrate how to use threads within GTK+ programs.
+ * <informalexample>
+ * <programlisting role="C">
+ * /<!---->*-------------------------------------------------------------------------
+ * * Filename: gtk-thread.c
+ * * Version: 0.99.1
+ * * Copyright: Copyright (C) 1999, Erik Mouw
+ * * Author: Erik Mouw <J.A.K.Mouw@its.tudelft.nl>
+ * * Description: GTK threads example.
+ * * Created at: Sun Oct 17 21:27:09 1999
+ * * Modified by: Erik Mouw <J.A.K.Mouw@its.tudelft.nl>
+ * * Modified at: Sun Oct 24 17:21:41 1999
+ * *-----------------------------------------------------------------------*<!---->/
+ * /<!---->*
+ * * Compile with:
+ * *
+ * * cc -o gtk-thread gtk-thread.c `gtk-config --cflags --libs gthread`
+ * *
+ * * Thanks to Sebastian Wilhelmi and Owen Taylor for pointing out some
+ * * bugs.
+ * *
+ * *<!---->/