From dffca808469f372352a2f6cfe58f8ad026ce3a5e Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sun, 18 Sep 2011 21:17:33 -0400 Subject: [PATCH] Move docs around Move the docs of functions to the actual functions. Also add docs for some new apis. --- glib/gthread-posix.c | 237 ++++++++++++++++++++++++++++++++++++++++++++ glib/gthread.c | 275 ++++++++++----------------------------------------- 2 files changed, 290 insertions(+), 222 deletions(-) diff --git a/glib/gthread-posix.c b/glib/gthread-posix.c index 10ef8ed..ff5e5aa 100644 --- a/glib/gthread-posix.c +++ b/glib/gthread-posix.c @@ -60,6 +60,37 @@ g_thread_abort (gint status, } /* {{{1 GMutex */ + +/** + * g_mutex_init: + * @mutex: an uninitialized #GMutex + * + * Initializes a #GMutex so that it can be used. + * + * 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. + * + * |[ + * 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(). + * + * Since: 2.32 + */ void g_mutex_init (GMutex *mutex) { @@ -69,6 +100,17 @@ g_mutex_init (GMutex *mutex) g_thread_abort (status, "pthread_mutex_init"); } +/** + * g_mutex_clear: + * @mutex: an initialized #GMutex + * + * 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. + * + * Sine: 2.32 + */ void g_mutex_clear (GMutex *mutex) { @@ -78,6 +120,22 @@ g_mutex_clear (GMutex *mutex) g_thread_abort (status, "pthread_mutex_destroy"); } +/** + * g_mutex_lock: + * @mutex: a #GMutex + * + * Locks @mutex. If @mutex is already locked by another thread, the + * current thread will block until @mutex is unlocked by the other + * thread. + * + * This function can be used even if g_thread_init() has not yet been + * called, and, in that case, will do nothing. + * + * #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. + */ void g_mutex_lock (GMutex *mutex) { @@ -87,6 +145,16 @@ g_mutex_lock (GMutex *mutex) g_thread_abort (status, "pthread_mutex_lock"); } +/** + * g_mutex_unlock: + * @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. + * + * This function can be used even if g_thread_init() has not yet been + * called, and, in that case, will do nothing. + */ void g_mutex_unlock (GMutex *mutex) { @@ -96,6 +164,25 @@ g_mutex_unlock (GMutex *mutex) g_thread_abort (status, "pthread_mutex_lock"); } +/** + * g_mutex_trylock: + * @mutex: a #GMutex + * + * Tries to lock @mutex. If @mutex is already locked by another thread, + * it immediately returns %FALSE. Otherwise it locks @mutex and returns + * %TRUE. + * + * This function can be used even if g_thread_init() has not yet been + * called, and, in that case, will immediately return %TRUE. + * + * #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. + + * Returns: %TRUE, if @mutex could be locked + */ gboolean g_mutex_trylock (GMutex *mutex) { @@ -112,6 +199,21 @@ g_mutex_trylock (GMutex *mutex) /* {{{1 GCond */ +/** + * g_cond_init: + * @cond: an uninitialized #GCond + * + * Initialized a #GCond so that it can be used. + * + * 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. + * + * Since: 2.32 + */ void g_cond_init (GCond *cond) { @@ -121,6 +223,17 @@ g_cond_init (GCond *cond) g_thread_abort (status, "pthread_cond_init"); } +/** + * g_cond_clear: + * @cond: an initialized #GCond + * + * Frees the resources allocated ot a #GCond with g_cond_init(). + * + * #GConds that have been created with g_cond_new() should + * be freed with g_cond_free() instead. + * + * Since: 2.32 + */ void g_cond_clear (GCond *cond) { @@ -130,6 +243,18 @@ g_cond_clear (GCond *cond) g_thread_abort (status, "pthread_cond_destroy"); } +/** + * g_cond_wait: + * @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. + * + * This function can be used even if g_thread_init() has not yet been + * called, and, in that case, will immediately return. + */ void g_cond_wait (GCond *cond, GMutex *mutex) @@ -140,6 +265,17 @@ g_cond_wait (GCond *cond, g_thread_abort (status, "pthread_cond_wait"); } +/** + * g_cond_signal: + * @cond: a #GCond + * + * If threads are waiting for @cond, exactly one of them is woken up. + * It is good practice to hold the same lock as the waiting thread + * while calling this function, though not required. + * + * This function can be used even if g_thread_init() has not yet been + * called, and, in that case, will do nothing. + */ void g_cond_signal (GCond *cond) { @@ -149,6 +285,17 @@ g_cond_signal (GCond *cond) g_thread_abort (status, "pthread_cond_signal"); } +/** + * g_cond_broadcast: + * @cond: a #GCond + * + * If threads are waiting for @cond, all of them are woken up. + * It is good practice to lock the same mutex as the waiting threads + * while calling this function, though not required. + * + * This function can be used even if g_thread_init() has not yet been + * called, and, in that case, will do nothing. + */ void g_cond_broadcast (GCond *cond) { @@ -158,6 +305,26 @@ g_cond_broadcast (GCond *cond) g_thread_abort (status, "pthread_cond_broadcast"); } +/** + * g_cond_timed_wait: + * @cond: a #GCond + * @mutex: a #GMutex that is currently locked + * @abs_time: a #GTimeVal, determining the final time + * + * Waits until this thread is woken up on @cond, but not longer than + * until the time specified by @abs_time. The @mutex is unlocked before + * falling asleep and locked again before resuming. + * + * If @abs_time is %NULL, g_cond_timed_wait() acts like g_cond_wait(). + * + * This function can be used even if g_thread_init() has not yet been + * called, and, in that case, will immediately return %TRUE. + * + * To easily calculate @abs_time a combination of g_get_current_time() + * and g_time_val_add() can be used. + * + * Returns: %TRUE if @cond was signalled, or %FALSE on timeout + */ gboolean g_cond_timed_wait (GCond *cond, GMutex *mutex, @@ -184,6 +351,20 @@ g_cond_timed_wait (GCond *cond, return FALSE; } +/** + * g_cond_timedwait: + * @cond: a #GCond + * @mutex: a #GMutex that is currently locked + * @abs_time: the final time, in microseconds + * + * A variant of g_cond_timed_wait() that takes @abs_time + * as a #gint64 instead of a #GTimeVal. + * See g_cond_timed_wait() for details. + * + * Returns: %TRUE if @cond was signalled, or %FALSE on timeout + * + * Since: 2.32 + */ gboolean g_cond_timedwait (GCond *cond, GMutex *mutex, @@ -206,6 +387,32 @@ g_cond_timedwait (GCond *cond, /* {{{1 GPrivate */ +/** + * g_private_new: + * @destructor: a function to destroy the data keyed to + * the #GPrivate when a thread ends + * + * Creates a new #GPrivate. If @destructor is non-%NULL, it is a + * pointer to a destructor function. Whenever a thread ends and the + * corresponding pointer keyed to this instance of #GPrivate is + * non-%NULL, the destructor is called with this pointer as the + * argument. + * + * + * #GStaticPrivate is a better choice for most uses. + * + * + * @destructor is used quite differently from @notify in + * g_static_private_set(). + * + * A #GPrivate cannot be freed. Reuse it instead, if you + * can, to avoid shortage, or use #GStaticPrivate. + * + * This function will abort if g_thread_init() has not been + * called yet. + * + * Returns: a newly allocated #GPrivate + */ GPrivate * g_private_new (GDestroyNotify notify) { @@ -227,6 +434,25 @@ g_private_init (GPrivate *key, key->ready = TRUE; } +/** + * g_private_get: + * @private_key: a #GPrivate + * + * Returns the pointer keyed to @private_key for the current thread. If + * g_private_set() hasn't been called for the current @private_key and + * thread yet, this pointer will be %NULL. + * + * This function can be used even if g_thread_init() has not yet been + * called, and, in that case, will return the value of @private_key + * casted to #gpointer. Note however, that private data set + * before g_thread_init() will + * not be retained after the + * call. Instead, %NULL will be returned in all threads directly after + * g_thread_init(), regardless of any g_private_set() calls issued + * before threading system initialization. + * + * Returns: the corresponding pointer + */ gpointer g_private_get (GPrivate *key) { @@ -237,6 +463,17 @@ g_private_get (GPrivate *key) return pthread_getspecific (key->key); } +/** + * g_private_set: + * @private_key: a #GPrivate + * @data: the new pointer + * + * Sets the pointer keyed to @private_key for the current thread. + * + * This function can be used even if g_thread_init() has not yet been + * called, and, in that case, will set @private_key to @data casted to + * #GPrivate*. See g_private_get() for resulting caveats. + */ void g_private_set (GPrivate *key, gpointer value) diff --git a/glib/gthread.c b/glib/gthread.c index 5ed3e14..9c591b5 100644 --- a/glib/gthread.c +++ b/glib/gthread.c @@ -455,82 +455,12 @@ static GThreadFunctions g_thread_functions_for_glib_use_old = { * #GStaticMutex instead. * * A #GMutex should only be accessed via the following functions. - * - * All of the g_mutex_* functions are - * actually macros. Apart from taking their addresses, you can however - * use them as if they were functions. **/ -/** - * g_mutex_new: - * @Returns: a new #GMutex. - * - * Creates a new #GMutex. - * - * This function will abort if g_thread_init() has not been - * called yet. - **/ (GMutex*(*)())g_thread_fail, - -/** - * g_mutex_lock: - * @mutex: a #GMutex. - * - * Locks @mutex. If @mutex is already locked by another thread, the - * current thread will block until @mutex is unlocked by the other - * thread. - * - * This function can be used even if g_thread_init() has not yet been - * called, and, in that case, will do nothing. - * - * #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. - **/ NULL, - -/** - * g_mutex_trylock: - * @mutex: a #GMutex. - * @Returns: %TRUE, if @mutex could be locked. - * - * Tries to lock @mutex. If @mutex is already locked by another thread, - * it immediately returns %FALSE. Otherwise it locks @mutex and returns - * %TRUE. - * - * This function can be used even if g_thread_init() has not yet been - * called, and, in that case, will immediately return %TRUE. - * - * #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. - **/ NULL, - -/** - * g_mutex_unlock: - * @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. - * - * This function can be used even if g_thread_init() has not yet been - * called, and, in that case, will do nothing. - **/ NULL, - -/** - * g_mutex_free: - * @mutex: a #GMutex. - * - * Destroys @mutex. - * - * Calling g_mutex_free() on a locked mutex may result in - * undefined behaviour. - **/ NULL, /* GCond Virtual Functions {{{2 ------------------------------------------ */ @@ -593,87 +523,13 @@ static GThreadFunctions g_thread_functions_for_glib_use_old = { * #GMutex, like above. * * A #GCond should only be accessed via the following functions. - * - * All of the g_cond_* functions are - * actually macros. Apart from taking their addresses, you can however - * use them as if they were functions. - **/ + */ -/** - * g_cond_new: - * @Returns: a new #GCond. - * - * Creates a new #GCond. This function will abort, if g_thread_init() - * has not been called yet. - **/ (GCond*(*)())g_thread_fail, - -/** - * g_cond_signal: - * @cond: a #GCond. - * - * If threads are waiting for @cond, exactly one of them is woken up. - * It is good practice to hold the same lock as the waiting thread - * while calling this function, though not required. - * - * This function can be used even if g_thread_init() has not yet been - * called, and, in that case, will do nothing. - **/ NULL, - -/** - * g_cond_broadcast: - * @cond: a #GCond. - * - * If threads are waiting for @cond, all of them are woken up. It is - * good practice to lock the same mutex as the waiting threads, while - * calling this function, though not required. - * - * This function can be used even if g_thread_init() has not yet been - * called, and, in that case, will do nothing. - **/ NULL, - -/** - * g_cond_wait: - * @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. - * - * This function can be used even if g_thread_init() has not yet been - * called, and, in that case, will immediately return. - **/ NULL, - -/** - * g_cond_timed_wait: - * @cond: a #GCond. - * @mutex: a #GMutex that is currently locked. - * @abs_time: a #GTimeVal, determining the final time. - * @Returns: %TRUE if @cond was signalled, or %FALSE on timeout. - * - * Waits until this thread is woken up on @cond, but not longer than - * until the time specified by @abs_time. The @mutex is unlocked before - * falling asleep and locked again before resuming. - * - * If @abs_time is %NULL, g_cond_timed_wait() acts like g_cond_wait(). - * - * This function can be used even if g_thread_init() has not yet been - * called, and, in that case, will immediately return %TRUE. - * - * To easily calculate @abs_time a combination of g_get_current_time() - * and g_time_val_add() can be used. - **/ NULL, - -/** - * g_cond_free: - * @cond: a #GCond. - * - * Destroys the #GCond. - **/ NULL, /* GPrivate Virtual Functions {{{2 --------------------------------------- */ @@ -732,64 +588,8 @@ static GThreadFunctions g_thread_functions_for_glib_use_old = { * use them as if they were functions. **/ -/** - * g_private_new: - * @destructor: a function to destroy the data keyed to #GPrivate when - * a thread ends. - * @Returns: a new #GPrivate. - * - * Creates a new #GPrivate. If @destructor is non-%NULL, it is a - * pointer to a destructor function. Whenever a thread ends and the - * corresponding pointer keyed to this instance of #GPrivate is - * non-%NULL, the destructor is called with this pointer as the - * argument. - * - * - * #GStaticPrivate is a better choice for most uses. - * - * - * @destructor is used quite differently from @notify in - * g_static_private_set(). - * - * A #GPrivate cannot be freed. Reuse it instead, if you - * can, to avoid shortage, or use #GStaticPrivate. - * - * This function will abort if g_thread_init() has not been - * called yet. - **/ (GPrivate*(*)(GDestroyNotify))g_thread_fail, - -/** - * g_private_get: - * @private_key: a #GPrivate. - * @Returns: the corresponding pointer. - * - * Returns the pointer keyed to @private_key for the current thread. If - * g_private_set() hasn't been called for the current @private_key and - * thread yet, this pointer will be %NULL. - * - * This function can be used even if g_thread_init() has not yet been - * called, and, in that case, will return the value of @private_key - * casted to #gpointer. Note however, that private data set - * before g_thread_init() will - * not be retained after the - * call. Instead, %NULL will be returned in all threads directly after - * g_thread_init(), regardless of any g_private_set() calls issued - * before threading system intialization. - **/ NULL, - -/** - * g_private_set: - * @private_key: a #GPrivate. - * @data: the new pointer. - * - * Sets the pointer keyed to @private_key for the current thread. - * - * This function can be used even if g_thread_init() has not yet been - * called, and, in that case, will set @private_key to @data casted to - * #GPrivate*. See g_private_get() for resulting caveats. - **/ NULL, /* GThread Virtual Functions {{{2 ---------------------------------------- */ @@ -830,26 +630,6 @@ static GThreadFunctions g_thread_functions_for_glib_use_old = { * try to avoid being dependent on priorities. **/ -/** - * g_thread_create: - * @func: a function to execute in the new thread. - * @data: an argument to supply to the new thread. - * @joinable: should this thread be joinable? - * @error: return location for error. - * @Returns: the new #GThread on success. - * - * This function creates a new thread with the default priority. - * - * If @joinable is %TRUE, you can wait for this threads termination - * calling g_thread_join(). Otherwise the thread will just disappear - * when it terminates. - * - * The new thread executes the function @func with the argument @data. - * If the thread was created successfully, it is returned. - * - * @error can be %NULL to ignore errors, or non-%NULL to report errors. - * The error is set, if and only if the function returns %NULL. - **/ (void(*)(GThreadFunc, gpointer, gulong, gboolean, gboolean, GThreadPriority, gpointer, GError**))g_thread_fail, @@ -1921,6 +1701,28 @@ g_thread_create_proxy (gpointer data) } /** + * g_thread_create: + * @func: a function to execute in the new thread + * @data: an argument to supply to the new thread + * @joinable: should this thread be joinable? + * @error: return location for error, or %NULL + * + * This function creates a new thread with the default priority. + * + * If @joinable is %TRUE, you can wait for this threads termination + * calling g_thread_join(). Otherwise the thread will just disappear + * when it terminates. + * + * The new thread executes the function @func with the argument @data. + * If the thread was created successfully, it is returned. + * + * @error can be %NULL to ignore errors, or non-%NULL to report errors. + * The error is set, if and only if the function returns %NULL. + * + * Returns: the new #GThread on success + */ + +/** * g_thread_create_full: * @func: a function to execute in the new thread. * @data: an argument to supply to the new thread. @@ -2558,7 +2360,7 @@ g_thread_foreach (GFunc thread_func, } /** - * g_thread_get_initialized + * g_thread_get_initialized: * * Indicates if g_thread_init() has been called. * @@ -2572,6 +2374,13 @@ g_thread_get_initialized () return g_thread_supported (); } +/** + * g_mutex_new: + * + * Creates a new #GMutex. + * + * Returns: a newly allocated #GMutex. Use g_mutex_free() to free + */ GMutex * g_mutex_new (void) { @@ -2583,6 +2392,15 @@ g_mutex_new (void) return mutex; } +/** + * g_mutex_free: + * @mutex: a #GMutex + * + * Destroys a @mutex that has been created with g_mutex_new(). + * + * Calling g_mutex_free() on a locked mutex may result + * in undefined behaviour. + */ void g_mutex_free (GMutex *mutex) { @@ -2590,6 +2408,13 @@ g_mutex_free (GMutex *mutex) g_slice_free (GMutex, mutex); } +/** + * g_cond_new: + * + * Creates a new #GCond. + * + * Returns: a newly allocated #GCond. Free with g_cond_free() + */ GCond * g_cond_new (void) { @@ -2601,6 +2426,12 @@ g_cond_new (void) return cond; } +/** + * g_cond_free: + * @cond: a #GCond + * + * Destroys a #GCond that has been created with g_cond_new(). + */ void g_cond_free (GCond *cond) { -- 2.7.4