Warn about the consequences of not calling g_thread_init() first, if it

2008-08-15  Tor Lillqvist  <tml@novell.com>

	* glib/tmpl/threads.sgml: Warn about the consequences of not
	calling g_thread_init() first, if it will be called at all. Advice
	calling it if using random GLib-based libraries.

svn path=/trunk/; revision=7355

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index e4bf8cb..e55af00 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,9 @@
+2008-08-15  Tor Lillqvist  <tml@novell.com>
+
+       * glib/tmpl/threads.sgml: Warn about the consequences of not
+       calling g_thread_init() first, if it will be called at all. Advice
+       calling it if using random GLib-based libraries.
+
 2008-08-11  Matthias Clasen  <mclasen@redhat.com>
 
        Bug 547262 – Missing link in the docs

diff --git a/docs/reference/glib/tmpl/threads.sgml b/docs/reference/glib/tmpl/threads.sgml
index a675699..99523eb 100644 (file)
--- a/docs/reference/glib/tmpl/threads.sgml
+++ b/docs/reference/glib/tmpl/threads.sgml
@@ -34,7 +34,24 @@ primitives to portably create and manage threads (#GThread).
 
 <para>
 You must call g_thread_init() before executing any other GLib
-functions in a threaded GLib program. After that, GLib is completely
+functions in a GLib program if g_thread_init() will be called at
+all. This is a requirement even if no threads are in fact ever created
+by the process. It is enough that g_thread_init() is called. If other
+GLib functions have been called before that, the behaviour of the
+program is undefined.
+
+Failing this requirement leads easily to hangs or crashes, apparently
+more easily on Windows than on Linux, for example.
+
+Please note that if you call functions in some GLib-using library, in
+particular those above the GTK+ stack, that library might well call
+g_thread_init() itself, or call some other library that calls
+g_thread_init(). Thus, if you use some GLib-based library that is
+above the GTK+ stack, it is safest to call g_thread_init() in your
+application's main() before calling any GLib functions or functions in
+GLib-using libraries.
+
+After calling g_thread_init(), GLib is completely
 thread safe (all global data is automatically locked), but individual
 data structure instances are not automatically locked for performance
 reasons. So, for example you must coordinate accesses to the same