ACE/ace/Thread.h

   1 // -*- C++ -*-
   2
   3 //==========================================================================
   4 /**
   5  *  @file    Thread.h
   6  *
   7  *  @author Douglas Schmidt <d.schmidt@vanderbilt.edu>
   8  */
   9 //==========================================================================
  10
  11 #ifndef ACE_THREAD_H
  12 #define ACE_THREAD_H
  13
  14 #include /**/ "ace/pre.h"
  15
  16 #include /**/ "ace/ACE_export.h"
  17
  18 #if !defined (ACE_LACKS_PRAGMA_ONCE)
  19 # pragma once
  20 #endif /* ACE_LACKS_PRAGMA_ONCE */
  21
  22 #include "ace/OS_NS_Thread.h"
  23 #include "ace/Thread_Adapter.h"
  24
  25 ACE_BEGIN_VERSIONED_NAMESPACE_DECL
  26
  27 struct cancel_state
  28 {
  29   /// e.g., PTHREAD_CANCEL_ENABLE, PTHREAD_CANCEL_DISABLE,
  30   /// PTHREAD_CANCELED.
  31   int cancelstate;
  32
  33   /// e.g., PTHREAD_CANCEL_DEFERRED and PTHREAD_CANCEL_ASYNCHRONOUS.
  34   int canceltype;
  35 };
  36
  37 /**
  38  * @class ACE_Thread
  39  *
  40  * @brief Provides a wrapper for threads.
  41  *
  42  * This class provides a common interface that is mapped onto
  43  * POSIX Pthreads, Solaris threads, Win32 threads, VxWorks
  44  * threads, or pSoS threads.  Note, however, that it is
  45  * generally a better idea to use the ACE_Thread_Manager
  46  * programming API rather than the <ACE_Thread> API since the
  47  * thread manager is more powerful.
  48  */
  49 class ACE_Export ACE_Thread
  50 {
  51 public:
  52   /**
  53    * Creates a new thread having @a flags attributes and running @a func
  54    * with @a args (if @a thread_adapter is non-0 then @a func and @a args
  55    * are ignored and are obtained from @a thread_adapter>.  @a thr_id
  56    * and @a t_handle are set to the thread's ID and handle (?),
  57    * respectively.  The thread runs at @a priority priority (see
  58    * below).
  59    *
  60    * The @a flags are a bitwise-OR of the following:
  61    * = BEGIN<INDENT>
  62    * THR_CANCEL_DISABLE, THR_CANCEL_ENABLE, THR_CANCEL_DEFERRED,
  63    * THR_CANCEL_ASYNCHRONOUS, THR_BOUND, THR_NEW_LWP, THR_DETACHED,
  64    * THR_SUSPENDED, THR_DAEMON, THR_JOINABLE, THR_SCHED_FIFO,
  65    * THR_SCHED_RR, THR_SCHED_DEFAULT, THR_EXPLICIT_SCHED,
  66    * THR_SCOPE_SYSTEM, THR_SCOPE_PROCESS
  67    * = END<INDENT>
  68    *
  69    * By default, or if @a priority is set to
  70    * ACE_DEFAULT_THREAD_PRIORITY, an "appropriate" priority value for
  71    * the given scheduling policy (specified in @a flags, e.g.,
  72    * @c THR_SCHED_DEFAULT is used.  This value is calculated
  73    * dynamically, and is the median value between the minimum and
  74    * maximum priority values for the given policy.  If an explicit
  75    * value is given, it is used.  Note that actual priority values are
  76    * EXTREMELY implementation-dependent, and are probably best
  77    * avoided.
  78    *
  79    * Note that @a thread_adapter is always deleted when @a spawn
  80    * is called, so it must be allocated with global operator new.
  81    */
  82   static int spawn (ACE_THR_FUNC func,
  83                     void *arg = 0,
  84                     long flags = THR_NEW_LWP | THR_JOINABLE,
  85                     ACE_thread_t *t_id = 0,
  86                     ACE_hthread_t *t_handle = 0,
  87                     long priority = ACE_DEFAULT_THREAD_PRIORITY,
  88                     void *stack = 0,
  89                     size_t stack_size = ACE_DEFAULT_THREAD_STACKSIZE,
  90                     ACE_Thread_Adapter *thread_adapter = 0,
  91                     const char** thr_name = 0);
  92
  93   /**
  94    * Spawn N new threads, which execute @a func with argument @a arg (if
  95    * @a thread_adapter is non-0 then @a func and @a args are ignored and
  96    * are obtained from @a thread_adapter).  If @a stack != 0 it is
  97    * assumed to be an array of @a n pointers to the base of the stacks
  98    * to use for the threads being spawned.  Likewise, if @a stack_size
  99    * != 0 it is assumed to be an array of @a n values indicating how
 100    * big each of the corresponding @a stacks are.  Returns the number
 101    * of threads actually spawned (if this doesn't equal the number
 102    * requested then something has gone wrong and @c errno will
 103    * explain...).
 104    *
 105    * @see spawn()
 106    */
 107   static size_t spawn_n (size_t n,
 108                          ACE_THR_FUNC func,
 109                          void *arg = 0,
 110                          long flags = THR_NEW_LWP | THR_JOINABLE,
 111                          long priority = ACE_DEFAULT_THREAD_PRIORITY,
 112                          void *stack[] = 0,
 113                          size_t stack_size[] = 0,
 114                          ACE_Thread_Adapter *thread_adapter = 0,
 115                          const char* thr_name[] = 0);
 116
 117   /**
 118    * Spawn @a n new threads, which execute @a func with argument @a arg
 119    * (if @a thread_adapter is non-0 then @a func and @a args are ignored
 120    * and are obtained from @a thread_adapter).  The thread_ids of
 121    * successfully spawned threads will be placed into the @a thread_ids
 122    * buffer (which must be the same size as @a n).  If @a stack != 0 it
 123    * is assumed to be an array of @a n pointers to the base of the
 124    * stacks to use for the threads being spawned.  If @a stack_size !=
 125    * 0 it is assumed to be an array of @a n values indicating how big
 126    * each of the corresponding @a stacks are.  If @a thread_handles != 0
 127    * it is assumed to be an array of @a n thread_handles that will be
 128    * assigned the values of the thread handles being spawned.  Returns
 129    * the number of threads actually spawned (if this doesn't equal the
 130    * number requested then something has gone wrong and @c errno will
 131    * explain...).
 132    *
 133    * @see spawn()
 134    */
 135   static size_t spawn_n (ACE_thread_t thread_ids[],
 136                          size_t n,
 137                          ACE_THR_FUNC func,
 138                          void *arg,
 139                          long flags,
 140                          long priority = ACE_DEFAULT_THREAD_PRIORITY,
 141                          void *stack[] = 0,
 142                          size_t stack_size[] = 0,
 143                          ACE_hthread_t thread_handles[] = 0,
 144                          ACE_Thread_Adapter *thread_adapter = 0,
 145                          const char* thr_name[] = 0);
 146
 147   /**
 148    * Wait for one or more threads to exit and reap their exit status.
 149    * thr_join() returns successfully when the target thread terminates.
 150    *
 151    * @param thread_id is the ACE_thread_t ID of the thread to wait for.
 152    *                  If @a thread_id is 0, join() waits for any
 153    *                  undetached thread in the process to terminate
 154    *                  on platforms that support this capability
 155    *                  (for example, Solaris).
 156    * @param departed  points to a location that is set to the ID of the
 157    *                  terminated thread if join() returns successfully.
 158    *                  If @a departed is 0, it is ignored.
 159    * @param status    Points to the location that receives the joined
 160    *                  thread's exit value. If @a status is 0, it is ignored.
 161    *
 162    * @retval  0 for success
 163    * @retval  -1 (with errno set) for failure.
 164    */
 165   static int join (ACE_thread_t thread_id,
 166                    ACE_thread_t *departed,
 167                    ACE_THR_FUNC_RETURN *status);
 168
 169   /// Wait for one thread to exit and reap its exit status.
 170   static int join (ACE_hthread_t,
 171                    ACE_THR_FUNC_RETURN * = 0);
 172
 173   /// Continue the execution of a previously suspended thread.
 174   static int resume (ACE_hthread_t);
 175
 176   /// Suspend the execution of a particular thread.
 177   static int suspend (ACE_hthread_t);
 178
 179   /// Get the priority of a particular thread.
 180   static int getprio (ACE_hthread_t ht_id, int &priority);
 181
 182   /// Get the priority and policy of a particular thread.
 183   static int getprio (ACE_hthread_t ht_id, int &priority, int &policy);
 184
 185   /// Set the priority of a particular thread.
 186   static int setprio (ACE_hthread_t ht_id, int priority, int policy = -1);
 187
 188   /// Send a signal to the thread.
 189   static int kill (ACE_thread_t, int signum);
 190
 191   /// Yield the thread to another.
 192   static void yield (void);
 193
 194   /**
 195    * Return the unique kernel handle of the thread.  Note that on
 196    * Win32 this is actually a pseudohandle, which cannot be shared
 197    * with other processes or waited on by threads.  To locate the real
 198    * handle, please use the ACE_Thread_Manager::thr_self() method.
 199    */
 200   static void self (ACE_hthread_t &t_handle);
 201
 202   /// Return the unique ID of the thread.
 203   static ACE_thread_t self (void);
 204
 205   /// Exit the current thread and return "status".
 206   /// Should _not_ be called by main thread.
 207   static void exit (ACE_THR_FUNC_RETURN status = 0);
 208
 209   /// Get the LWP concurrency level of the process.
 210   static int getconcurrency (void);
 211
 212   /// Set the LWP concurrency level of the process.
 213   static int setconcurrency (int new_level);
 214
 215   /// Change and/or examine calling thread's signal mask.
 216   static int sigsetmask (int how,
 217                          const sigset_t *sigset,
 218                          sigset_t *osigset = 0);
 219
 220   /**
 221    * Allocates a @a keyp that is used to identify data that is specific
 222    * to each thread in the process.  The key is global to all threads
 223    * in the process.
 224    */
 225   static int keycreate (ACE_thread_key_t *keyp,
 226 #if defined (ACE_HAS_THR_C_DEST)
 227                         ACE_THR_C_DEST destructor
 228 #else
 229                         ACE_THR_DEST destructor
 230 #endif /* ACE_HAS_THR_C_DEST */
 231                         );
 232
 233   /// Free up the key so that other threads can reuse it.
 234   static int keyfree (ACE_thread_key_t key);
 235
 236   /// Bind value to the thread-specific data key, @a key, for the calling
 237   /// thread.
 238   static int setspecific (ACE_thread_key_t key,
 239                           void *value);
 240
 241   /// Stores the current value bound to @a key for the calling thread
 242   /// into the location pointed to by @a valuep.
 243   static int getspecific (ACE_thread_key_t key,
 244                           void **valuep);
 245
 246   /// Disable thread cancellation.
 247   static int disablecancel (struct cancel_state *old_state);
 248
 249   /// Enable thread cancellation.
 250   static int enablecancel (struct cancel_state *old_state,
 251                            int flag);
 252
 253   /// Set the cancellation state.
 254   static int setcancelstate (struct cancel_state &new_state,
 255                              struct cancel_state *old_state);
 256
 257   /**
 258    * Cancel a thread.
 259    * @note This method is only portable on platforms, such as POSIX pthreads,
 260    * that support thread cancellation.
 261    */
 262   static int cancel (ACE_thread_t t_id);
 263
 264   /// Test the cancel.
 265   static void testcancel (void);
 266
 267 private:
 268   /// Ensure that we don't get instantiated.
 269   ACE_Thread (void);
 270 };
 271
 272 ACE_END_VERSIONED_NAMESPACE_DECL
 273
 274 #if defined (__ACE_INLINE__)
 275 #include "ace/Thread.inl"
 276 #endif /* __ACE_INLINE__ */
 277
 278 #include /**/ "ace/post.h"
 279
 280 #endif /* ACE_THREAD_H */