threads.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

<refentry id="glib-Threads">
<refmeta>
<refentrytitle>
Threads</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>
Threads</refname><refpurpose>
thread abstraction; including threads, different mutexes, conditions
and thread private data.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;glib.h&gt;



#define     <link linkend="G-THREADS-ENABLED-CAPS">G_THREADS_ENABLED</link>
#define     <link linkend="G-THREADS-IMPL-POSIX-CAPS">G_THREADS_IMPL_POSIX</link>
#define     <link linkend="G-THREADS-IMPL-SOLARIS-CAPS">G_THREADS_IMPL_SOLARIS</link>
#define     <link linkend="G-THREADS-IMPL-NONE-CAPS">G_THREADS_IMPL_NONE</link>

#define     <link linkend="G-THREAD-ERROR-CAPS">G_THREAD_ERROR</link>
enum        <link linkend="GThreadError">GThreadError</link>;

struct      <link linkend="GThreadFunctions">GThreadFunctions</link>;
void        <link linkend="g-thread-init">g_thread_init</link>                   (<link linkend="GThreadFunctions">GThreadFunctions</link> *vtable);
<link linkend="gboolean">gboolean</link>    <link linkend="g-thread-supported">g_thread_supported</link>              ();

<link linkend="gpointer">gpointer</link>    (<link linkend="GThreadFunc">*GThreadFunc</link>)                  (<link linkend="gpointer">gpointer</link> data);
enum        <link linkend="GThreadPriority">GThreadPriority</link>;
struct      <link linkend="GThread">GThread</link>;
<link linkend="GThread">GThread</link>*    <link linkend="g-thread-create">g_thread_create</link>                 (<link linkend="GThreadFunc">GThreadFunc</link> func,
                                             <link linkend="gpointer">gpointer</link> data,
                                             <link linkend="gboolean">gboolean</link> joinable,
                                             <link linkend="GError">GError</link> **error);
<link linkend="GThread">GThread</link>*    <link linkend="g-thread-create-full">g_thread_create_full</link>            (<link linkend="GThreadFunc">GThreadFunc</link> func,
                                             <link linkend="gpointer">gpointer</link> data,
                                             <link linkend="gulong">gulong</link> stack_size,
                                             <link linkend="gboolean">gboolean</link> joinable,
                                             <link linkend="gboolean">gboolean</link> bound,
                                             <link linkend="GThreadPriority">GThreadPriority</link> priority,
                                             <link linkend="GError">GError</link> **error);
<link linkend="GThread">GThread</link>*    <link linkend="g-thread-self">g_thread_self</link>                   (void);
<link linkend="gpointer">gpointer</link>    <link linkend="g-thread-join">g_thread_join</link>                   (<link linkend="GThread">GThread</link> *thread);
void        <link linkend="g-thread-set-priority">g_thread_set_priority</link>           (<link linkend="GThread">GThread</link> *thread,
                                             <link linkend="GThreadPriority">GThreadPriority</link> priority);
void        <link linkend="g-thread-yield">g_thread_yield</link>                  ();
void        <link linkend="g-thread-exit">g_thread_exit</link>                   (<link linkend="gpointer">gpointer</link> retval);

struct      <link linkend="GMutex">GMutex</link>;
<link linkend="GMutex">GMutex</link>*     <link linkend="g-mutex-new">g_mutex_new</link>                     ();
void        <link linkend="g-mutex-lock">g_mutex_lock</link>                    (<link linkend="GMutex">GMutex</link> *mutex);
<link linkend="gboolean">gboolean</link>    <link linkend="g-mutex-trylock">g_mutex_trylock</link>                 (<link linkend="GMutex">GMutex</link> *mutex);
void        <link linkend="g-mutex-unlock">g_mutex_unlock</link>                  (<link linkend="GMutex">GMutex</link> *mutex);
void        <link linkend="g-mutex-free">g_mutex_free</link>                    (<link linkend="GMutex">GMutex</link> *mutex);

