luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-11-10 11:26:16 +01:00
Code Issues Packages Projects Releases Wiki Activity

Cleanup thread documentation

Browse Source
This commit is contained in:
Ryan Lortie 2011-10-06 12:01:53 -04:00
parent 49b93a0bba
commit 94b7d2ee6c
7 changed files with 115 additions and 152 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
docs/reference/glib/Makefile.am
View File

@ -24,10 +24,13 @@ CFILE_GLOB=$(top_srcdir)/glib/*.c $(top_srcdir)/gmodule/*.c
# Ignore some private headers
IGNORE_HFILES = \
gallocator.h \
gdatasetprivate.h \
glibintl.h \
gbsearcharray.h \
glib-private.h \
gmoduleconf.h \
gthreadprivate.h \
gunibreak.h \
gunicomp.h \
gunidecomp.h \

9
docs/reference/glib/glib-docs.sgml
View File

@ -83,7 +83,6 @@ synchronize their operation.
<xi:include href="xml/hooks.xml" />
<xi:include href="xml/misc_utils.xml" />
<xi:include href="xml/scanner.xml" />
<xi:include href="xml/completion.xml" />
<xi:include href="xml/timers.xml" />
<xi:include href="xml/spawn.xml" />
<xi:include href="xml/fileutils.xml" />
@ -120,7 +119,6 @@ synchronize their operation.
<xi:include href="xml/quarks.xml" />
<xi:include href="xml/datalist.xml" />
<xi:include href="xml/datasets.xml" />
<xi:include href="xml/relations.xml" />
<xi:include href="xml/caches.xml" />
<xi:include href="xml/gvarianttype.xml"/>
<xi:include href="xml/gvariant.xml"/>
@ -128,6 +126,13 @@ synchronize their operation.
<xi:include href="gvariant-text.xml"/>
</chapter>
<chapter id="deprecated">
<title>Deprecated APIs</title>
<xi:include href="xml/threads-deprecated.xml"/>
<xi:include href="xml/relations.xml" />
<xi:include href="xml/completion.xml" />
</chapter>
<chapter id="tools">
<title>GLib Tools</title>
<xi:include href="glib-gettextize.xml" />

2
docs/reference/glib/glib-overrides.txt
View File

@ -9,7 +9,7 @@
</MACRO>
<MACRO>
<NAME>G_THREADS_IMPL_NONE</NAME>
<NAME>G_THREADS_IMPL_WIN32</NAME>
#define G_THREADS_IMPL_NONE
</MACRO>

94
docs/reference/glib/glib-sections.txt
View File

@ -572,25 +572,17 @@ g_child_watch_funcs
GSourcePrivate
</SECTION>
<SECTION>
<TITLE>Threads</TITLE>
<FILE>threads</FILE>
<SUBSECTION>
G_THREADS_IMPL_POSIX
G_THREADS_IMPL_WIN32
<SUBSECTION>
G_THREAD_ERROR
GThreadError
<SUBSECTION>
g_thread_init
g_thread_supported
g_thread_get_initialized
<SUBSECTION>
GThreadFunc
GThread
GThreadFunc
g_thread_new
g_thread_new_full
g_thread_self
@ -598,23 +590,6 @@ g_thread_join
g_thread_yield
g_thread_exit
<SUBSECTION Deprecated>
g_thread_create
g_thread_create_full
GThreadPriority
g_thread_set_priority
g_thread_foreach
<SUBSECTION>
GMutex
g_mutex_init
g_mutex_clear
g_mutex_new
g_mutex_free
g_mutex_lock
g_mutex_trylock
g_mutex_unlock
<SUBSECTION>
G_LOCK_DEFINE
G_LOCK_DEFINE_STATIC
@ -623,6 +598,14 @@ G_LOCK
G_TRYLOCK
G_UNLOCK
<SUBSECTION>
GMutex
g_mutex_init
g_mutex_clear
g_mutex_lock
g_mutex_trylock
g_mutex_unlock
<SUBSECTION>
GRecMutex
g_rec_mutex_init
@ -644,8 +627,6 @@ g_rw_lock_reader_unlock
<SUBSECTION>
GCond
g_cond_new
g_cond_free
g_cond_init
g_cond_clear
g_cond_wait
@ -661,9 +642,6 @@ g_private_get
g_private_set
g_private_replace
<SUBSECTION Deprecated>
g_private_new
<SUBSECTION>
GOnce
GOnceStatus
@ -680,7 +658,41 @@ g_pointer_bit_lock
g_pointer_bit_trylock
g_pointer_bit_unlock
<SUBSECTION Deprecated>
<SUBSECTION Private>
G_LOCK_NAME
atexit
g_thread_error_quark
g_once_impl
</SECTION>
<SECTION>
<TITLE>Deprecated Thread APIs</TITLE>
<FILE>threads-deprecated</FILE>
<SUBSECTION>
G_THREADS_IMPL_POSIX
G_THREADS_IMPL_WIN32
<SUBSECTION>
g_thread_init
g_thread_supported
g_thread_get_initialized
<SUBSECTION>
g_thread_create
g_thread_create_full
GThreadPriority
g_thread_set_priority
g_thread_foreach
<SUBSECTION>
g_mutex_new
g_mutex_free
g_cond_new
g_cond_free
g_private_new
<SUBSECTION>
GStaticMutex
G_STATIC_MUTEX_INIT
g_static_mutex_init
@ -690,7 +702,7 @@ g_static_mutex_unlock
g_static_mutex_get_mutex
g_static_mutex_free
<SUBSECTION Deprecated>
<SUBSECTION>
GStaticRecMutex
G_STATIC_REC_MUTEX_INIT
g_static_rec_mutex_init
@ -701,7 +713,7 @@ g_static_rec_mutex_lock_full
g_static_rec_mutex_unlock_full
g_static_rec_mutex_free
<SUBSECTION Deprecated>
<SUBSECTION>
GStaticRWLock
G_STATIC_RW_LOCK_INIT
g_static_rw_lock_init
@ -713,7 +725,7 @@ g_static_rw_lock_writer_trylock
g_static_rw_lock_writer_unlock
g_static_rw_lock_free
<SUBSECTION Deprecated>
<SUBSECTION>
GStaticPrivate
G_STATIC_PRIVATE_INIT
g_static_private_init
@ -725,22 +737,12 @@ g_static_private_free
GThreadFunctions
G_THREADS_ENABLED
g_static_mutex_get_mutex_impl
g_static_mutex_get_mutex_impl_shortcut
G_LOCK_NAME
glib_dummy_decl
GSystemThread
g_thread_use_default_impl
g_threads_got_initialized
g_thread_functions_for_glib_use
g_thread_gettime
g_thread_init_glib
g_thread_error_quark
g_once_impl
g_once_init_enter_impl
atexit
g_system_thread_assign
g_system_thread_equal
g_system_thread_equal_simple
</SECTION>
<SECTION>

18
glib/deprecated/gthread-deprecated.c
View File

@ -74,6 +74,24 @@
* to initialize the thread system.
*/
/**
* G_THREADS_IMPL_POSIX:
*
* This macro is defined if POSIX style threads are used.
*
* Deprecated:2.32:POSIX threads are in use on all non-Windows systems.
* Use G_OS_WIN32 to detect Windows.
*/
/**
* G_THREADS_IMPL_WIN32:
*
* This macro is defined if Windows style threads are used.
*
* Deprecated:2.32:Use G_OS_WIN32 to detect Windows.
*/
/* {{{1 Exported Variables */
gboolean g_thread_use_default_impl = TRUE;

