← Back to branch summary

~canonical-dx-team/ubuntu/maverick/gtk+2.0/menuproxy

« back to all changes in this revision

Viewing changes to docs/reference/gdk/tmpl/threads.sgml

  • Committer: Bazaar Package Importer
  • Author(s): Sebastien Bacher
  • Date: 2007-05-04 12:24:25 UTC
  • mfrom: (1.1.21 upstream)
  • Revision ID: james.westby@ubuntu.com-20070504122425-0m8midgzrp40y8w2
Tags: 2.10.12-1ubuntu1
* Sync with Debian
* New upstream version:
  Fixed bugs:
  - 379414 file chooser warnings when changing path in the entry
  - 418585 GtkFileChooserDefault sizing code is not DPI independent
  - 419568 Crash in search if start with special letter
  - 435062 build dies with icon cache validation
  - 379399 Segfault to call gtk_print_operation_run twice.
  - 387889 cups backend has problems when there are too many printers
  - 418531 invalid read to gtkicontheme.c gtk_icon_theme_lookup_icon...
  - 423916 crash in color scheme code
  - 424042 Segmentation fault while quickly pressing Alt+arrows
  - 415260 Protect against negative indices when setting values in G...
  - 419171 XGetVisualInfo() may not set nxvisuals
  - 128852 Gdk cursors don't look good on win32
  - 344657 Ctrl-H doesn't toggle "Show Hidden Files" setting
  - 345345 PrintOperation::paginate is not emitted for class handler
  - 347567 GtkPrintOperation::end-print is not emitted if it's cance...
  - 369112 gtk_ui_manager_add_ui should accept unnamed separator
  - 392015 Selected menu item invisible on Windows Vista
  - 399253 MS-Windows Theme Bottom Tab placement rendering glitches
  - 399425 gtk_input_dialog_fill_axes() adds child to gtkscrolledwin...
  - 403251 [patch] little memory leak in GtkPrintJob
  - 403267 [patch] memory leak in GtkPageSetupUnixDialog
  - 403470 MS-Windows Theme tab placement other than on top leaks a ...
  - 404506 Windows system fonts that have multi-byte font names cann...
  - 405089 Incorrect window placement for GtkEventBox private window
  - 405515 Minor leak in gtkfilesystemmodel.c
  - 405539 gdk_pixbuf_save() for PNG saver can return FALSE without ...
  - 415681 gdk_window_clear_area includes an extra line and column o...
  - 418219 GtkRecentChooser should apply filter before sorting and c...
  - 418403 Scroll to printer after selecting it from settings
  - 421985 _gtk_print_operation_platform_backend_launch_preview
  - 421990 gtk_print_job_get_surface
  - 421993 gtk_print_operation_init
  - 423064 Conditional jump or move depends on uninitialised value(s...
  - 423722 Fix printing header in gtk-demo
  - 424168 gtk_print_operation_run on async preview
  - 425655 Don't install gtk+-unix-print-2.0.pc on non-UNIX platforms
  - 425786 GDK segfaults if XineramaQueryScreens fails
  - 428665 Lpr Backend gets stuck in infinite loop during gtk_enumer...
  - 429902 GtkPrintOperation leaks cairo contextes
  - 431997 First delay of GdkPixbufAnimationIter is wrong
  - 433242 Inconsistent scroll arrow position calculations
  - 433972 Placing gtk.Expander inside a gtk.TextView() changes gtk....
  - 434261 _gtk_toolbar_elide_underscores incorrectly handles some s...
  - 383354 ctrl-L should make 'Location' entry disappear
  - 418673 gtk_recent_manager_add_item
  - 429732 gtk_accel_group_finalize accesses invalid memory
  - 435028 WM_CLIENT_LEADER is wrong on the leader_window
  - 431067 Background of the header window is not updated
  - 338843 add recent files support inside the ui manager
  - 148535 add drop shadow to menus, tooltips, etc. under Windows XP
* debian/control.in:
  - Conflicts on ubuntulooks (<= 0.9.11-1)
* debian/patches/15_default-fallback-icon-theme.patch:
  - patch from Debian, fallback on gnome icon theme

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/reference/gdk/tmpl/threads.sgml
 
1
<!-- ##### SECTION Title ##### -->
 
2
Threads
 
3
 
 
4
<!-- ##### SECTION Short_Description ##### -->
 
5
Functions for using GDK in multi-threaded programs
 
6
 
 
7
<!-- ##### SECTION Long_Description ##### -->
 
8
<para>
 
9
For thread safety, GDK relies on the thread primitives in GLib, 
 
10
and on the thread-safe GLib main loop.
 
11
</para>
 
12
<para>
 
13
GLib is completely thread safe (all global data is automatically 
 
14
locked), but individual data structure instances are not automatically 
 
15
locked for performance reasons. So e.g. you must coordinate 
 
16
accesses to the same #GHashTable from multiple threads.
 
17
</para>
 
18
<para>
 
19
GTK+ is "thread aware" but not thread safe &mdash; it provides a
 
20
global lock controlled by gdk_threads_enter()/gdk_threads_leave()
 
21
which protects all use of GTK+. That is, only one thread can use GTK+ 
 
22
at any given time.
 
23
</para>
 
24
<para>
 
25
Unfortunately the above holds with the X11 backend only. With the
 
26
Win32 backend, GDK calls should not be attempted from multiple threads
 
27
at all.
 
28
</para>
 
29
<para>
 
30
You must call g_thread_init() and gdk_threads_init() before executing
 
31
any other GTK+ or GDK functions in a threaded GTK+ program.
 
32
</para>
 
33
<para>
 
34
Idles, timeouts, and input functions are executed outside
 
35
of the main GTK+ lock. So, if you need to call GTK+
 
36
inside of such a callback, you must surround the callback
 
37
with a gdk_threads_enter()/gdk_threads_leave() pair.
 
38
(However, signals are still executed within the main
 
39
GTK+ lock.)
 
40
</para>
 
41
<para>
 
42
In particular, this means, if you are writing widgets that might 
 
43
be used in threaded programs, you <emphasis>must</emphasis> surround 
 
44
timeouts and idle functions in this matter.
 
45
</para>
 
46
<para>
 
47
As always, you must also surround any calls to GTK+ not made within 
 
48
a signal handler with a gdk_threads_enter()/gdk_threads_leave() pair.
 
49
</para>
 
50
 
 
51
<para>
 
52
Before calling gdk_threads_leave() from a thread other
 
53
than your main thread, you probably want to call gdk_flush()
 
54
to send all pending commands to the windowing system.
 
55
(The reason you don't need to do this from the main thread
 
56
is that GDK always automatically flushes pending commands
 
57
when it runs out of incoming events to process and has
 
58
to sleep while waiting for more events.)
 
59
</para>
 
60
 
 
61
<para>A minimal main program for a threaded GTK+ application
 
62
looks like:</para>
 
63
 
 
64
<informalexample>
 
65
<programlisting role="C">
 
66
int
 
67
main (int argc, char *argv[])
 
68
{
 
69
  GtkWidget *window;
 
70
 
 
71
  g_thread_init (NULL);
 
72
  gdk_threads_init (<!-- -->);
 
73
  gdk_threads_enter (<!-- -->);
 
74
 
 
75
  gtk_init (&amp;argc, &amp;argv);
 
76
 
 
77
  window = create_window (<!-- -->);
 
78
  gtk_widget_show (window);
 
79
 
 
80
  gtk_main (<!-- -->);
 
81
  gdk_threads_leave (<!-- -->);
 
82
 
 
83
  return 0;
 
84
}
 
85
</programlisting>
 
86
</informalexample>
 
87
 
 
88
<para>
 
89
Callbacks require a bit of attention. Callbacks from GTK+ signals
 
90
are made within the GTK+ lock. However callbacks from GLib (timeouts,
 
91
IO callbacks, and idle functions) are made outside of the GTK+
 
92
lock. So, within a signal handler you do not need to call
 
93
gdk_threads_enter(), but within the other types of callbacks, you
 
94
do.
 
95
</para>
 
96
 
 
97
<para>Erik Mouw contributed the following code example to
 
98
illustrate how to use threads within GTK+ programs.
 
99
</para>
 
100
 
 
101
<informalexample>
 
102
<programlisting role="C">
 
103
/*-------------------------------------------------------------------------
 
104
 * Filename:      gtk-thread.c
 
105
 * Version:       0.99.1
 
106
 * Copyright:     Copyright (C) 1999, Erik Mouw
 
107
 * Author:        Erik Mouw &lt;J.A.K.Mouw@its.tudelft.nl&gt;
 
108
 * Description:   GTK threads example. 
 
109
 * Created at:    Sun Oct 17 21:27:09 1999
 
110
 * Modified by:   Erik Mouw &lt;J.A.K.Mouw@its.tudelft.nl&gt;
 
111
 * Modified at:   Sun Oct 24 17:21:41 1999
 
112
 *-----------------------------------------------------------------------*/
 
113
/*
 
114
 * Compile with:
 
115
 *
 
116
 * cc -o gtk-thread gtk-thread.c `gtk-config --cflags --libs gthread`
 
117
 *
 
118
 * Thanks to Sebastian Wilhelmi and Owen Taylor for pointing out some
 
119
 * bugs.
 
120
 *
 
121
 */
 
122
 
 
123
&num;include &lt;stdio.h&gt;
 
124
&num;include &lt;stdlib.h&gt;
 
125
&num;include &lt;unistd.h&gt;
 
126
&num;include &lt;time.h&gt;
 
127
&num;include &lt;gtk/gtk.h&gt;
 
128
&num;include &lt;glib.h&gt;
 
129
&num;include &lt;pthread.h&gt;
 
130
 
 
131
&num;define YES_IT_IS    (1)
 
132
&num;define NO_IT_IS_NOT (0)
 
133
 
 
134
typedef struct 
 
135
{
 
136
  GtkWidget *label;
 
137
  int what;
 
138
} yes_or_no_args;
 
139
 
 
140
G_LOCK_DEFINE_STATIC (yes_or_no);
 
141
static volatile int yes_or_no = YES_IT_IS;
 
142
 
 
143
void destroy (GtkWidget *widget, gpointer data)
 
144
{
 
145
  gtk_main_quit (<!-- -->);
 
146
}
 
147
 
 
148
void *argument_thread (void *args)
 
149
{
 
150
  yes_or_no_args *data = (yes_or_no_args *)args;
 
151
  gboolean say_something;
 
152
 
 
153
  for (;;)
 
154
    {
 
155
      /* sleep a while */
 
156
      sleep(rand(<!-- -->) / (RAND_MAX / 3) + 1);
 
157
 
 
158
      /* lock the yes_or_no_variable */
 
159
      G_LOCK(yes_or_no);
 
160
 
 
161
      /* do we have to say something? */
 
162
      say_something = (yes_or_no != data->what);
 
163
 
 
164
      if(say_something)
 
165
        {
 
166
          /* set the variable */
 
167
          yes_or_no = data->what;
 
168
        }
 
169
 
 
170
      /* Unlock the yes_or_no variable */
 
171
      G_UNLOCK (yes_or_no);
 
172
 
 
173
      if (say_something)
 
174
        {
 
175
          /* get GTK thread lock */
 
176
          gdk_threads_enter (<!-- -->);
 
177
 
 
178
          /* set label text */
 
179
          if(data->what == YES_IT_IS)
 
180
            gtk_label_set_text (GTK_LABEL (data->label), "O yes, it is!");
 
181
          else
 
182
            gtk_label_set_text (GTK_LABEL (data->label), "O no, it isn't!");
 
183
 
 
184
          /* release GTK thread lock */
 
185
          gdk_threads_leave (<!-- -->);
 
186
        }
 
187
    }
 
188
 
 
189
  return NULL;
 
190
}
 
191
 
 
192
int main (int argc, char *argv[])
 
193
{
 
194
  GtkWidget *window;
 
195
  GtkWidget *label;
 
196
  yes_or_no_args yes_args, no_args;
 
197
  pthread_t no_tid, yes_tid;
 
198
 
 
199
  /* init threads */
 
200
  g_thread_init (NULL);
 
201
  gdk_threads_init (<!-- -->);
 
202
  gdk_threads_enter (<!-- -->);
 
203
 
 
204
  /* init gtk */
 
205
  gtk_init(&amp;argc, &amp;argv);
 
206
 
 
207
  /* init random number generator */
 
208
  srand ((unsigned int) time (NULL));
 
209
 
 
210
  /* create a window */
 
211
  window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
 
212
 
 
213
  gtk_signal_connect (GTK_OBJECT (window), "destroy",
 
214
                      GTK_SIGNAL_FUNC (destroy), NULL);
 
215
 
 
216
  gtk_container_set_border_width (GTK_CONTAINER (window), 10);
 
217
 
 
218
  /* create a label */
 
219
  label = gtk_label_new ("And now for something completely different ...");
 
220
  gtk_container_add (GTK_CONTAINER (window), label);
 
221
  
 
222
  /* show everything */
 
223
  gtk_widget_show (label);
 
224
  gtk_widget_show (window);
 
225
 
 
226
  /* create the threads */
 
227
  yes_args.label = label;
 
228
  yes_args.what = YES_IT_IS;
 
229
  pthread_create (&amp;yes_tid, NULL, argument_thread, &amp;yes_args);
 
230
 
 
231
  no_args.label = label;
 
232
  no_args.what = NO_IT_IS_NOT;
 
233
  pthread_create (&amp;no_tid, NULL, argument_thread, &amp;no_args);
 
234
 
 
235
  /* enter the GTK main loop */
 
236
  gtk_main (<!-- -->);
 
237
  gdk_threads_leave (<!-- -->);
 
238
 
 
239
  return 0;
 
240
}
 
241
</programlisting>
 
242
</informalexample>
 
243
 
 
244
<!-- ##### SECTION See_Also ##### -->
 
245
<para>
 
246
 
 
247
</para>
 
248
 
 
249
<!-- ##### SECTION Stability_Level ##### -->
 
250
 
 
251
 
 
252
<!-- ##### MACRO GDK_THREADS_ENTER ##### -->
 
253
<para>
 
254
This macro marks the beginning of a critical section in which GDK and GTK+
 
255
functions can be called.  Only one thread at a time can be in such a
 
256
critial section. The macro expands to a no-op if #G_THREADS_ENABLED
 
257
has not been defined. Typically gdk_threads_enter() should be used 
 
258
instead of this macro.
 
259
</para>
 
260
 
 
261
 
 
262
 
 
263
<!-- ##### MACRO GDK_THREADS_LEAVE ##### -->
 
264
<para>
 
265
This macro marks the end of a critical section 
 
266
begun with #GDK_THREADS_ENTER.
 
267
</para>
 
268
 
 
269
 
 
270
 
 
271
<!-- ##### FUNCTION gdk_threads_init ##### -->
 
272
<para>
 
273
 
 
274
</para>
 
275
 
 
276
 
 
277
 
 
278
<!-- ##### FUNCTION gdk_threads_enter ##### -->
 
279
<para>
 
280
This macro marks the beginning of a critical section
 
281
in which GDK and GTK+ functions can be called.
 
282
Only one thread at a time can be in such a critial 
 
283
section.
 
284
</para>
 
285
 
 
286
 
 
287
 
 
288
<!-- ##### FUNCTION gdk_threads_leave ##### -->
 
289
<para>
 
290
Leaves a critical region begun with gdk_threads_enter(). 
 
291
</para>
 
292
 
 
293
 
 
294
 
 
295
<!-- ##### VARIABLE gdk_threads_mutex ##### -->
 
296
<para>
 
297
The #GMutex used to implement the critical region for
 
298
gdk_threads_enter()/gdk_threads_leave(). 
 
299
</para>
 
300
 
 
301
 
 
302
<!-- ##### FUNCTION gdk_threads_set_lock_functions ##### -->
 
303
<para>
 
304
 
 
305
</para>
 
306
 
 
307
@enter_fn: 
 
308
@leave_fn: 
 
309
 
 
310