From d6b0af99d711584ca4e44f218a4cd2151a9ccef4 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sat, 24 Sep 2011 19:00:19 -0400 Subject: [PATCH] GThread doc additions --- docs/reference/glib/glib-sections.txt | 41 +++- glib/deprecated/gthread.h | 3 + glib/gthread-posix.c | 406 +++++++++++++++++++++++++++++++--- glib/gthread.c | 66 ++++-- 4 files changed, 458 insertions(+), 58 deletions(-) diff --git a/docs/reference/glib/glib-sections.txt b/docs/reference/glib/glib-sections.txt index 8f5fa13..17e2e72 100644 --- a/docs/reference/glib/glib-sections.txt +++ b/docs/reference/glib/glib-sections.txt @@ -606,11 +606,35 @@ g_thread_foreach GMutex +G_MUTEX_INIT +g_mutex_init +g_mutex_clear g_mutex_new +g_mutex_free g_mutex_lock g_mutex_trylock g_mutex_unlock -g_mutex_free + + +GRecMutex +G_REC_MUTEX_INIT +g_rec_mutex_init +g_rec_mutex_clear +g_rec_mutex_lock +g_rec_mutex_trylock +g_rec_mutex_unlock + + +GRWLock +G_RW_LOCK_INIT +g_rw_lock_init +g_rw_lock_clear +g_rw_lock_writer_lock +g_rw_lock_writer_trylock +g_rw_lock_writer_unlock +g_rw_lock_reader_lock +g_rw_lock_reader_trylock +g_rw_lock_reader_unlock GStaticMutex @@ -655,12 +679,16 @@ g_static_rw_lock_free GCond +G_COND_INIT g_cond_new -g_cond_signal -g_cond_broadcast +g_cond_free +g_cond_init +g_cond_clear g_cond_wait g_cond_timed_wait -g_cond_free +g_cond_timedwait +g_cond_signal +g_cond_broadcast GPrivate @@ -693,13 +721,8 @@ g_pointer_bit_trylock g_pointer_bit_unlock -G_THREAD_ECF -G_THREAD_CF -G_THREAD_UF g_static_mutex_get_mutex_impl g_static_mutex_get_mutex_impl_shortcut -G_MUTEX_DEBUG_MAGIC -g_thread_init_with_errorcheck_mutexes G_LOCK_NAME glib_dummy_decl GSystemThread diff --git a/glib/deprecated/gthread.h b/glib/deprecated/gthread.h index 9b09e1d..668064a 100644 --- a/glib/deprecated/gthread.h +++ b/glib/deprecated/gthread.h @@ -107,6 +107,9 @@ GThread* g_thread_create_full (GThreadFunc func, GThreadPriority priority, GError **error); +void g_thread_set_priority (GThread *thread, + GThreadPriority priority); + #ifdef G_OS_WIN32 typedef GMutex * GStaticMutex; #define G_STATIC_MUTEX_INIT NULL diff --git a/glib/gthread-posix.c b/glib/gthread-posix.c index ca2703c..ce04ce4 100644 --- a/glib/gthread-posix.c +++ b/glib/gthread-posix.c @@ -63,6 +63,19 @@ g_thread_abort (gint status, /* {{{1 GMutex */ /** + * G_MUTEX_INIT: + * + * Initializer for statically allocated #GMutexes. + * Alternatively, g_mutex_init() can be used. + * + * |[ + * GMutex mutex = G_MUTEX_INIT; + * ]| + * + * Since: 2.32 + */ + +/** * g_mutex_init: * @mutex: an uninitialized #GMutex * @@ -71,25 +84,27 @@ g_thread_abort (gint status, * 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(). Also see #G_MUTEX_INITIALIZER - * for an alternative way to initialize statically allocated mutexes. + * created with g_mutex_new(). Also see #G_MUTEX_INIT for an + * alternative way to initialize statically allocated mutexes. * * |[ * typedef struct { * GMutex m; - * /* ... */ + * ... * } Blob; * * Blob *b; * * b = g_new (Blob, 1); * g_mutex_init (&b->m); - * /* ... */ * ]| * * To undo the effect of g_mutex_init() when a mutex is no longer * needed, use g_mutex_clear(). * + * Calling g_mutex_init() on an already initialized #GMutex leads + * to undefined behaviour. + * * Since: 2.32 */ void @@ -121,6 +136,9 @@ g_mutex_init (GMutex *mutex) * #GMutexes that have have been created with g_mutex_new() should * be freed with g_mutex_free() instead. * + * Calling g_mutex_clear() on a locked mutex leads to undefined + * behaviour. + * * Sine: 2.32 */ void @@ -146,7 +164,7 @@ g_mutex_clear (GMutex *mutex) * #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 - * #GStaticRecMutex, if you need recursive mutexes. + * #GRecMutex if you need recursive mutexes. */ void g_mutex_lock (GMutex *mutex) @@ -162,7 +180,10 @@ g_mutex_lock (GMutex *mutex) * @mutex: a #GMutex * * Unlocks @mutex. If another thread is blocked in a g_mutex_lock() - * call for @mutex, it will be woken and can lock @mutex itself. + * call for @mutex, it will become unblocked and can lock @mutex itself. + * + * Calling g_mutex_unlock() on a mutex that is not locked by the + * current thread leads to undefined behaviour. * * This function can be used even if g_thread_init() has not yet been * called, and, in that case, will do nothing. @@ -190,10 +211,9 @@ g_mutex_unlock (GMutex *mutex) * #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 #GStaticRecMutex, if you need recursive - * mutexes. + * @mutex. Use #GRecMutex if you need recursive mutexes. - * Returns: %TRUE, if @mutex could be locked + * Returns: %TRUE if @mutex could be locked */ gboolean g_mutex_trylock (GMutex *mutex) @@ -211,6 +231,23 @@ g_mutex_trylock (GMutex *mutex) /* {{{1 GRecMutex */ +/** + * GRecMutex: + * + * The GRecMutex struct is an opaque data structure to represent a + * recursive mutex. It is similar to a #GMutex with the difference + * that it is possible to lock a GRecMutex multiple times in the same + * thread without deadlock. When doing so, care has to be taken to + * unlock the recursive mutex as often as it has been locked. + * + * A GRecMutex should only be accessed with the + * g_rec_mutex_ functions. Before a GRecMutex + * can be used, it has to be initialized with #G_REC_MUTEX_INIT or + * g_rec_mutex_init(). + * + * Since: 2.32 + */ + static pthread_mutex_t * g_rec_mutex_impl_new (void) { @@ -249,35 +286,135 @@ g_rec_mutex_get_impl (GRecMutex *mutex) return impl; } +/** + * G_REC_MUTEX_INIT: + * + * Initializer for statically allocated #GRecMutexes. + * Alternatively, g_rec_mutex_init() can be used. + * + * |[ + * GRecMutex mutex = G_REC_MUTEX_INIT; + * ]| + * + * Since: 2.32 + */ + +/** + * g_rec_mutex_init: + * @rec_mutex: an uninitialized #GRecMutex + * + * Initializes a #GRecMutex so that it can be used. + * + * 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(). Also see #G_REC_MUTEX_INIT + * for an alternative way to initialize statically allocated + * recursive mutexes. + * + * |[ + * typedef struct { + * GRecMutex m; + * ... + * } Blob; + * + * Blob *b; + * + * b = g_new (Blob, 1); + * g_rec_mutex_init (&b->m); + * ]| + * + * Calling g_rec_mutex_init() on an already initialized #GRecMutex + * leads to undefined behaviour. + * + * To undo the effect of g_rec_mutex_init() when a recursive mutex + * is no longer needed, use g_rec_mutex_clear(). + * + * Since: 2.32 + */ void -g_rec_mutex_init (GRecMutex *mutex) +g_rec_mutex_init (GRecMutex *rec_mutex) { - mutex->impl = g_rec_mutex_impl_new (); + rec_mutex->impl = g_rec_mutex_impl_new (); } +/** + * g_rec_mutex_clear: + * @rec_mutex: an initialized #GRecMutex + * + * 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. + * + * Calling g_rec_mutex_clear() on a locked recursive mutex leads + * to undefined behaviour. + * + * Sine: 2.32 + */ void -g_rec_mutex_clear (GRecMutex *mutex) +g_rec_mutex_clear (GRecMutex *rec_mutex) { - if (mutex->impl) - g_rec_mutex_impl_free (mutex->impl); + if (rec_mutex->impl) + g_rec_mutex_impl_free (rec_mutex->impl); } +/** + * g_rec_mutex_lock: + * @rec_mutex: a #GRecMutex + * + * Locks @rec_mutex. If @rec_mutex is already locked by another + * thread, the current thread will block until @rec_mutex is + * unlocked by the other thread. If @rec_mutex is already locked + * by the current thread, the 'lock count' of @rec_mutex is increased. + * The mutex will only become available again when it is unlocked + * as many times as it has been locked. + * + * Since: 2.32 + */ void g_rec_mutex_lock (GRecMutex *mutex) { pthread_mutex_lock (g_rec_mutex_get_impl (mutex)); } +/** + * g_rec_mutex_unlock: + * @rec_mutex: a #RecGMutex + * + * Unlocks @rec_mutex. If another thread is blocked in a + * g_rec_mutex_lock() call for @rec_mutex, it will become unblocked + * and can lock @rec_mutex itself. + * + * Calling g_rec_mutex_unlock() on a recursive mutex that is not + * locked by the current thread leads to undefined behaviour. + * + * Since: 2.32 + */ void -g_rec_mutex_unlock (GRecMutex *mutex) +g_rec_mutex_unlock (GRecMutex *rec_mutex) { - pthread_mutex_unlock (mutex->impl); + pthread_mutex_unlock (rec_mutex->impl); } +/** + * g_rec_mutex_trylock: + * @rec_mutex: a #GRecMutex + * + * Tries to lock @rec_mutex. If @rec_mutex is already locked + * by another thread, it immediately returns %FALSE. Otherwise + * it locks @rec_mutex and returns %TRUE. + * + * Returns: %TRUE if @rec_mutex could be locked + * + * Since: 2.32 + */ gboolean -g_rec_mutex_trylock (GRecMutex *mutex) +g_rec_mutex_trylock (GRecMutex *rec_mutex) { - if (pthread_mutex_trylock (g_rec_mutex_get_impl (mutex)) != 0) + if (pthread_mutex_trylock (g_rec_mutex_get_impl (rec_mutex)) != 0) return FALSE; return TRUE; @@ -285,24 +422,170 @@ g_rec_mutex_trylock (GRecMutex *mutex) /* {{{1 GRWLock */ +/** + * GRWLock: + * + * The GRWLock struct is an opaque data structure to represent a + * reader-writer lock. It is similar to a #GMutex in that it allows + * multiple threads to coordinate access to a shared resource. + * + * The difference to a mutex is that a reader-writer lock discriminates + * between read-only ('reader') and full ('writer') access. While only + * one thread at a time is allowed write access (by holding the 'writer' + * lock via g_rw_lock_writer_lock()), multiple threads can gain + * simultaneous read-only access (by holding the 'reader' lock via + * g_rw_lock_reader_lock()). + * + * + * An array with access functions + * + * GRWLock lock = G_RW_LOCK_INIT; + * GPtrArray *array; + * + * gpointer + * my_array_get (guint index) + * { + * gpointer retval = NULL; + * + * if (!array) + * return NULL; + * + * g_rw_lock_reader_lock (&lock); + * if (index < array->len) + * retval = g_ptr_array_index (array, index); + * g_rw_lock_reader_unlock (&lock); + * + * return retval; + * } + * + * void + * my_array_set (guint index, gpointer data) + * { + * g_rw_lock_writer_lock (&lock); + * + * if (!array) + * array = g_ptr_array_new (); + * + * if (index >= array->len) + * g_ptr_array_set_size (array, index+1); + * g_ptr_array_index (array, index) = data; + * + * g_rw_lock_writer_unlock (&lock); + * } + * + * + * This example shows an array which can be accessed by many readers + * (the my_array_get() function) simultaneously, + * whereas the writers (the my_array_set() + * function) will only be allowed once at a time and only if no readers + * currently access the array. This is because of the potentially + * dangerous resizing of the array. Using these functions is fully + * multi-thread safe now. + * + * + * + * A GRWLock should only be accessed with the + * g_rw_lock_ functions. Before it can be used, + * it has to be initialized with #G_RW_LOCK_INIT or g_rw_lock_init(). + * + * Since: 2.32 + */ + +/** + * G_RW_LOCK_INIT: + * + * Initializer for statically allocated #GRWLocks. + * Alternatively, g_rw_lock_init_init() can be used. + * + * |[ + * GRWLock lock = G_RW_LOCK_INIT; + * ]| + * + * Since: 2.32 + */ + +/** + * g_rw_lock_init: + * @lock: an uninitialized #GRWLock + * + * Initializes a #GRWLock so that it can be used. + * + * This function is useful to initialize a lock that has been + * allocated on the stack, or as part of a larger structure. + * Also see #G_RW_LOCK_INIT for an alternative way to initialize + * statically allocated locks. + * + * |[ + * typedef struct { + * GRWLock l; + * ... + * } Blob; + * + * Blob *b; + * + * b = g_new (Blob, 1); + * g_rw_lock_init (&b->l); + * ]| + * + * To undo the effect of g_rw_lock_init() when a lock is no longer + * needed, use g_rw_lock_clear(). + * + * Calling g_rw_lock_init() on an already initialized #GRWLock leads + * to undefined behaviour. + * + * Since: 2.32 + */ void g_rw_lock_init (GRWLock *lock) { pthread_rwlock_init (&lock->impl, NULL); } +/** + * g_rw_lock_clear: + * @lock: an initialized #GRWLock + * + * Frees the resources allocated to a lock with g_rw_lock_init(). + * + * Calling g_rw_lock_clear() when any thread holds the lock + * leads to undefined behaviour. + * + * Sine: 2.32 + */ void g_rw_lock_clear (GRWLock *lock) { pthread_rwlock_destroy (&lock->impl); } +/** + * g_rw_lock_writer_lock: + * @lock: a #GRWLock + * + * Obtain a write lock on @lock. If any thread already holds + * a read or write lock on @lock, the current thread will block + * until all other threads have dropped their locks on @lock. + * + * Since: 2.32 + */ void g_rw_lock_writer_lock (GRWLock *lock) { pthread_rwlock_wrlock (&lock->impl); } +/** + * g_rw_lock_writer_trylock: + * @lock: a #GRWLock + * + * Tries to obtain a write lock on @lock. If any other thread holds + * a read or write lock on @lock, it immediately returns %FALSE. + * Otherwise it locks @lock and returns %TRUE. + * + * Returns: %TRUE if @lock could be locked + * + * Since: 2.32 + */ gboolean g_rw_lock_writer_trylock (GRWLock *lock) { @@ -312,18 +595,54 @@ g_rw_lock_writer_trylock (GRWLock *lock) return TRUE; } +/** + * g_rw_lock_writer_unlock: + * @lock: a #GRWLock + * + * Release a write lock on @lock. + * + * Calling g_rw_lock_writer_unlock() on a lock that is not held + * by the current thread leads to undefined behaviour. + * + * Since: 2.32 + */ void g_rw_lock_writer_unlock (GRWLock *lock) { pthread_rwlock_unlock (&lock->impl); } +/** + * g_rw_lock_reader_lock: + * @lock: a #GRWLock + * + * Obtain a read lock on @lock. If another thread currently holds + * the write lock on @lock or blocks waiting for it, the current + * thread will block. Read locks can be taken recursively. + * + * It is implementation-defined how many threads are allowed to + * hold read locks on the same lock simultaneously. + * + * Since: 2.32 + */ void g_rw_lock_reader_lock (GRWLock *lock) { pthread_rwlock_rdlock (&lock->impl); } +/** + * g_rw_lock_reader_trylock: + * @lock: a #GRWLock + * + * Tries to obtain a read lock on @lock and returns %TRUE if + * the read lock was successfully obtained. Otherwise it + * returns %FALSE. + * + * Returns: %TRUE if @lock could be locked + * + * Since: 2.32 + */ gboolean g_rw_lock_reader_trylock (GRWLock *lock) { @@ -333,6 +652,17 @@ g_rw_lock_reader_trylock (GRWLock *lock) return TRUE; } +/** + * g_rw_lock_reader_unlock: + * @lock: a #GRWLock + * + * Release a read lock on @lock. + * + * Calling g_rw_lock_reader_unlock() on a lock that is not held + * by the current thread leads to undefined behaviour. + * + * Since: 2.32 + */ void g_rw_lock_reader_unlock (GRWLock *lock) { @@ -342,6 +672,19 @@ g_rw_lock_reader_unlock (GRWLock *lock) /* {{{1 GCond */ /** + * G_COND_INIT: + * + * Initializer for statically allocated #GConds. + * Alternatively, g_cond_init() can be used. + * + * |[ + * GCond cond = G_COND_INIT; + * ]| + * + * Since: 2.32 + */ + +/** * g_cond_init: * @cond: an uninitialized #GCond * @@ -350,9 +693,14 @@ g_rw_lock_reader_unlock (GRWLock *lock) * 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(). Also see #G_COND_INITIALIZER - * for an alternative way to initialize statically allocated - * #GConds. + * created with g_cond_new(). Also see #G_COND_INIT for an + * alternative way to initialize statically allocated #GConds. + * + * To undo the effect of g_cond_init() when a #GCond is no longer + * needed, use g_cond_clear(). + * + * Calling g_cond_init() on an already initialized #GCond leads + * to undefined behaviour. * * Since: 2.32 */ @@ -369,11 +717,14 @@ g_cond_init (GCond *cond) * g_cond_clear: * @cond: an initialized #GCond * - * Frees the resources allocated ot a #GCond with g_cond_init(). + * 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. * + * Calling g_cond_clear() for a #GCond on which threads are + * blocking leads to undefined behaviour. + * * Since: 2.32 */ void @@ -390,9 +741,8 @@ g_cond_clear (GCond *cond) * @cond: a #GCond * @mutex: a #GMutex that is currently locked * - * Waits until this thread is woken up on @cond. - * The @mutex is unlocked before falling asleep - * and locked again before resuming. + * Waits until this thread is woken up on @cond. The @mutex is unlocked + * before falling asleep and locked again before resuming. * * This function can be used even if g_thread_init() has not yet been * called, and, in that case, will immediately return. @@ -411,7 +761,8 @@ g_cond_wait (GCond *cond, * g_cond_signal: * @cond: a #GCond * - * If threads are waiting for @cond, exactly one of them is woken up. + * If threads are waiting for @cond, at least one of them is unblocked. + * If no threads are waiting for @cond, this function has no effect. * It is good practice to hold the same lock as the waiting thread * while calling this function, though not required. * @@ -431,7 +782,8 @@ g_cond_signal (GCond *cond) * g_cond_broadcast: * @cond: a #GCond * - * If threads are waiting for @cond, all of them are woken up. + * If threads are waiting for @cond, all of them are unblocked. + * If no threads are waiting for @cond, this function has no effect. * It is good practice to lock the same mutex as the waiting threads * while calling this function, though not required. * diff --git a/glib/gthread.c b/glib/gthread.c index a4fbc56..372f8d4 100644 --- a/glib/gthread.c +++ b/glib/gthread.c @@ -21,6 +21,7 @@ * Boston, MA 02111-1307, USA. */ +/* {{{1 Prelude */ /* Prelude {{{1 ----------------------------------------------------------- */ /* @@ -67,8 +68,8 @@ /** * SECTION:threads * @title: Threads - * @short_description: thread abstraction; including threads, different - * mutexes, conditions and thread private data + * @short_description: portable support for threads, mutexes, locks, + * conditions and thread private data * @see_also: #GThreadPool, #GAsyncQueue * * Threads act almost like processes, but unlike processes all threads @@ -81,7 +82,7 @@ * threads can be made, unless order is explicitly forced by the * programmer through synchronization primitives. * - * The aim of the thread related functions in GLib is to provide a + * The aim of the thread-related functions in GLib is to provide a * portable means for writing multi-threaded software. There are * primitives for mutexes to protect the access to portions of memory * (#GMutex, #GRecMutex and #GRWLock). There is a facility to use @@ -90,8 +91,7 @@ * There are primitives for thread-private data - data that every thread * has a private instance of (#GPrivate, #GStaticPrivate). There are * facilities for one-time initialization (#GOnce, g_once_init_enter()). - * Last but definitely not least there are primitives to portably create - * and manage threads (#GThread). + * Finally there are primitives to create and manage threads (#GThread). * * The threading system is initialized with g_thread_init(), which * takes an optional custom thread implementation or %NULL for the @@ -109,7 +109,7 @@ * * Please note that since version 2.24 the GObject initialization * function g_type_init() initializes threads (with a %NULL argument), - * so most applications, including those using Gtk+ will run with + * so most applications, including those using GTK+ will run with * threads enabled. If you want a special thread implementation, make * sure you call g_thread_init() before g_type_init() is called. * @@ -133,7 +133,7 @@ * G_THREADS_ENABLED: * * This macro is defined, for backward compatibility, to indicate that - * GLib has been compiled with thread support. As of glib 2.28, it is + * GLib has been compiled with thread support. As of GLib 2.28, it is * always defined. **/ @@ -439,7 +439,7 @@ gboolean g_threads_got_initialized = FALSE; * int * give_me_next_number (void) * { - * static GMutex mutex = G_MUTEX_INITIALIZER; + * static GMutex mutex = G_MUTEX_INIT; * static int current_number = 0; * int ret_val; * @@ -452,7 +452,8 @@ gboolean g_threads_got_initialized = FALSE; * * * - * A #GMutex should only be accessed via the following functions. + * A #GMutex should only be accessed via g_mutex_ + * functions. **/ /* GCond Virtual Functions {{{2 ------------------------------------------ */ @@ -880,6 +881,7 @@ g_once_init_leave (volatile gsize *value_location, * GStaticMutex: * * A #GStaticMutex works like a #GMutex. + * * Prior to GLib 2.32, GStaticMutex had the significant advantage * that it doesn't need to be created at run-time, but can be defined * at compile-time. Since 2.32, #GMutex can be statically allocated @@ -1898,7 +1900,7 @@ g_thread_join (GThread* thread) * This function does nothing. * * Deprecated:2.32: Thread priorities no longer have any effect. - **/ + */ void g_thread_set_priority (GThread *thread, GThreadPriority priority) @@ -2024,6 +2026,8 @@ g_thread_self (void) * keep the lock for a considerable time justify a #GStaticRWLock. The * above example most probably would fare better with a * #GStaticMutex. + * + * Deprecated: 2.32: Use a #GRWLock instead **/ /** @@ -2046,7 +2050,9 @@ g_thread_self (void) * A #GStaticRWLock must be initialized with this function before it * can be used. Alternatively you can initialize it with * #G_STATIC_RW_LOCK_INIT. - **/ + * + * Deprecated: 2.32: Use g_rw_lock_init() instead + */ void g_static_rw_lock_init (GStaticRWLock* lock) { @@ -2089,7 +2095,9 @@ g_static_rw_lock_signal (GStaticRWLock* lock) * #GStaticRWLock is not recursive. It might seem to be possible to * recursively lock for reading, but that can result in a deadlock, due * to writer preference. - **/ + * + * Deprecated: 2.32: Use g_rw_lock_reader_lock() instead + */ void g_static_rw_lock_reader_lock (GStaticRWLock* lock) { @@ -2117,7 +2125,9 @@ g_static_rw_lock_reader_lock (GStaticRWLock* lock) * lock @lock for writing, immediately returns %FALSE. Otherwise locks * @lock for reading and returns %TRUE. This lock has to be unlocked by * g_static_rw_lock_reader_unlock(). - **/ + * + * Deprectated: 2.32: Use g_rw_lock_reader_trylock() instead + */ gboolean g_static_rw_lock_reader_trylock (GStaticRWLock* lock) { @@ -2145,7 +2155,9 @@ g_static_rw_lock_reader_trylock (GStaticRWLock* lock) * Unlocks @lock. If a thread waits to lock @lock for writing and all * locks for reading have been unlocked, the waiting thread is woken up * and can lock @lock for writing. - **/ + * + * Deprectated: 2.32: Use g_rw_lock_reader_unlock() instead + */ void g_static_rw_lock_reader_unlock (GStaticRWLock* lock) { @@ -2172,7 +2184,9 @@ g_static_rw_lock_reader_unlock (GStaticRWLock* lock) * reading. When @lock is locked for writing, no other thread can lock * @lock (neither for reading nor writing). This lock has to be * unlocked by g_static_rw_lock_writer_unlock(). - **/ + * + * Deprectated: 2.32: Use g_rw_lock_writer_lock() instead + */ void g_static_rw_lock_writer_lock (GStaticRWLock* lock) { @@ -2199,7 +2213,9 @@ g_static_rw_lock_writer_lock (GStaticRWLock* lock) * either reading or writing) by another thread, it immediately returns * %FALSE. Otherwise it locks @lock for writing and returns %TRUE. This * lock has to be unlocked by g_static_rw_lock_writer_unlock(). - **/ + * + * Deprectated: 2.32: Use g_rw_lock_writer_trylock() instead + */ gboolean g_static_rw_lock_writer_trylock (GStaticRWLock* lock) { @@ -2230,7 +2246,9 @@ g_static_rw_lock_writer_trylock (GStaticRWLock* lock) * lock @lock for writing, and some thread or threads are waiting to * lock @lock for reading, the waiting threads are woken up and can * lock @lock for reading. - **/ + * + * Deprectated: 2.32: Use g_rw_lock_writer_unlock() instead + */ void g_static_rw_lock_writer_unlock (GStaticRWLock* lock) { @@ -2255,7 +2273,9 @@ g_static_rw_lock_writer_unlock (GStaticRWLock* lock) * unbounded lifetime, i.e. objects declared 'static', but if you have * a #GStaticRWLock as a member of a structure, and the structure is * freed, you should also free the #GStaticRWLock. - **/ + * + * Deprecated: 2.32: Use a #GRWLock instead + */ void g_static_rw_lock_free (GStaticRWLock* lock) { @@ -2340,7 +2360,7 @@ g_thread_get_initialized () /** * g_mutex_new: * - * Creates a new #GMutex. + * Allocated and initializes a new #GMutex. * * Returns: a newly allocated #GMutex. Use g_mutex_free() to free */ @@ -2361,8 +2381,8 @@ g_mutex_new (void) * * Destroys a @mutex that has been created with g_mutex_new(). * - * Calling g_mutex_free() on a locked mutex may result - * in undefined behaviour. + * Calling g_mutex_free() on a locked mutex may result + * in undefined behaviour. */ void g_mutex_free (GMutex *mutex) @@ -2374,7 +2394,7 @@ g_mutex_free (GMutex *mutex) /** * g_cond_new: * - * Creates a new #GCond. + * Allocates and initializes a new #GCond. * * Returns: a newly allocated #GCond. Free with g_cond_free() */ @@ -2463,3 +2483,5 @@ GThreadFunctions g_thread_functions_for_glib_use = NULL, NULL, }; + +/* vim: set foldmethod=marker: */ -- 2.7.4