<para>
The aim of the thread related functions in GLib is to provide a
-portable means for writing multithreaded software. There are
+portable means for writing multi-threaded software. There are
primitives for mutexes to protect the access to portions of memory
(#GMutex, #GStaticMutex, #G_LOCK_DEFINE, #GStaticRecMutex and
#GStaticRWLock), there are primitives for condition variables to allow
This macro is defined, if GLib was compiled with thread support. This
does not necessarily mean, that there is a thread implementation
available, but the infrastructure is in place and once you provide a
-thread implementation to g_thread_init(), GLib will be multithread
+thread implementation to g_thread_init(), GLib will be multi-thread
safe. It isn't and cannot be, if #G_THREADS_ENABLED is not defined.
</para>
<para>
This macro is defined, if no thread implementation is used. You can
-however provide one to g_thread_init() to make GLib multithread safe.
+however provide one to g_thread_init() to make GLib multi-thread safe.
</para>
<note>
<para>
g_thread_init() must not be called directly or indirectly as a
-callback from GLib. Also no mutexes may be currently locked, while
+call-back from GLib. Also no mutexes may be currently locked, while
calling g_thread_init().
</para>
</note>
<!-- ##### 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 ##### -->
<!-- ##### STRUCT GThread ##### -->
<para>
-The #Gthread struct represents a running thread. It has three public
-members, but the underlying struct is bigger, so you must not copy
-this struct. You also must not write that information.
+The #GThread struct represents a running thread. It has three public
+read-only members, but the underlying struct is bigger, so you must
+not copy this struct.
</para>
<note>
</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.
</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>
</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?
<!-- ##### 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 ##### -->
<!-- ##### 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>
</para>
</note>
+@retval: the return value of this thread
<!-- ##### STRUCT GMutex ##### -->
</para>
<para>
-It is easy to see, that this won't work in a multithreaded
+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:
</para>
<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>
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
lock can be used for protecting data, that some portions of code only
read from, while others also write. In such situations it is
desirable, that several readers can read at once, whereas of course
-only one writer may write at a time. Take a look at the followin
+only one writer may write at a time. Take a look at the following
example:
<example>
<para>
This example shows an array, which can be accessed by many readers
-(the my_array_get function) simultaniously, whereas the writers (the
+(the my_array_get function) simultaneously, whereas the writers (the
my_array_set function) only will be allowed once a time and only if no
readers currently access the array. This is because of the potentially
dangerous resizing of the array. Using that functions is fully
-multithread safe now.
+multi-thread safe now.
</para>
-</para>
+<para>
Most of the time the writers should have precedence of readers. That
means for this implementation, that as soon as a writer wants to lock
the data, no other reader is allowed to lock the data, whereas of
</para>
<para>
-Even though #GStaticRWLoc is not opaque, it should only be used with
+Even though #GStaticRWLock is not opaque, it should only be used with
the following functions.
</para>
<para>
Locks @lock for writing. If @lock is already locked for writing or
reading by other threads, this function will block until @lock is
-completly unlocked and then lock @lock for writing. While this
+completely unlocked and then lock @lock for writing. While this
functions waits to lock @lock, no other thread can lock @lock for
reading. When @lock is locked for writing, no other thread can lock
@lock (neither for reading nor writing). This lock has to be unlocked
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
@Returns: the corresponding pointer
-<!-- ##### FUNCTION g_static_private_get_for_thread ##### -->
-<para>
-
-</para>
-
-@private_key:
-@thread:
-@Returns:
-
-
<!-- ##### FUNCTION g_static_private_set ##### -->
<para>
Sets the pointer keyed to @private_key for the current thread and the
current thread ends or sets this pointer again
-<!-- ##### FUNCTION g_static_private_set_for_thread ##### -->
-<para>
-
-</para>
-
-@private_key:
-@thread:
-@data:
-@notify:
-
-
<!-- ##### FUNCTION g_static_private_free ##### -->
<para>
Releases all resources allocated to @private_key.
projects / platform / upstream / glib.git / blobdiff