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+, however, is not thread safe. You should only use GTK+ and GDK
from the thread gtk_init() and gtk_main() were called on.
This is usually referred to as the “main thread”.
Signals on GTK+ and GDK types, as well as non-signal callbacks, are
emitted in the main thread.
You can schedule work in the main thread safely from other threads
by using gdk_threads_add_idle() and gdk_threads_add_timeout():
You should use gdk_threads_add_idle() and gdk_threads_add_timeout()
instead of g_idle_add() and g_timeout_add() since libraries not under
your control might be using the deprecated GDK locking mechanism.
If you are sure that none of the code in your application and libraries
use the deprecated gdk_threads_enter() or gdk_threads_leave() methods,
then you can safely use g_idle_add() and g_timeout_add().
For more information on this "worker thread" pattern, you should
also look at GTask, which gives you high-level tools to perform
expensive tasks from worker threads, and will handle thread
management for you.
Functions
GDK_THREADS_ENTER
#define GDK_THREADS_ENTER() gdk_threads_enter()
GDK_THREADS_ENTER has been deprecated since version 3.6 and should not be used in newly-written code.
Use g_main_context_invoke(), g_idle_add() and related
functions if you need to schedule GTK+ calls from other threads.
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.
GDK_THREADS_LEAVE
#define GDK_THREADS_LEAVE() gdk_threads_leave()
GDK_THREADS_LEAVE has been deprecated since version 3.6 and should not be used in newly-written code.
Deprecated in 3.6.
This macro marks the end of a critical section
begun with GDK_THREADS_ENTER.
gdk_threads_init ()
void
gdk_threads_init (void);
gdk_threads_init has been deprecated since version 3.6 and should not be used in newly-written code.
All GDK and GTK+ calls should be made from the main
thread
Initializes GDK so that it can be used from multiple threads
in conjunction with gdk_threads_enter() and gdk_threads_leave().
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);
gdk_threads_enter has been deprecated since version 3.6 and should not be used in newly-written code.
All GDK and GTK+ calls should be made from the main
thread
This function 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.
gdk_threads_leave ()
void
gdk_threads_leave (void);
gdk_threads_leave has been deprecated since version 3.6 and should not be used in newly-written code.
All GDK and GTK+ calls should be made from the main
thread
Leaves a critical region begun with gdk_threads_enter().
gdk_threads_set_lock_functions ()
void
gdk_threads_set_lock_functions (GCallback enter_fn,
GCallback leave_fn);
gdk_threads_set_lock_functions has been deprecated since version 3.6 and should not be used in newly-written code.
All GDK and GTK+ calls should be made from the main
thread
Allows the application to replace the standard method that
GDK uses to protect its data structures. Normally, GDK
creates a single GMutex that is locked by gdk_threads_enter(),
and released by gdk_threads_leave(); using this function an
application provides, instead, a function enter_fn
that is
called by gdk_threads_enter() and a function leave_fn
that is
called by gdk_threads_leave().
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.
[skip]
Since: 2.4
gdk_threads_add_idle_full ()
guint
gdk_threads_add_idle_full (gint priority,
GSourceFunc function,
gpointer data,
GDestroyNotify notify);
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:
[rename-to gdk_threads_add_idle]
Returns
the ID (greater than 0) of the event source.
Since: 2.12
gdk_threads_add_timeout_full ()
guint
gdk_threads_add_timeout_full (gint priority,
guint interval,
GSourceFunc function,
gpointer data,
GDestroyNotify notify);
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:
[rename-to gdk_threads_add_timeout]
Returns
the ID (greater than 0) of the event source.
Since: 2.12