struct      <link linkend="GStaticMutex">GStaticMutex</link>;
#define     <link linkend="G-STATIC-MUTEX-INIT-CAPS">G_STATIC_MUTEX_INIT</link>
void        <link linkend="g-static-mutex-init">g_static_mutex_init</link>             (<link linkend="GStaticMutex">GStaticMutex</link> *mutex);
void        <link linkend="g-static-mutex-lock">g_static_mutex_lock</link>             (<link linkend="GStaticMutex">GStaticMutex</link> *mutex);
<link linkend="gboolean">gboolean</link>    <link linkend="g-static-mutex-trylock">g_static_mutex_trylock</link>          (<link linkend="GStaticMutex">GStaticMutex</link> *mutex);
void        <link linkend="g-static-mutex-unlock">g_static_mutex_unlock</link>           (<link linkend="GStaticMutex">GStaticMutex</link> *mutex);
<link linkend="GMutex">GMutex</link>*     <link linkend="g-static-mutex-get-mutex">g_static_mutex_get_mutex</link>        (<link linkend="GStaticMutex">GStaticMutex</link> *mutex);
void        <link linkend="g-static-mutex-free">g_static_mutex_free</link>             (<link linkend="GStaticMutex">GStaticMutex</link> *mutex);

#define     <link linkend="G-LOCK-DEFINE-CAPS">G_LOCK_DEFINE</link>                   (name)
#define     <link linkend="G-LOCK-DEFINE-STATIC-CAPS">G_LOCK_DEFINE_STATIC</link>            (name)
#define     <link linkend="G-LOCK-EXTERN-CAPS">G_LOCK_EXTERN</link>                   (name)
#define     <link linkend="G-LOCK-CAPS">G_LOCK</link>                          (name)
#define     <link linkend="G-TRYLOCK-CAPS">G_TRYLOCK</link>                       (name)
#define     <link linkend="G-UNLOCK-CAPS">G_UNLOCK</link>                        (name)

struct      <link linkend="GStaticRecMutex">GStaticRecMutex</link>;
#define     <link linkend="G-STATIC-REC-MUTEX-INIT-CAPS">G_STATIC_REC_MUTEX_INIT</link>
void        <link linkend="g-static-rec-mutex-init">g_static_rec_mutex_init</link>         (<link linkend="GStaticRecMutex">GStaticRecMutex</link> *mutex);
void        <link linkend="g-static-rec-mutex-lock">g_static_rec_mutex_lock</link>         (<link linkend="GStaticRecMutex">GStaticRecMutex</link> *mutex);
<link linkend="gboolean">gboolean</link>    <link linkend="g-static-rec-mutex-trylock">g_static_rec_mutex_trylock</link>      (<link linkend="GStaticRecMutex">GStaticRecMutex</link> *mutex);
void        <link linkend="g-static-rec-mutex-unlock">g_static_rec_mutex_unlock</link>       (<link linkend="GStaticRecMutex">GStaticRecMutex</link> *mutex);
void        <link linkend="g-static-rec-mutex-lock-full">g_static_rec_mutex_lock_full</link>    (<link linkend="GStaticRecMutex">GStaticRecMutex</link> *mutex,
                                             <link linkend="guint">guint</link> depth);
<link linkend="guint">guint</link>       <link linkend="g-static-rec-mutex-unlock-full">g_static_rec_mutex_unlock_full</link>  (<link linkend="GStaticRecMutex">GStaticRecMutex</link> *mutex);
void        <link linkend="g-static-rec-mutex-free">g_static_rec_mutex_free</link>         (<link linkend="GStaticRecMutex">GStaticRecMutex</link> *mutex);

struct      <link linkend="GStaticRWLock">GStaticRWLock</link>;
#define     <link linkend="G-STATIC-RW-LOCK-INIT-CAPS">G_STATIC_RW_LOCK_INIT</link>
void        <link linkend="g-static-rw-lock-init">g_static_rw_lock_init</link>           (<link linkend="GStaticRWLock">GStaticRWLock</link> *lock);
void        <link linkend="g-static-rw-lock-reader-lock">g_static_rw_lock_reader_lock</link>    (<link linkend="GStaticRWLock">GStaticRWLock</link> *lock);
<link linkend="gboolean">gboolean</link>    <link linkend="g-static-rw-lock-reader-trylock">g_static_rw_lock_reader_trylock</link> (<link linkend="GStaticRWLock">GStaticRWLock</link> *lock);
void        <link linkend="g-static-rw-lock-reader-unlock">g_static_rw_lock_reader_unlock</link>  (<link linkend="GStaticRWLock">GStaticRWLock</link> *lock);
void        <link linkend="g-static-rw-lock-writer-lock">g_static_rw_lock_writer_lock</link>    (<link linkend="GStaticRWLock">GStaticRWLock</link> *lock);
<link linkend="gboolean">gboolean</link>    <link linkend="g-static-rw-lock-writer-trylock">g_static_rw_lock_writer_trylock</link> (<link linkend="GStaticRWLock">GStaticRWLock</link> *lock);
void        <link linkend="g-static-rw-lock-writer-unlock">g_static_rw_lock_writer_unlock</link>  (<link linkend="GStaticRWLock">GStaticRWLock</link> *lock);
void        <link linkend="g-static-rw-lock-free">g_static_rw_lock_free</link>           (<link linkend="GStaticRWLock">GStaticRWLock</link> *lock);

