
@c %start of fragment

@node Threads
@chapter Threads
Functions for using GDK in multi-threaded programs

@section Overview
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 @code{<g-hash-table>}
from multiple threads.

GTK+ is "thread aware" but not thread safe &#x2014; it provides a global lock
controlled by @code{gdk-threads-enter}/@code{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 @code{g-thread-init} and @code{gdk-threads-init} before executing
any other GTK+ or GDK functions in a threaded GTK+ program.

Idles, timeouts, and input functions 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 @code{gdk-threads-enter}/@code{gdk-threads-leave} pair.
(However, signals are still executed within the main GTK+ lock.)

In particular, this means, if you are writing widgets that might be used in
threaded programs, you @emph{must} 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 @code{gdk-threads-enter}/@code{gdk-threads-leave} pair.

Before calling @code{gdk-threads-leave} from a thread other than your main
thread, you probably want to call @code{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:

@example 

int
main (int argc, char *argv[])
@{
  GtkWidget *window;

  g_thread_init (NULL);
  gdk_threads_init ();
  gdk_threads_enter ();

  gtk_init (&argc, &argv);

  window = create_window ();
  gtk_widget_show (window);

  gtk_main ();
  gdk_threads_leave ();

  return 0;
@}
@end example

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 @code{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.

@example 

/*-------------------------------------------------------------------------
 * 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.
 *
 */

&#x0023;include <stdio.h>
&#x0023;include <stdlib.h>
&#x0023;include <unistd.h>
&#x0023;include <time.h>
&#x0023;include <gtk/gtk.h>
&#x0023;include <glib.h>
&#x0023;include <pthread.h>

&#x0023;define YES_IT_IS    (1)
&#x0023;define NO_IT_IS_NOT (0)

typedef struct 
@{
  GtkWidget *label;
  int what;
@} yes_or_no_args;

G_LOCK_DEFINE_STATIC (yes_or_no);
static volatile int yes_or_no = YES_IT_IS;

void destroy (GtkWidget *widget, gpointer data)
@{
  gtk_main_quit ();
@}

void *argument_thread (void *args)
@{
  yes_or_no_args *data = (yes_or_no_args *)args;
  gboolean say_something;

  for (;;)
    @{
      /* sleep a while */
      sleep(rand() / (RAND_MAX / 3) + 1);

      /* lock the yes_or_no_variable */
      G_LOCK(yes_or_no);

      /* do we have to say something? */
      say_something = (yes_or_no != data->what);

      if(say_something)
	@{
	  /* set the variable */
	  yes_or_no = data->what;
	@}

      /* Unlock the yes_or_no variable */
      G_UNLOCK (yes_or_no);

      if (say_something)
	@{
	  /* get GTK thread lock */
	  gdk_threads_enter ();

	  /* set label text */
	  if(data->what == YES_IT_IS)
	    gtk_label_set_text (GTK_LABEL (data->label), "O yes, it is!");
	  else
	    gtk_label_set_text (GTK_LABEL (data->label), "O no, it isn't!");

	  /* release GTK thread lock */
	  gdk_threads_leave ();
	@}
    @}

  return NULL;
@}

int main (int argc, char *argv[])
@{
  GtkWidget *window;
  GtkWidget *label;
  yes_or_no_args yes_args, no_args;
  pthread_t no_tid, yes_tid;

  /* init threads */
  g_thread_init (NULL);
  gdk_threads_init ();
  gdk_threads_enter ();

  /* init gtk */
  gtk_init(&argc, &argv);

  /* init random number generator */
  srand ((unsigned int) time (NULL));

  /* create a window */
  window = gtk_window_new (GTK_WINDOW_TOPLEVEL);

  gtk_signal_connect (GTK_OBJECT (window), "destroy",
		      GTK_SIGNAL_FUNC (destroy), NULL);

  gtk_container_set_border_width (GTK_CONTAINER (window), 10);

  /* create a label */
  label = gtk_label_new ("And now for something completely different ...");
  gtk_container_add (GTK_CONTAINER (window), label);
  
  /* show everything */
  gtk_widget_show (label);
  gtk_widget_show (window);

  /* create the threads */
  yes_args.label = label;
  yes_args.what = YES_IT_IS;
  pthread_create (&yes_tid, NULL, argument_thread, &yes_args);

  no_args.label = label;
  no_args.what = NO_IT_IS_NOT;
  pthread_create (&no_tid, NULL, argument_thread, &no_args);

  /* enter the GTK main loop */
  gtk_main ();
  gdk_threads_leave ();

  return 0;
@}
@end example

@section Usage
@include defuns-threads.xml.texi

@c %end of fragment
