lib/glthread/thread.h

   1 /* Creating and controlling threads.
   2    Copyright (C) 2005-2013 Free Software Foundation, Inc.
   3
   4    This program is free software; you can redistribute it and/or modify
   5    it under the terms of the GNU General Public License as published by
   6    the Free Software Foundation; either version 2, or (at your option)
   7    any later version.
   8
   9    This program is distributed in the hope that it will be useful,
  10    but WITHOUT ANY WARRANTY; without even the implied warranty of
  11    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12    GNU General Public License for more details.
  13
  14    You should have received a copy of the GNU General Public License
  15    along with this program; if not, see <http://www.gnu.org/licenses/>.  */
  16
  17 /* Written by Bruno Haible <bruno@clisp.org>, 2005.
  18    Based on GCC's gthr-posix.h, gthr-posix95.h, gthr-solaris.h,
  19    gthr-win32.h.  */
  20
  21 /* This file contains primitives for creating and controlling threads.
  22
  23    Thread data type: gl_thread_t.
  24
  25    Creating a thread:
  26        thread = gl_thread_create (func, arg);
  27    Or with control of error handling:
  28        err = glthread_create (&thread, func, arg);
  29        extern int glthread_create (gl_thread_t *result,
  30                                    void *(*func) (void *), void *arg);
  31
  32    Querying and changing the signal mask of a thread (not supported on all
  33    platforms):
  34        gl_thread_sigmask (how, newmask, oldmask);
  35    Or with control of error handling:
  36        err = glthread_sigmask (how, newmask, oldmask);
  37        extern int glthread_sigmask (int how, const sigset_t *newmask, sigset_t *oldmask);
  38
  39    Waiting for termination of another thread:
  40        gl_thread_join (thread, &return_value);
  41    Or with control of error handling:
  42        err = glthread_join (thread, &return_value);
  43        extern int glthread_join (gl_thread_t thread, void **return_value_ptr);
  44
  45    Getting a reference to the current thread:
  46        current = gl_thread_self ();
  47        extern gl_thread_t gl_thread_self (void);
  48
  49    Getting a reference to the current thread as a pointer, for debugging:
  50        ptr = gl_thread_self_pointer ();
  51        extern void * gl_thread_self_pointer (void);
  52
  53    Terminating the current thread:
  54        gl_thread_exit (return_value);
  55        extern _Noreturn void gl_thread_exit (void *return_value);
  56
  57    Requesting custom code to be executed at fork() time(not supported on all
  58    platforms):
  59        gl_thread_atfork (prepare_func, parent_func, child_func);
  60    Or with control of error handling:
  61        err = glthread_atfork (prepare_func, parent_func, child_func);
  62        extern int glthread_atfork (void (*prepare_func) (void),
  63                                    void (*parent_func) (void),
  64                                    void (*child_func) (void));
  65    Note that even on platforms where this is supported, use of fork() and
  66    threads together is problematic, see
  67      <http://lists.gnu.org/archive/html/bug-gnulib/2008-08/msg00062.html>
  68  */
  69
  70
  71 #ifndef _GLTHREAD_THREAD_H
  72 #define _GLTHREAD_THREAD_H
  73
  74 #include <errno.h>
  75 #include <stdlib.h>
  76
  77 _GL_INLINE_HEADER_BEGIN
  78 #ifndef _GLTHREAD_THREAD_INLINE
  79 # define _GLTHREAD_THREAD_INLINE _GL_INLINE
  80 #endif
  81
  82 /* ========================================================================= */
  83
  84 #if USE_POSIX_THREADS
  85
  86 /* Use the POSIX threads library.  */
  87
  88 # include <pthread.h>
  89
  90 # ifdef __cplusplus
  91 extern "C" {
  92 # endif
  93
  94 # if PTHREAD_IN_USE_DETECTION_HARD
  95
  96 /* The pthread_in_use() detection needs to be done at runtime.  */
  97 #  define pthread_in_use() \
  98      glthread_in_use ()
  99 extern int glthread_in_use (void);
 100
 101 # endif
 102
 103 # if USE_POSIX_THREADS_WEAK
 104
 105 /* Use weak references to the POSIX threads library.  */
 106
 107 /* Weak references avoid dragging in external libraries if the other parts
 108    of the program don't use them.  Here we use them, because we don't want
 109    every program that uses libintl to depend on libpthread.  This assumes
 110    that libpthread would not be loaded after libintl; i.e. if libintl is
 111    loaded first, by an executable that does not depend on libpthread, and
 112    then a module is dynamically loaded that depends on libpthread, libintl
 113    will not be multithread-safe.  */
 114
 115 /* The way to test at runtime whether libpthread is present is to test
 116    whether a function pointer's value, such as &pthread_mutex_init, is
 117    non-NULL.  However, some versions of GCC have a bug through which, in
 118    PIC mode, &foo != NULL always evaluates to true if there is a direct
 119    call to foo(...) in the same function.  To avoid this, we test the
 120    address of a function in libpthread that we don't use.  */
 121
 122 #  pragma weak pthread_create
 123
 124 #  ifdef __clang__
 125   /* Without this, clang complains that pthread_sigmask is never declared.  */
 126 #   include <signal.h>
 127 #  endif
 128 #  pragma weak pthread_sigmask
 129
 130 #  pragma weak pthread_join
 131 #  ifndef pthread_self
 132 #   pragma weak pthread_self
 133 #  endif
 134 #  pragma weak pthread_exit
 135 #  if HAVE_PTHREAD_ATFORK
 136 #   pragma weak pthread_atfork
 137 #  endif
 138
 139 #  if !PTHREAD_IN_USE_DETECTION_HARD
 140 #   pragma weak pthread_cancel
 141 #   define pthread_in_use() (pthread_cancel != NULL)
 142 #  endif
 143
 144 # else
 145
 146 #  if !PTHREAD_IN_USE_DETECTION_HARD
 147 #   define pthread_in_use() 1
 148 #  endif
 149
 150 # endif
 151
 152 /* -------------------------- gl_thread_t datatype -------------------------- */
 153
 154 /* This choice of gl_thread_t assumes that
 155      pthread_equal (a, b)  is equivalent to  ((a) == (b)).
 156    This is the case on all platforms in use in 2008.  */
 157 typedef pthread_t gl_thread_t;
 158 # define glthread_create(THREADP, FUNC, ARG) \
 159     (pthread_in_use () ? pthread_create (THREADP, NULL, FUNC, ARG) : ENOSYS)
 160 # define glthread_sigmask(HOW, SET, OSET) \
 161     (pthread_in_use () ? pthread_sigmask (HOW, SET, OSET) : 0)
 162 # define glthread_join(THREAD, RETVALP) \
 163     (pthread_in_use () ? pthread_join (THREAD, RETVALP) : 0)
 164 # ifdef PTW32_VERSION
 165    /* In pthreads-win32, pthread_t is a struct with a pointer field 'p' and
 166       other fields.  */
 167 #  define gl_thread_self() \
 168      (pthread_in_use () ? pthread_self () : gl_null_thread)
 169 #  define gl_thread_self_pointer() \
 170      (pthread_in_use () ? pthread_self ().p : NULL)
 171 extern const gl_thread_t gl_null_thread;
 172 # else
 173 #  define gl_thread_self() \
 174      (pthread_in_use () ? pthread_self () : (pthread_t) NULL)
 175 #  define gl_thread_self_pointer() \
 176      (pthread_in_use () ? (void *) pthread_self () : NULL)
 177 # endif
 178 # define gl_thread_exit(RETVAL) \
 179     (pthread_in_use () ? pthread_exit (RETVAL) : 0)
 180
 181 # if HAVE_PTHREAD_ATFORK
 182 #  define glthread_atfork(PREPARE_FUNC, PARENT_FUNC, CHILD_FUNC) \
 183      (pthread_in_use () ? pthread_atfork (PREPARE_FUNC, PARENT_FUNC, CHILD_FUNC) : 0)
 184 # else
 185 #  define glthread_atfork(PREPARE_FUNC, PARENT_FUNC, CHILD_FUNC) 0
 186 # endif
 187
 188 # ifdef __cplusplus
 189 }
 190 # endif
 191
 192 #endif
 193
 194 /* ========================================================================= */
 195
 196 #if USE_PTH_THREADS
 197
 198 /* Use the GNU Pth threads library.  */
 199
 200 # include <pth.h>
 201
 202 # ifdef __cplusplus
 203 extern "C" {
 204 # endif
 205
 206 # if USE_PTH_THREADS_WEAK
 207
 208 /* Use weak references to the GNU Pth threads library.  */
 209
 210 #  pragma weak pth_spawn
 211 #  pragma weak pth_sigmask
 212 #  pragma weak pth_join
 213 #  pragma weak pth_self
 214 #  pragma weak pth_exit
 215
 216 #  pragma weak pth_cancel
 217 #  define pth_in_use() (pth_cancel != NULL)
 218
 219 # else
 220
 221 #  define pth_in_use() 1
 222
 223 # endif
 224 /* -------------------------- gl_thread_t datatype -------------------------- */
 225
 226 typedef pth_t gl_thread_t;
 227 # define glthread_create(THREADP, FUNC, ARG) \
 228     (pth_in_use () ? ((*(THREADP) = pth_spawn (NULL, FUNC, ARG)) ? 0 : errno) : 0)
 229 # define glthread_sigmask(HOW, SET, OSET) \
 230     (pth_in_use () && !pth_sigmask (HOW, SET, OSET) ? errno : 0)
 231 # define glthread_join(THREAD, RETVALP) \
 232     (pth_in_use () && !pth_join (THREAD, RETVALP) ? errno : 0)
 233 # define gl_thread_self() \
 234     (pth_in_use () ? (void *) pth_self () : NULL)
 235 # define gl_thread_self_pointer() \
 236     gl_thread_self ()
 237 # define gl_thread_exit(RETVAL) \
 238     (pth_in_use () ? pth_exit (RETVAL) : 0)
 239 # define glthread_atfork(PREPARE_FUNC, PARENT_FUNC, CHILD_FUNC) 0
 240
 241 # ifdef __cplusplus
 242 }
 243 # endif
 244
 245 #endif
 246
 247 /* ========================================================================= */
 248
 249 #if USE_SOLARIS_THREADS
 250
 251 /* Use the old Solaris threads library.  */
 252
 253 # include <thread.h>
 254 # include <synch.h>
 255
 256 # ifdef __cplusplus
 257 extern "C" {
 258 # endif
 259
 260 # if USE_SOLARIS_THREADS_WEAK
 261
 262 /* Use weak references to the old Solaris threads library.  */
 263
 264 #  pragma weak thr_create
 265 #  pragma weak thr_join
 266 #  pragma weak thr_self
 267 #  pragma weak thr_exit
 268
 269 #  pragma weak thr_suspend
 270 #  define thread_in_use() (thr_suspend != NULL)
 271
 272 # else
 273
 274 #  define thread_in_use() 1
 275
 276 # endif
 277
 278 /* -------------------------- gl_thread_t datatype -------------------------- */
 279
 280 typedef thread_t gl_thread_t;
 281 # define glthread_create(THREADP, FUNC, ARG) \
 282     (thread_in_use () ? thr_create (NULL, 0, FUNC, ARG, 0, THREADP) : 0)
 283 # define glthread_sigmask(HOW, SET, OSET) \
 284     (thread_in_use () ? sigprocmask (HOW, SET, OSET) : 0)
 285 # define glthread_join(THREAD, RETVALP) \
 286     (thread_in_use () ? thr_join (THREAD, NULL, RETVALP) : 0)
 287 # define gl_thread_self() \
 288     (thread_in_use () ? (void *) thr_self () : NULL)
 289 # define gl_thread_self_pointer() \
 290     gl_thread_self ()
 291 # define gl_thread_exit(RETVAL) \
 292     (thread_in_use () ? thr_exit (RETVAL) : 0)
 293 # define glthread_atfork(PREPARE_FUNC, PARENT_FUNC, CHILD_FUNC) 0
 294
 295 # ifdef __cplusplus
 296 }
 297 # endif
 298
 299 #endif
 300
 301 /* ========================================================================= */
 302
 303 #if USE_WINDOWS_THREADS
 304
 305 # define WIN32_LEAN_AND_MEAN  /* avoid including junk */
 306 # include <windows.h>
 307
 308 # ifdef __cplusplus
 309 extern "C" {
 310 # endif
 311
 312 /* -------------------------- gl_thread_t datatype -------------------------- */
 313
 314 /* The gl_thread_t is a pointer to a structure in memory.
 315    Why not the thread handle?  If it were the thread handle, it would be hard
 316    to implement gl_thread_self() (since GetCurrentThread () returns a pseudo-
 317    handle, DuplicateHandle (GetCurrentThread ()) returns a handle that must be
 318    closed afterwards, and there is no function for quickly retrieving a thread
 319    handle from its id).
 320    Why not the thread id?  I tried it.  It did not work: Sometimes ids appeared
 321    that did not belong to running threads, and glthread_join failed with ESRCH.
 322  */
 323 typedef struct gl_thread_struct *gl_thread_t;
 324 # define glthread_create(THREADP, FUNC, ARG) \
 325     glthread_create_func (THREADP, FUNC, ARG)
 326 # define glthread_sigmask(HOW, SET, OSET) \
 327     /* unsupported */ 0
 328 # define glthread_join(THREAD, RETVALP) \
 329     glthread_join_func (THREAD, RETVALP)
 330 # define gl_thread_self() \
 331     gl_thread_self_func ()
 332 # define gl_thread_self_pointer() \
 333     gl_thread_self ()
 334 # define gl_thread_exit(RETVAL) \
 335     gl_thread_exit_func (RETVAL)
 336 # define glthread_atfork(PREPARE_FUNC, PARENT_FUNC, CHILD_FUNC) 0
 337 extern int glthread_create_func (gl_thread_t *threadp, void * (*func) (void *), void *arg);
 338 extern int glthread_join_func (gl_thread_t thread, void **retvalp);
 339 extern gl_thread_t gl_thread_self_func (void);
 340 extern int gl_thread_exit_func (void *retval);
 341
 342 # ifdef __cplusplus
 343 }
 344 # endif
 345
 346 #endif
 347
 348 /* ========================================================================= */
 349
 350 #if !(USE_POSIX_THREADS || USE_PTH_THREADS || USE_SOLARIS_THREADS || USE_WINDOWS_THREADS)
 351
 352 /* Provide dummy implementation if threads are not supported.  */
 353
 354 typedef int gl_thread_t;
 355 # define glthread_create(THREADP, FUNC, ARG) ENOSYS
 356 # define glthread_sigmask(HOW, SET, OSET) 0
 357 # define glthread_join(THREAD, RETVALP) 0
 358 # define gl_thread_self() 0
 359 # define gl_thread_self_pointer() \
 360     ((void *) gl_thread_self ())
 361 # define gl_thread_exit(RETVAL) 0
 362 # define glthread_atfork(PREPARE_FUNC, PARENT_FUNC, CHILD_FUNC) 0
 363
 364 #endif
 365
 366 /* ========================================================================= */
 367
 368 /* Macros with built-in error handling.  */
 369
 370 #ifdef __cplusplus
 371 extern "C" {
 372 #endif
 373
 374 _GLTHREAD_THREAD_INLINE gl_thread_t
 375 gl_thread_create (void *(*func) (void *arg), void *arg)
 376 {
 377   gl_thread_t thread;
 378   int ret;
 379
 380   ret = glthread_create (&thread, func, arg);
 381   if (ret != 0)
 382     abort ();
 383   return thread;
 384 }
 385 #define gl_thread_sigmask(HOW, SET, OSET)     \
 386    do                                         \
 387      {                                        \
 388        if (glthread_sigmask (HOW, SET, OSET)) \
 389          abort ();                            \
 390      }                                        \
 391    while (0)
 392 #define gl_thread_join(THREAD, RETVAL)     \
 393    do                                      \
 394      {                                     \
 395        if (glthread_join (THREAD, RETVAL)) \
 396          abort ();                         \
 397      }                                     \
 398    while (0)
 399 #define gl_thread_atfork(PREPARE, PARENT, CHILD)     \
 400    do                                                \
 401      {                                               \
 402        if (glthread_atfork (PREPARE, PARENT, CHILD)) \
 403          abort ();                                   \
 404      }                                               \
 405    while (0)
 406
 407 #ifdef __cplusplus
 408 }
 409 #endif
 410
 411 _GL_INLINE_HEADER_END
 412
 413 #endif /* _GLTHREAD_THREAD_H */