struct      <link linkend="GCond">GCond</link>;
<link linkend="GCond">GCond</link>*      <link linkend="g-cond-new">g_cond_new</link>                      ();
void        <link linkend="g-cond-signal">g_cond_signal</link>                   (<link linkend="GCond">GCond</link> *cond);
void        <link linkend="g-cond-broadcast">g_cond_broadcast</link>                (<link linkend="GCond">GCond</link> *cond);
void        <link linkend="g-cond-wait">g_cond_wait</link>                     (<link linkend="GCond">GCond</link> *cond,
                                             <link linkend="GMutex">GMutex</link> *mutex);
<link linkend="gboolean">gboolean</link>    <link linkend="g-cond-timed-wait">g_cond_timed_wait</link>               (<link linkend="GCond">GCond</link> *cond,
                                             <link linkend="GMutex">GMutex</link> *mutex,
                                             <link linkend="GTimeVal">GTimeVal</link> *abs_time);
void        <link linkend="g-cond-free">g_cond_free</link>                     (<link linkend="GCond">GCond</link> *cond);

struct      <link linkend="GPrivate">GPrivate</link>;
<link linkend="GPrivate">GPrivate</link>*   <link linkend="g-private-new">g_private_new</link>                   (<link linkend="GDestroyNotify">GDestroyNotify</link> destructor);
<link linkend="gpointer">gpointer</link>    <link linkend="g-private-get">g_private_get</link>                   (<link linkend="GPrivate">GPrivate</link> *private_key);
void        <link linkend="g-private-set">g_private_set</link>                   (<link linkend="GPrivate">GPrivate</link> *private_key,
                                             <link linkend="gpointer">gpointer</link> data);

struct      <link linkend="GStaticPrivate">GStaticPrivate</link>;
#define     <link linkend="G-STATIC-PRIVATE-INIT-CAPS">G_STATIC_PRIVATE_INIT</link>
void        <link linkend="g-static-private-init">g_static_private_init</link>           (<link linkend="GStaticPrivate">GStaticPrivate</link> *private_key);
<link linkend="gpointer">gpointer</link>    <link linkend="g-static-private-get">g_static_private_get</link>            (<link linkend="GStaticPrivate">GStaticPrivate</link> *private_key);
void        <link linkend="g-static-private-set">g_static_private_set</link>            (<link linkend="GStaticPrivate">GStaticPrivate</link> *private_key,
                                             <link linkend="gpointer">gpointer</link> data,
                                             <link linkend="GDestroyNotify">GDestroyNotify</link> notify);
void        <link linkend="g-static-private-free">g_static_private_free</link>           (<link linkend="GStaticPrivate">GStaticPrivate</link> *private_key);


</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>

<para>
Threads act almost like processes, but unlike processes all threads of
one process share the same memory. This is good, as it provides easy
communication between the involved threads via this shared memory, and
it is bad, because strange things (so called Heisenbugs) might happen,
when the program is not carefully designed. Especially bad is, that due
to the concurrent nature of threads no assumptions on the order of
execution of different threads can be done unless explicitly forced by
the programmer through synchronization primitives.
</para>

<para>
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
(<link linkend="GMutex">GMutex</link>, <link linkend="GStaticMutex">GStaticMutex</link>, <link linkend="G-LOCK-DEFINE-CAPS">G_LOCK_DEFINE</link>, <link linkend="GStaticRecMutex">GStaticRecMutex</link> and
<link linkend="GStaticRWLock">GStaticRWLock</link>), there are primitives for condition variables to allow
synchronization of threads (<link linkend="GCond">GCond</link>) and finally there are primitives
for thread-private data, that every thread has a private instance of
(<link linkend="GPrivate">GPrivate</link>, <link linkend="GStaticPrivate">GStaticPrivate</link>). Last but definitely not least there are
primitives to portably create and manage threads (<link linkend="GThread">GThread</link>).
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="G-THREADS-ENABLED-CAPS">G_THREADS_ENABLED</title>
<programlisting>#define G_THREADS_ENABLED
</programlisting>

<para>
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 <link linkend="g-thread-init">g_thread_init</link>(), GLib will be multi-thread
safe. It isn't and cannot be, if <link linkend="G-THREADS-ENABLED-CAPS">G_THREADS_ENABLED</link> is not defined.
</para></refsect2>
<refsect2>
<title><anchor id="G-THREADS-IMPL-POSIX-CAPS">G_THREADS_IMPL_POSIX</title>
<programlisting>#define G_THREADS_IMPL_POSIX
</programlisting>

