Threads

## Threads Threads — Functions for using GDK in multi-threaded programs |

## Functions

#define | GDK_THREADS_ENTER
#define | GDK_THREADS_LEAVE
void | gdk_threads_init ()
void | gdk_threads_enter ()
void | gdk_threads_leave ()
void | gdk_threads_set_lock_functions ()
guint | gdk_threads_add_idle ()
guint | gdk_threads_add_idle_full ()
guint | gdk_threads_add_timeout ()
guint | gdk_threads_add_timeout_full ()
guint | gdk_threads_add_timeout_seconds ()
guint | gdk_threads_add_timeout_seconds_full ()

## Includes

    #include <gdk/gdk.h>

## 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()`:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    static void
    worker_thread (void)
    {
      ExpensiveData *expensive_data = do_expensive_computation ();

      gdk_threads_add_idle (got_value, expensive_data);
    }

    static gboolean
    got_value (gpointer user_data)
    {
      ExpensiveData *expensive_data = user_data;

      my_app->expensive_data = expensive_data;
      gtk_button_set_sensitive (my_app->button, TRUE);
      gtk_button_set_label (my_app->button, expensive_data->result_label);

      return G_SOURCE_REMOVE;
    }

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]

#### Parameters

enter_fn | function called to guard GDK |
leave_fn | function called to release the guard |

Since: 2.4

### gdk_threads_add_idle ()

    guint
    gdk_threads_add_idle (GSourceFunc function,
                          gpointer data);

A wrapper for the common usage of `gdk_threads_add_idle_full()` assigning the default priority, G_PRIORITY_DEFAULT_IDLE.

See `gdk_threads_add_idle_full()`.

[skip]

#### Parameters

function | function to call |
data | data to pass to `function` |

#### Returns

the ID (greater than 0) of the event source.

Since: 2.12

### 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:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    26
    27
    28
    29
    static gboolean
    idle_callback (gpointer data)
    {
       // gdk_threads_enter(); would be needed for g_idle_add()

       SomeWidget *self = data;
       // do stuff with self

       self->idle_id = 0;

       // gdk_threads_leave(); would be needed for g_idle_add()
       return FALSE;
    }

    static void
    some_widget_do_stuff_later (SomeWidget *self)
    {
       self->idle_id = gdk_threads_add_idle (idle_callback, self)
       // using g_idle_add() here would require thread protection in the callback
    }

    static void
    some_widget_finalize (GObject *object)
    {
       SomeWidget *self = SOME_WIDGET (object);
       if (self->idle_id)
         g_source_remove (self->idle_id);
       G_OBJECT_CLASS (parent_class)->finalize (object);
    }

[rename-to gdk_threads_add_idle]

#### Parameters

priority | the priority of the idle source. Typically this will be in the range between G_PRIORITY_DEFAULT_IDLE and G_PRIORITY_HIGH_IDLE |
function | function to call |
data | data to pass to `function` |
notify | function to call when the idle is removed, or `NULL`. | [allow-none]

#### Returns

the ID (greater than 0) of the event source.

Since: 2.12

### gdk_threads_add_timeout ()

    guint
    gdk_threads_add_timeout (guint interval,
                             GSourceFunc function,
                             gpointer data);

A wrapper for the common usage of `gdk_threads_add_timeout_full()` assigning the default priority, G_PRIORITY_DEFAULT.

See `gdk_threads_add_timeout_full()`.

[skip]

#### Parameters

interval | the time between calls to the function, in milliseconds (1/1000ths of a second) |
function | function to call |
data | data to pass to `function` |

#### 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:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    18
    19
    20
    21
    22
    23
    24
    25
    static gboolean timeout_callback (gpointer data)
    {
       SomeWidget *self = data;

       // do stuff with self

       self->timeout_id = 0;

       return G_SOURCE_REMOVE;
    }

    static void some_widget_do_stuff_later (SomeWidget *self)
    {
       self->timeout_id = g_timeout_add (timeout_callback, self)
    }

    static void some_widget_finalize (GObject *object)
    {
       SomeWidget *self = SOME_WIDGET (object);

       if (self->timeout_id)
         g_source_remove (self->timeout_id);

       G_OBJECT_CLASS (parent_class)->finalize (object);
    }

[rename-to gdk_threads_add_timeout]

#### Parameters

priority | the priority of the timeout source. Typically this will be in the range between G_PRIORITY_DEFAULT_IDLE and G_PRIORITY_HIGH_IDLE. |
interval | the time between calls to the function, in milliseconds (1/1000ths of a second) |
function | function to call |
data | data to pass to `function` |
notify | function to call when the timeout is removed, or `NULL`. | [allow-none]

#### Returns

the ID (greater than 0) of the event source.

Since: 2.12

### gdk_threads_add_timeout_seconds ()

    guint
    gdk_threads_add_timeout_seconds (guint interval,
                                     GSourceFunc function,
                                     gpointer data);

A wrapper for the common usage of `gdk_threads_add_timeout_seconds_full()` assigning the default priority, G_PRIORITY_DEFAULT.

For details, see `gdk_threads_add_timeout_full()`.

[skip]

#### Parameters

interval | the time between calls to the function, in seconds |
function | function to call |
data | data to pass to `function` |

#### Returns

the ID (greater than 0) of the event source.

Since: 2.14

### gdk_threads_add_timeout_seconds_full ()

    guint
    gdk_threads_add_timeout_seconds_full (gint priority,
                                          guint interval,
                                          GSourceFunc function,
                                          gpointer data,
                                          GDestroyNotify notify);

A variant of `gdk_threads_add_timeout_full()` with second-granularity. See `g_timeout_add_seconds_full()` for a discussion of why it is a good idea to use this function if you don’t need finer granularity.

[rename-to gdk_threads_add_timeout_seconds]

#### Parameters

priority | the priority of the timeout source. Typically this will be in the range between G_PRIORITY_DEFAULT_IDLE and G_PRIORITY_HIGH_IDLE. |
interval | the time between calls to the function, in seconds |
function | function to call |
data | data to pass to `function` |
notify | function to call when the timeout is removed, or `NULL`. | [allow-none]

#### Returns

the ID (greater than 0) of the event source.

Since: 2.14