Commit e4699af8 authored by Matthias Clasen's avatar Matthias Clasen

Documentation tweaks

parent 55654fc8
...@@ -82,10 +82,10 @@ ...@@ -82,10 +82,10 @@
* (#GMutex, #GRecMutex and #GRWLock). There is a facility to use * (#GMutex, #GRecMutex and #GRWLock). There is a facility to use
* individual bits for locks (g_bit_lock()). There are primitives * individual bits for locks (g_bit_lock()). There are primitives
* for condition variables to allow synchronization of threads (#GCond). * for condition variables to allow synchronization of threads (#GCond).
* There are primitives for thread-private data - data that every thread * There are primitives for thread-private data - data that every
* has a private instance of (#GPrivate). There are * thread has a private instance of (#GPrivate). There are facilities
* facilities for one-time initialization (#GOnce, g_once_init_enter()). * for one-time initialization (#GOnce, g_once_init_enter()). Finally,
* Finally there are primitives to create and manage threads (#GThread). * there are primitives to create and manage threads (#GThread).
* *
* The GLib threading system used to be initialized with g_thread_init(). * The GLib threading system used to be initialized with g_thread_init().
* This is no longer necessary. Since version 2.32, the GLib threading * This is no longer necessary. Since version 2.32, the GLib threading
...@@ -422,9 +422,15 @@ ...@@ -422,9 +422,15 @@
* GThread: * GThread:
* *
* The #GThread struct represents a running thread. This struct * The #GThread struct represents a running thread. This struct
* is returned by g_thread_new() or g_thread_try_new(). You can obtain * is returned by g_thread_new() or g_thread_try_new(). You can
* the #GThread struct representing the current thead by calling * obtain the #GThread struct representing the current thead by
* g_thread_self(). * calling g_thread_self().
*
* GThread is refcounted, see g_thread_ref() and g_thread_unref().
* The thread represented by it holds a reference while it is running,
* and g_thread_join() consumes the reference that it is given, so
* it is normally not necessary to manage GThread references
* explicitly.
* *
* The structure is opaque -- none of its fields may be directly * The structure is opaque -- none of its fields may be directly
* accessed. * accessed.
...@@ -434,8 +440,8 @@ ...@@ -434,8 +440,8 @@
* GThreadFunc: * GThreadFunc:
* @data: data passed to the thread * @data: data passed to the thread
* *
* Specifies the type of the @func functions passed to g_thread_new() or * Specifies the type of the @func functions passed to g_thread_new()
* g_thread_try_new(). * or g_thread_try_new().
* *
* Returns: the return value of the thread * Returns: the return value of the thread
*/ */
...@@ -679,8 +685,9 @@ void ...@@ -679,8 +685,9 @@ void
* Increase the reference count on @thread. * Increase the reference count on @thread.
* *
* Returns: a new reference to @thread * Returns: a new reference to @thread
*
* Since: 2.32 * Since: 2.32
**/ */
GThread * GThread *
g_thread_ref (GThread *thread) g_thread_ref (GThread *thread)
{ {
...@@ -698,8 +705,12 @@ g_thread_ref (GThread *thread) ...@@ -698,8 +705,12 @@ g_thread_ref (GThread *thread)
* Decrease the reference count on @thread, possibly freeing all * Decrease the reference count on @thread, possibly freeing all
* resources associated with it. * resources associated with it.
* *
* Note that each thread holds a reference to its #GThread while
* it is running, so it is safe to drop your own reference to it
* if you don't need it anymore.
*
* Since: 2.32 * Since: 2.32
**/ */
void void
g_thread_unref (GThread *thread) g_thread_unref (GThread *thread)
{ {
...@@ -749,19 +760,22 @@ g_thread_proxy (gpointer data) ...@@ -749,19 +760,22 @@ g_thread_proxy (gpointer data)
* @name: a name for the new thread * @name: a name for the new thread
* @func: a function to execute in the new thread * @func: a function to execute in the new thread
* @data: an argument to supply to the new thread * @data: an argument to supply to the new thread
* @error: return location for error
* *
* This function creates a new thread. The new thread starts by invoking * This function creates a new thread. The new thread starts by invoking
* @func with the argument data. The thread will run until @func returns * @func with the argument data. The thread will run until @func returns
* or until g_thread_exit() is called from the new thread. * or until g_thread_exit() is called from the new thread. The return value
* of @func becomes the return value of the thread, which can be obtained
* with g_thread_join().
* *
* The @name can be useful for discriminating threads in * The @name can be useful for discriminating threads in a debugger.
* a debugger. Some systems restrict the length of @name to * Some systems restrict the length of @name to 16 bytes.
* 16 bytes.
* *
* If the thread can not be created the program aborts. See * If the thread can not be created the program aborts. See
* g_thread_try_new() if you want to attempt to deal with failures. * g_thread_try_new() if you want to attempt to deal with failures.
* *
* To free the struct returned by this function, use g_thread_unref().
* Note that g_thread_join() implicitly unrefs the #GThread as well.
*
* Returns: the new #GThread * Returns: the new #GThread
* *
* Since: 2.32 * Since: 2.32
...@@ -885,8 +899,10 @@ g_thread_exit (gpointer retval) ...@@ -885,8 +899,10 @@ g_thread_exit (gpointer retval)
* The value returned by @func or given to g_thread_exit() is * The value returned by @func or given to g_thread_exit() is
* returned by this function. * returned by this function.
* *
* All resources of @thread including the #GThread struct are * g_thread_join() consumes the reference to the passed-in @thread.
* released before g_thread_join() returns. * This will usually cause the #GThread struct and associated resources
* to be freed. Use g_thread_ref() to obtain an extra reference if you
* want to keep the GThread alive beyond the g_thread_join() call.
* *
* Returns: the return value of the thread * Returns: the return value of the thread
*/ */
...@@ -916,13 +932,13 @@ g_thread_join (GThread *thread) ...@@ -916,13 +932,13 @@ g_thread_join (GThread *thread)
* *
* This functions returns the #GThread corresponding to the * This functions returns the #GThread corresponding to the
* current thread. Note that this function does not increase * current thread. Note that this function does not increase
* the reference count of the returned object. * the reference count of the returned struct.
* *
* This function will return a #GThread even for threads that were not * This function will return a #GThread even for threads that
* created by GLib (ie: those created by other threading APIs). This * were not created by GLib (i.e. those created by other threading
* may be useful for thread identification purposes (ie: comparisons) * APIs). This may be useful for thread identification purposes
* but you must not use GLib functions (such as g_thread_join()) on * (i.e. comparisons) but you must not use GLib functions (such
* these threads. * as g_thread_join()) on these threads.
* *
* Returns: the #GThread representing the current thread * Returns: the #GThread representing the current thread
*/ */
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment