1. Home
  2. Tutorials
  3. C/C++
  4. GDK Threads API
Yolinux.com Tutorial

GNOME GDK Threads: Cross platform g_threads programming API

This YoLinux.com GDK threads tutorial is aimed at C/C++ application developers who wish to write parallel processing software with a single multiplatform API.

The GDK2 Threads Reference Manual is a valuable resource for basic use of this API.

GDK Threads Tutorial Contents:
Introduction to GDK threads:

This tutorial will cover using the Gnome GDK thread library to build a multi-threaded, parallel processing application for cross platform deployment.

GDK threads is a component of the GNOME applications development environment which also includes multi-platform API's for GUIs, graphics, video, window management, XML parsing, internationalization, database access and general application development. The GNOME thread libraries can be used without the GNOME desktop or GUI infrastructure. The API's support the "C" computer language. I usually encapsulate these calls within C++ objects where convenient.

Threads allow one to spawn a new concurrent process flow. It is most effective on multiprocessor systems where the process flow can be scheduled by the operating system to run on another processor thus gaining speed through parallel or distributed processing. The GNOME thread libraries are not a feature rich as POSIX threads but do provide the basic infrastructure.

For more information on programming threads and concepts, see the YoLinux POSIX Threads Tutorial.

For downloading, installation and configuration of the development environment on Ms/Windows with MS/Visual C++ or Cygwin as well as Linux see the YoLinux GTK+ Programming Tutorial

Program Framework:

The basic framework of a GDK multi-threaded program requires:

  • the include file: gtk/gtk.h
  • functions to spawn in a separate thread.
  • main program.
  • a call to gtk_init (&argc, &argv);
  • calls to initialize the threads infrastructure: g_thread_init() and gdk_threads_init().
  • spawn a thread: g_thread_create()
  • protect data from corruption and contention issues with gdk_threads_mutex
  • if not using processing time and you wish to "yield" to other tasks call g_thread_yield()
  • if a GTK+ GUI application, protect GTK+ calls using gdk_threads_enter() and gdk_threads_leave()
  • Pass conditional information to a thread using g_cond_signal()
  • wait to complete thread process: g_thread_join() or terminate (riskier due to race condition potential) using g_thread_exit().

view sourceprint?
01#include <gtk>
02 
03void *print_message_function( void *ptr );
04 
05int main()
06{
07  GThread          *Thread1, *Thread2;
08  char *message1 = "Thread 1";
09  char *message2 = "Thread 2";
10  GError           *err1 = NULL ;
11  GError           *err2 = NULL ;
12 
13  if( !g_thread_supported() )
14  {
15     g_thread_init(NULL);
16     gdk_threads_init();                   // Called to initialize internal mutex "gdk_threads_mutex".
17     printf("g_thread supported\n");
18  }
19  else
20  {
21     printf("g_thread NOT supported\n");
22  }
23 
24  if( (Thread1 = g_thread_create((GThreadFunc)print_message_function, (void *)message1, TRUE, &err1)) == NULL)
25  {
26     printf("Thread create failed: %s!!\n", err1->message );
27     g_error_free ( err1 ) ;
28  }
29 
30  if( (Thread2 = g_thread_create((GThreadFunc)print_message_function, (void *)message2, TRUE, &err2)) == NULL)
31  {
32     printf("Thread create failed: %s!!\n", err2->message );
33     g_error_free ( err2 ) ;
34  }
35 
36  g_thread_join(Thread1);
37  g_thread_join(Thread2);
38 
39  return 0;
40}
41 
42void *print_message_function( void *ptr )
43{
44     char *message;
45     g_usleep(1000000);
46     message = (char *) ptr;
47     printf("%s \n", message);
48     g_usleep(1000000);
49     printf("%s \n", message);
50}

Linux Compile: gcc -o gdk-thread-only gdk-thread-only.c `pkg-config --cflags --libs gtk+-2.0 gthread-2.0`

Results: 

[prompt]$ gdk-thread-only
g_thread supported
Thread 1
Thread 2
Thread 1
Thread 2

Mutex:

A mutex is necessary to protect data from corruption or unexpected behavior.
See the YoLinux POSIX threads tutorial discussion on mutexes and thread synchronization.

Declare mutex outside of thread scope where it is visible to threaded function:

  • C++ class member variable initialized in constructor.
  • Global variable.
Code snippet:
view sourceprint?
01..
02...
03 
04// Declare outside of thread scope:
05static GMutex *mutex_to_protext_variable_ABC = NULL;
06 
07...
08..
09 
10// Initialize Mutex
11 
12g_assert (mutex_to_protext_variable_ABC == NULL);
13 
14mutex_to_protext_variable_ABC = g_mutex_new();
15 
16...
17..
18 
19// Within threaded function, protect variable with a mutex.
20 
21g_mutex_lock(mutex_to_protext_variable_ABC);
22 
23ABC = updateFunction();
24 
25g_mutex_unlock(mutex_to_protext_variable_ABC);
26 
27...
28..

Notes:

  • All of the g_mutex_* functions are actually macros.
  • This is an example of a dynamic mutex created at run time. You may also use a static mutex defined at compile time. I have not had good luck in using static mutexes and find the "dynamic" mutex more usable.
  • Considerations when updating GTK+ GUI from a GDK thread

Yielding processing time:

The GDK thread can communicate with the operating system scheduler to yield processing time to other threads. This is preferable to a spinning a loop to delay a thread.

view sourceprint?
01..
02...
03   if ( haveExtraTime )
04   {
05      if (gtk_events_pending())
06      {
07          gtk_main_iteration(); // Handle unprocessed GTK events
08      }
09      else
10      {
11          g_thread_yield();     // Yield processing time
12      }
13   }
14 
15...
16..

Pitfalls:

[Potential Pitfall]: When using this cross platform API on Microsoft Windows and compiling with Visual Studio VC++ compiler be sure to use the proper compiler flag to use the appropriate libraries:

  • Use: /MTd Use debug, multi-threaded, libraries
  • DO NOT USE: MLd => Use debug, single-threaded, libraries
If you use the single threaded debug libraries, a call to printf to print local variables may cause a crash.

Links: