From: Matthias Clasen Date: Sat, 15 Oct 2011 17:04:20 +0000 (-0400) Subject: Expand thread docs a bit X-Git-Tag: 2.31.0~88 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=6651bd221e4d9316884b4fad3c3e9943695ab639;p=platform%2Fupstream%2Fglib.git Expand thread docs a bit Add some discussion of pitfalls of threaded programming. --- diff --git a/glib/gthread.c b/glib/gthread.c index 646841e..2bbbce5 100644 --- a/glib/gthread.c +++ b/glib/gthread.c @@ -91,11 +91,44 @@ * This is no longer necessary. Since version 2.32, the GLib threading * system is automatically initialized at the start of your program, * and all thread-creation functions and synchronization primitives - * are available right away. It is still possible to do thread-unsafe - * initialization and setup at the beginning of your program, before - * creating the first threads. - * - * GLib is internally completely thread-safe (all global data is + * are available right away. + * + * Note that it is not safe to assume that your program has no threads + * even if you don't call g_thread_new() yourself. GLib and GIO can + * and will create threads for their own purposes in some cases, such + * as when using g_unix_signal_source_new() or when using #GDBus. + * + * Originally, UNIX did not have threads, and therefore some traditional + * UNIX APIs are problematic in threaded programs. Some notable examples + * are + * + * + * C library functions that return data in statically allocated + * buffers, such as strtok() or strerror(). For many of these, + * there are thread-safe variants with a _r suffix, or you can + * look at corresponding GLib APIs (like g_strsplit() or g_strerror()). + * + * + * setenv() and unsetenv() manipulate the process environment in + * a not thread-safe way, and may interfere with getenv() calls + * in other threads. Note that getenv() calls may be + * hidden behind other APIs. For example, GNU gettext() + * calls getenv() under the covers. In general, it is best to treat + * the environment as readonly. If you absolutely have to modify the + * environment, do it early in main(), when no other threads are around yet. + * + * + * setlocale() changes the locale for the entire process, affecting + * all threads. Temporary changes to the locale are often made to + * change the behavior of string scanning or formatting functions + * like scanf() or printf(). GLib offers a number of string APIs + * (like g_ascii_formatd() or g_ascii_strtod()) that can often be + * used as an alternative. Or you can use the uselocale() function + * to change the locale only for the current thread. + * + * + * + * GLib itself is internally completely thread-safe (all global data is * automatically locked), but individual data structure instances are * not automatically locked for performance reasons. For example, * you must coordinate accesses to the same #GHashTable from multiple