<para>
This macro is defined, if POSIX style threads are used.
</para></refsect2>
<refsect2>
<title><anchor id="G-THREADS-IMPL-SOLARIS-CAPS">G_THREADS_IMPL_SOLARIS</title>
<programlisting>#define G_THREADS_IMPL_SOLARIS
</programlisting>

<para>
This macro is defined, if the Solaris thread system is used.
</para></refsect2>
<refsect2>
<title><anchor id="G-THREADS-IMPL-NONE-CAPS">G_THREADS_IMPL_NONE</title>
<programlisting>#define G_THREADS_IMPL_NONE
</programlisting>

<para>
This macro is defined, if no thread implementation is used. You can
however provide one to <link linkend="g-thread-init">g_thread_init</link>() to make GLib multi-thread safe.
</para></refsect2>
<refsect2>
<title><anchor id="G-THREAD-ERROR-CAPS">G_THREAD_ERROR</title>
<programlisting>#define G_THREAD_ERROR g_thread_error_quark ()
</programlisting>
<para>
The error domain of the GLib thread subsystem.
</para></refsect2>
<refsect2>
<title><anchor id="GThreadError">enum GThreadError</title>
<programlisting>typedef enum
{
  G_THREAD_ERROR_AGAIN /* Resource temporarily unavailable */
} GThreadError;
</programlisting>
<para>
Possible errors of thread related functions.
</para><informaltable pgwide="1" frame="none" role="enum">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row>
<entry><literal>G_THREAD_ERROR_AGAIN</literal></entry>
<entry>a thread couldn't be created due to resource
shortage. Try again later.

</entry>
</row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="GThreadFunctions">struct GThreadFunctions</title>
<programlisting>struct GThreadFunctions
{
  GMutex*  (*mutex_new)           (void);
  void     (*mutex_lock)          (GMutex               *mutex);
  gboolean (*mutex_trylock)       (GMutex               *mutex);
  void     (*mutex_unlock)        (GMutex               *mutex);
  void     (*mutex_free)          (GMutex               *mutex);
  GCond*   (*cond_new)            (void);
  void     (*cond_signal)         (GCond                *cond);
  void     (*cond_broadcast)      (GCond                *cond);
  void     (*cond_wait)           (GCond                *cond,
                                   GMutex               *mutex);
  gboolean (*cond_timed_wait)     (GCond                *cond,
                                   GMutex               *mutex,
                                   GTimeVal             *end_time);
  void      (*cond_free)          (GCond                *cond);
  GPrivate* (*private_new)        (GDestroyNotify        destructor);
  gpointer  (*private_get)        (GPrivate             *private_key);
  void      (*private_set)        (GPrivate             *private_key,
                                   gpointer              data);
  void      (*thread_create)      (GThreadFunc           func,
                                   gpointer              data,
                                   gulong                stack_size,
                                   gboolean              joinable,
                                   gboolean              bound,
                                   GThreadPriority       priority,
                                   gpointer              thread,
                                   GError              **error);
  void      (*thread_yield)       (void);
  void      (*thread_join)        (gpointer              thread);
  void      (*thread_exit)        (void);
  void      (*thread_set_priority)(gpointer              thread,
                                   GThreadPriority       priority);
  void      (*thread_self)        (gpointer              thread);
  gboolean  (*thread_equal)       (gpointer              thread1,
				   gpointer              thread2);
};
</programlisting>

<para>
This function table is used by <link linkend="g-thread-init">g_thread_init</link>() to initialize the
thread system. The functions in that table are directly used by their
g_* prepended counterparts, that are described here, e.g. if you call
<link linkend="g-mutex-new">g_mutex_new</link>() then <link linkend="mutex-new">mutex_new</link>() from the table provided to
<link linkend="g-thread-init">g_thread_init</link>() will be called.
</para>

<note>
<para>
This struct should only be used, if you know, what you are doing.
</para>
</note></refsect2>
<refsect2>
<title><anchor id="g-thread-init">g_thread_init ()</title>
<programlisting>void        g_thread_init                   (<link linkend="GThreadFunctions">GThreadFunctions</link> *vtable);</programlisting>

<para>
Before you use a thread related function in GLib, you should
initialize the thread system. This is done by calling
<link linkend="g-thread-init">g_thread_init</link>(). Most of the time you will only have to call
<literal>g_thread_init(NULL)</literal>. 
</para>

<note>
<para>