Make 3.0 parallel-installable to 2.x

[~andy/gtk] / docs / reference / gdk / tmpl / threads.sgml

diff --git a/docs/reference/gdk/tmpl/threads.sgml b/docs/reference/gdk/tmpl/threads.sgml
index 0bb57f513363af47282d609228ad0a632ea690ce..75a61ee8407f46b00053e07223ae8a0a2bf7bcaa 100644 (file)
--- a/docs/reference/gdk/tmpl/threads.sgml
+++ b/docs/reference/gdk/tmpl/threads.sgml
@@ -22,16 +22,23 @@ which protects all use of GTK+. That is, only one thread can use GTK+
 at any given time.
 </para>
 <para>
+Unfortunately the above holds with the X11 backend only. With the
+Win32 backend, GDK calls should not be attempted from multiple threads
+at all.
+</para>
+<para>
 You must call g_thread_init() and gdk_threads_init() before executing
 any other GTK+ or GDK functions in a threaded GTK+ program.
 </para>
 <para>
-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 gdk_threads_enter()/gdk_threads_leave() pair.
-(However, signals are still executed within the main
-GTK+ lock.)
+Idles, timeouts, and input functions from GLib, such as g_idle_add(), 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 gdk_threads_enter()/gdk_threads_leave() pair or use
+gdk_threads_add_idle_full() which does this for you.
+However, event dispatching from the mainloop is still executed within
+the main GTK+ lock, so callback functions connected to event signals
+like GtkWidget::button-press-event, do not need thread protection.
 </para>
 <para>
 In particular, this means, if you are writing widgets that might 
@@ -205,8 +212,7 @@ int main (int argc, char *argv[])
   /* create a window */
   window = gtk_window_new (GTK_WINDOW_TOPLEVEL);
 
-  gtk_signal_connect (GTK_OBJECT (window), "destroy",
-                     GTK_SIGNAL_FUNC (destroy), NULL);
+  g_signal_connect (window, "destroy", G_CALLBACK (destroy), NULL);
 
   gtk_container_set_border_width (GTK_CONTAINER (window), 10);
 
@@ -244,13 +250,17 @@ int main (int argc, char *argv[])
 <!-- ##### SECTION Stability_Level ##### -->
 
 
+<!-- ##### SECTION Image ##### -->
+
+
 <!-- ##### MACRO GDK_THREADS_ENTER ##### -->
 <para>
-This macro marks the beginning of a critical section in which GDK and GTK+
-functions can be called.  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.
+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.
 </para>
 
 
@@ -268,16 +278,18 @@ begun with #GDK_THREADS_ENTER.
 
 </para>
 
+@void: 
 
 
 <!-- ##### FUNCTION gdk_threads_enter ##### -->
 <para>
-This macro marks the beginning of a critical section
-in which GDK and GTK+ functions can be called.
-Only one thread at a time can be in such a critial 
+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.
 </para>
 
+@void: 
 
 
 <!-- ##### FUNCTION gdk_threads_leave ##### -->
@@ -285,13 +297,13 @@ section.
 Leaves a critical region begun with gdk_threads_enter(). 
 </para>
 
+@void: 
 
 
 <!-- ##### VARIABLE gdk_threads_mutex ##### -->
 <para>
 The #GMutex used to implement the critical region for
-gdk_threads_enter()/gdk_threads_leave(). This variable should not be
-used directly &mdash; consider it private.
+gdk_threads_enter()/gdk_threads_leave(). 
 </para>
 
 
@@ -304,3 +316,73 @@ used directly &mdash; consider it private.
 @leave_fn: 
 
 
+<!-- ##### FUNCTION gdk_threads_add_idle ##### -->
+<para>
+
+</para>
+
+@function: 
+@data: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gdk_threads_add_idle_full ##### -->
+<para>
+
+</para>
+
+@priority: 
+@function: 
+@data: 
+@notify: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gdk_threads_add_timeout ##### -->
+<para>
+
+</para>
+
+@interval: 
+@function: 
+@data: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gdk_threads_add_timeout_full ##### -->
+<para>
+
+</para>
+
+@priority: 
+@interval: 
+@function: 
+@data: 
+@notify: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gdk_threads_add_timeout_seconds ##### -->
+<para>
+
+</para>
+
+@interval: 
+@function: 
+@data: 
+@Returns: 
+
+
+<!-- ##### FUNCTION gdk_threads_add_timeout_seconds_full ##### -->
+<para>
+
+</para>
+
+@priority: 
+@interval: 
+@function: 
+@data: 
+@notify: 
+@Returns: 
+
+