40
glib/gthread-posix.c
View File

@ -139,7 +139,7 @@ g_mutex_get_impl (GMutex *mutex)
* This function is useful to initialize a mutex that has been
* allocated on the stack, or as part of a larger structure.
* It is not necessary to initialize a mutex that has been
* created with g_mutex_new() or that has been statically allocated.
* created that has been statically allocated.
*
* |[
* typedef struct {
@ -173,8 +173,8 @@ g_mutex_init (GMutex *mutex)
*
* Frees the resources allocated to a mutex with g_mutex_init().
*
* #GMutexes that have have been created with g_mutex_new() should
* be freed with g_mutex_free() instead.
* This function should not be used with a #GMutex that has been
* statically allocated.
*
* Calling g_mutex_clear() on a locked mutex leads to undefined
* behaviour.
@ -199,9 +199,9 @@ g_mutex_clear (GMutex *mutex)
* called, and, in that case, will do nothing.
*
* <note>#GMutex is neither guaranteed to be recursive nor to be
* non-recursive, i.e. a thread could deadlock while calling
* g_mutex_lock(), if it already has locked @mutex. Use
* #GRecMutex if you need recursive mutexes.</note>
* non-recursive. As such, calling g_mutex_lock() on a #GMutex that has
* already been locked by the same thread results in undefined behaviour
* (including but not limited to deadlocks).</note>
*/
void
g_mutex_lock (GMutex *mutex)
@ -246,9 +246,10 @@ g_mutex_unlock (GMutex *mutex)
* called, and, in that case, will immediately return %TRUE.
*
* <note>#GMutex is neither guaranteed to be recursive nor to be
* non-recursive, i.e. the return value of g_mutex_trylock() could be
* both %FALSE or %TRUE, if the current thread already has locked
* @mutex. Use #GRecMutex if you need recursive mutexes.</note>
* non-recursive. As such, calling g_mutex_lock() on a #GMutex that has
* already been locked by the same thread results in undefined behaviour
* (including but not limited to deadlocks or arbitrary return values).
* </note>
* Returns: %TRUE if @mutex could be locked
*/
@ -315,9 +316,9 @@ g_rec_mutex_get_impl (GRecMutex *rec_mutex)
* This function is useful to initialize a recursive mutex
* that has been allocated on the stack, or as part of a larger
* structure.
* It is not necessary to initialize a recursive mutex that has
* been created with g_rec_mutex_new(). It is not necessary to
* initialise a recursive mutex that has been statically allocated.
*
* It is not necessary to initialise a recursive mutex that has been
* statically allocated.
*
* |[
* typedef struct {
@ -352,8 +353,8 @@ g_rec_mutex_init (GRecMutex *rec_mutex)
* Frees the resources allocated to a recursive mutex with
* g_rec_mutex_init().
*
* #GRecMutexes that have have been created with g_rec_mutex_new()
* should be freed with g_rec_mutex_free() instead.
* This function should not be used with a #GRecMutex that has been
* statically allocated.
*
* Calling g_rec_mutex_clear() on a locked recursive mutex leads
* to undefined behaviour.
@ -509,6 +510,9 @@ g_rw_lock_init (GRWLock *rw_lock)
*
* Frees the resources allocated to a lock with g_rw_lock_init().
*
* This function should not be used with a #GRWLock that has been
* statically allocated.
*
* Calling g_rw_lock_clear() when any thread holds the lock
* leads to undefined behaviour.
*
@ -681,7 +685,7 @@ g_cond_get_impl (GCond *cond)
* This function is useful to initialize a #GCond that has been
* allocated on the stack, or as part of a larger structure.
* It is not necessary to initialize a #GCond that has been
* created with g_cond_new() or that has been statically allocated.
* statically allocated.
*
* To undo the effect of g_cond_init() when a #GCond is no longer
* needed, use g_cond_clear().
@ -703,8 +707,8 @@ g_cond_init (GCond *cond)
*
* Frees the resources allocated to a #GCond with g_cond_init().
*
* #GConds that have been created with g_cond_new() should
* be freed with g_cond_free() instead.
* This function should not be used with a #GCond that has been
* statically allocated.
*
* Calling g_cond_clear() for a #GCond on which threads are
* blocking leads to undefined behaviour.
@ -1116,8 +1120,6 @@ g_system_thread_create (GThreadFunc thread_func,
* that other threads can run.
*
* This function is often used as a method to make busy wait less evil.
* But in most cases you will encounter, there are better methods to do
* that. So in general you shouldn't use this function.
*/
void
g_thread_yield (void)

101
glib/gthread.c
View File

@ -106,18 +106,6 @@
* are also thread-safe.
*/
/**
* G_THREADS_IMPL_POSIX:
*
* This macro is defined if POSIX style threads are used.
*/
/**
* G_THREADS_IMPL_WIN32:
*
* This macro is defined if Windows style threads are used.
*/
/* G_LOCK Documentation {{{1 ---------------------------------------------- */
/**
@ -224,75 +212,10 @@
*
* It is easy to see that this won't work in a multi-threaded
* application. There current_number must be protected against shared
* access. A first naive implementation would be:
* access. A #GMutex can be used as a solution to this problem:
*
* <example>
* <title>The wrong way to write a thread-safe function</title>
* <programlisting>
* int
* give_me_next_number (void)
* {
* static int current_number = 0;
* int ret_val;
* static GMutex * mutex = NULL;
*
* if (!mutex) mutex = g_mutex_new (<!-- -->);
*
* g_mutex_lock (mutex);
* ret_val = current_number = calc_next_number (current_number);
* g_mutex_unlock (mutex);
*
* return ret_val;
* }
* </programlisting>
* </example>
*
* This looks like it would work, but there is a race condition while
* constructing the mutex and this code cannot work reliable. Please do
* not use such constructs in your own programs! One working solution
* is:
*
* <example>
* <title>A correct thread-safe function</title>
* <programlisting>
* static GMutex *give_me_next_number_mutex = NULL;
*
* /<!-- -->* this function must be called before any call to
* * give_me_next_number(<!-- -->)
* *
* * it must be called exactly once.
* *<!-- -->/
* void
* init_give_me_next_number (void)
* {
* g_assert (give_me_next_number_mutex == NULL);
* give_me_next_number_mutex = g_mutex_new (<!-- -->);
* }
*
* int
* give_me_next_number (void)
* {
* static int current_number = 0;
* int ret_val;
*
* g_mutex_lock (give_me_next_number_mutex);
* ret_val = current_number = calc_next_number (current_number);
* g_mutex_unlock (give_me_next_number_mutex);
*
* return ret_val;
* }
* </programlisting>
* </example>
*
* If a #GMutex is allocated in static storage then it can be used
* without initialisation. Otherwise, you should call g_mutex_init() on
* it and g_mutex_clear() when done.
*
* A statically initialized #GMutex provides an even simpler and safer
* way of doing this:
*
* <example>
* <title>Using a statically allocated mutex</title>
* <title>Using GMutex to protected a shared variable</title>
* <programlisting>
* int
* give_me_next_number (void)
@ -310,6 +233,13 @@
* </programlisting>
* </example>
*
* Notice that the #GMutex is not initialised to any particular value.
* Its placement in static storage ensures that it will be initialised
* to all-zeros, which is appropriate.
*
* If a #GMutex is placed in other contexts (eg: embedded in a struct)
* then it must be explicitly initialised using g_mutex_init().
*
* A #GMutex should only be accessed via <function>g_mutex_</function>
* functions.
*/
@ -485,6 +415,9 @@
* is returned by g_thread_new() or g_thread_new_full(). You can
* obtain the #GThread struct representing the current thead by
* calling g_thread_self().
*
* The structure is opaque -- none of its fields may be directly
* accessed.
*/
/**
@ -789,15 +722,15 @@ g_thread_create_proxy (gpointer data)
* @joinable: should this thread be joinable?
* @error: return location for error
*
* This function creates a new thread. The new thread starts by
* invoking @func with the argument data. The thread will run
* until @func returns or until g_thread_exit() is called.
* This function creates a new thread. The new thread starts by invoking
* @func with the argument data. The thread will run until @func returns
* or until g_thread_exit() is called from the new thread.
*
* The @name can be useful for discriminating threads in
* a debugger. Some systems restrict the length of @name to
* 16 bytes.
*
* If @joinable is %TRUE, you can wait for this threads termination
* If @joinable is %TRUE, you can wait for this thread's termination
* calling g_thread_join(). Resources for a joinable thread are not
* fully released until g_thread_join() is called for that thread.
* Otherwise the thread will just disappear when it terminates.
@ -843,7 +776,7 @@ g_thread_new (const gchar *name,
* In most cases, using g_thread_new() (which doesn't take a
* @stack_size) is better.
*
* If @joinable is %TRUE, you can wait for this threads termination
* If @joinable is %TRUE, you can wait for this thread's termination
* calling g_thread_join(). Resources for a joinable thread are not
* fully released until g_thread_join() is called for that thread.
* Otherwise the thread will just disappear when it terminates.