Description

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.

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 must surround
timeouts and idle functions in this matter.

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.)

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.

Details

GDK_THREADS_ENTER()

#define GDK_THREADS_ENTER()

This macro marks the beginning of a critical section in which GDK and
GTK+ functions can be called safely and without causing race
conditions. Only one thread at a time can be in such a critial
section. The macro expands to a no-op if G_THREADS_ENABLED has not
been defined. Typically gdk_threads_enter() should be used instead of
this macro.

This call must be made before any use of the main loop from
GTK+; to be safe, call it before gtk_init().

gdk_threads_enter ()

void gdk_threads_enter (void);

This macro marks the beginning of a critical section in which GDK and
GTK+ functions can be called safely and without causing race
conditions. Only one thread at a time can be in such a critial
section.

The functions must provide at least same locking functionality
as the default implementation, but can also do extra application
specific processing.

As an example, consider an application that has its own recursive
lock that when held, holds the GTK+ lock as well. When GTK+ unlocks
the GTK+ lock when entering a recursive main loop, the application
must temporarily release its lock as well.

Most threaded GTK+ apps won't need to use this method.

This method must be called before gdk_threads_init(), and cannot
be called multiple times.

gdk_threads_add_idle_full ()

Adds a function to be called whenever there are no higher priority
events pending. If the function returns FALSE it is automatically
removed from the list of event sources and will not be called again.

This variant of g_idle_add_full() calls function with the GDK lock
held. It can be thought of a MT-safe version for GTK+ widgets for the
following use case, where you have to worry about idle_callback()
running in thread A and accessing self after it has been finalized
in thread B:

gdk_threads_add_timeout_full ()

Sets a function to be called at regular intervals holding the GDK lock,
with the given priority. The function is called repeatedly until it
returns FALSE, at which point the timeout is automatically destroyed
and the function will not be called again. The notify function is
called when the timeout is destroyed. The first call to the
function will be at the end of the first interval.

Note that timeout functions may be delayed, due to the processing of other
event sources. Thus they should not be relied on for precise timing.
After each call to the timeout function, the time of the next
timeout is recalculated based on the current time and the given interval
(it does not try to 'catch up' time lost in delays).

This variant of g_timeout_add_full() can be thought of a MT-safe version
for GTK+ widgets for the following use case: