Look for nanosleep function.

[platform/upstream/glib.git] / docs / reference / glib / tmpl / threads.sgml

diff --git a/docs/reference/glib/tmpl/threads.sgml b/docs/reference/glib/tmpl/threads.sgml
index 3d75a90..80f2c71 100644 (file)
--- a/docs/reference/glib/tmpl/threads.sgml
+++ b/docs/reference/glib/tmpl/threads.sgml
@@ -219,11 +219,13 @@ you can however use it as if it was a function.
 
 <!-- ##### USER_FUNCTION GThreadFunc ##### -->
 <para>
-Specifies the type of the @thread_func functions passed to
-g_thread_create().
+Specifies the type of the @func functions passed to
+g_thread_create() or g_thread_create_full().
 </para>
 
-@value: data supplied to the thread
+@data: data passed to the thread
+@Returns: the return value of the thread, which will be returned by
+g_thread_join()
 
 
 <!-- ##### ENUM GThreadPriority ##### -->
@@ -260,12 +262,41 @@ g_thread_join() is called for that thread.
 </para>
 </note>
 
+@func: the function executing in that thread
+@data: the argument to the function
 @joinable: is this thread joinable?
-@bound: is this thread bound to a system thread?
 @priority: the priority of the thread
 
 <!-- ##### FUNCTION g_thread_create ##### -->
 <para>
+This function creates a new thread with the priority @priority.
+</para>
+
+<para>
+If @joinable is #TRUE, you can wait for this threads termination
+calling g_thread_wait(). Otherwise the thread will just disappear, when
+ready. 
+</para>
+
+<para>
+The new thread executes the function @func with the argument
+@data. If the thread was created successfully, it is returned.
+</para>
+
+<para>
+@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.
+</para>
+
+@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
+
+
+<!-- ##### FUNCTION g_thread_create_full ##### -->
+<para>
 This function creates a new thread with the priority @priority. The
 stack gets the size @stack_size or the default value for the current
 platform, if @stack_size is 0.
@@ -281,8 +312,8 @@ generally faster. On some systems (e.g. Linux) all threads are bound.
 </para>
 
 <para>
-The new thread executes the function @thread_func with the argument
-@arg. If the thread was created successfully, it is returned.
+The new thread executes the function @func with the argument
+@data. If the thread was created successfully, it is returned.
 </para>
 
 <para>
@@ -301,8 +332,17 @@ default.
 </para>
 </note>
 
-@thread_func: a function to execute in the new thread
-@arg: an argument to supply to the new thread
+<note>
+<para>
+Only use g_thread_create_full(), when you really can't use
+g_thread_create() instead. g_thread_create() does not take
+@stack_size, @bound and @priority as arguments, as they should only be
+used for cases, where it is inevitable. 
+</para>
+</note>
+
+@func: a function to execute in the new thread
+@data: an argument to supply to the new thread
 @stack_size: a stack size for the new thread
 @joinable: should this thread be joinable?
 @bound: should this thread be bound to a system thread?
@@ -321,14 +361,16 @@ This functions returns the #GThread corresponding to the calling thread.
 
 <!-- ##### FUNCTION g_thread_join ##### -->
 <para>
-Waits until @thread finishes, i.e. the function @thread_func, as given
+Waits until @thread finishes, i.e. the function @func, as given
 to g_thread_create, returns or g_thread_exit() is called by
 @thread. All resources of @thread including the #GThread struct are
 released. @thread must have been created with @joinable=#TRUE in
-g_thread_create().
+g_thread_create(). The value returned by @func or given to
+g_thread_exit() by @thread is returned by this function.
 </para>
 
 @thread: a #GThread to be waited for
+@Returns: the return value of the thread
 
 
 <!-- ##### FUNCTION g_thread_set_priority ##### -->
@@ -366,7 +408,34 @@ to do that. So in general you shouldn't use that function.
 <!-- ##### FUNCTION g_thread_exit ##### -->
 <para>
 Exit the current thread. If another thread is waiting for that thread
-using g_thread_join(), that thread will be woken up. 
+using g_thread_join() and the current thread is joinable, the waiting
+thread will be woken up and getting @retval as the return value of
+g_thread_join(). If the current thread is not joinable, @retval is
+ignored. Calling
+</para>
+
+<para>
+<informalexample>
+<programlisting>
+g_thread_join (retval);
+</programlisting>
+</informalexample>
+</para>
+
+<para>
+is equivalent to calling 
+</para>
+
+<para>
+<informalexample>
+<programlisting>
+return retval;
+</programlisting>
+</informalexample>
+</para>
+
+<para>
+in the function @func, as given to g_thread_create().
 </para>
 
 <note>
@@ -377,6 +446,7 @@ results.
 </para>
 </note>
 
+@retval: the return value of this thread
 
 
 <!-- ##### STRUCT GMutex ##### -->
@@ -516,7 +586,7 @@ called and will do nothing then.
 <note>
 <para>
 #GMutex is not recursive, i.e. a thread will deadlock, if it already
-has locked the #GMutex while calling g_mutex_lock(). Use
+has locked @mutex while calling g_mutex_lock(). Use
 #GStaticRecMutex instead, if you need recursive mutexes.
 </para>
 </note>
@@ -537,6 +607,14 @@ This function can also be used, if g_thread_init() has not yet been
 called and will immediately return TRUE then.
 </para>
 
+<note>
+<para>
+#GMutex is not recursive, i.e. g_mutex_trylock() will return FALSE,
+if the current thread already has locked @mutex. Use
+#GStaticRecMutex instead, if you need recursive mutexes.
+</para>
+</note>
+
 @mutex: a #GMutex
 @Returns: TRUE, if @mutex could be locked
 
@@ -1288,6 +1366,11 @@ This function can also be used, if g_thread_init() has not yet been
 called and will immediately return TRUE then.
 </para>
 
+<para>
+To easily calculate @abs_time a combination of g_get_current_time()
+and g_time_val_add() can be used.
+</para>
+
 @cond: a #GCond
 @mutex: a #GMutex, that is currently locked
 @abs_time: a #GTimeVal, determining the final time