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, 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    * @param departed  points to a location that is set to the ID of the
 156    *                  terminated thread if join() returns successfully.
 157    *                  If @a departed is 0, it is ignored.
 158    * @param status    Points to the location that receives the joined
 159    *                  thread's exit value. If @a status is 0, it is ignored.
 160    *
 161    * @retval  0 for success
 162    * @retval  -1 (with errno set) for failure.
 163    */
 164   static int join (ACE_thread_t thread_id,
 165                    ACE_thread_t *departed,
 166                    ACE_THR_FUNC_RETURN *status);
 167
 168   /// Wait for one thread to exit and reap its exit status.
 169   static int join (ACE_hthread_t,
 170                    ACE_THR_FUNC_RETURN * = 0);
 171
 172   /// Continue the execution of a previously suspended thread.
 173   static int resume (ACE_hthread_t);
 174
 175   /// Suspend the execution of a particular thread.
 176   static int suspend (ACE_hthread_t);
 177
 178   /// Get the priority of a particular thread.
 179   static int getprio (ACE_hthread_t ht_id, int &priority);
 180
 181   /// Get the priority and policy of a particular thread.
 182   static int getprio (ACE_hthread_t ht_id, int &priority, int &policy);
 183
 184   /// Set the priority of a particular thread.
 185   static int setprio (ACE_hthread_t ht_id, int priority, int policy = -1);
 186
 187   /// Send a signal to the thread.
 188   static int kill (ACE_thread_t, int signum);
 189
 190   /// Yield the thread to another.
 191   static void yield ();
 192
 193   /**
 194    * Return the unique kernel handle of the thread.  Note that on
 195    * Win32 this is actually a pseudohandle, which cannot be shared
 196    * with other processes or waited on by threads.  To locate the real
 197    * handle, please use the ACE_Thread_Manager::thr_self() method.
 198    */
 199   static void self (ACE_hthread_t &t_handle);
 200
 201   /// Return the unique ID of the thread.
 202   static ACE_thread_t self ();
 203
 204   /// Exit the current thread and return "status".
 205   /// Should _not_ be called by main thread.
 206   static void exit (ACE_THR_FUNC_RETURN status = 0);
 207
 208   /// Get the LWP concurrency level of the process.
 209   static int getconcurrency ();
 210
 211   /// Set the LWP concurrency level of the process.
 212   static int setconcurrency (int new_level);
 213
 214   /// Change and/or examine calling thread's signal mask.
 215   static int sigsetmask (int how,
 216                          const sigset_t *sigset,
 217                          sigset_t *osigset = 0);
 218
 219   /**
 220    * Allocates a @a keyp that is used to identify data that is specific
 221    * to each thread in the process.  The key is global to all threads
 222    * in the process.
 223    */
 224   static int keycreate (ACE_thread_key_t *keyp,
 225 #if defined (ACE_HAS_THR_C_DEST)
 226                         ACE_THR_C_DEST destructor
 227 #else
 228                         ACE_THR_DEST destructor
 229 #endif /* ACE_HAS_THR_C_DEST */
 230                         );
 231
 232   /// Free up the key so that other threads can reuse it.
 233   static int keyfree (ACE_thread_key_t key);
 234
 235   /// Bind value to the thread-specific data key, @a key, for the calling
 236   /// thread.
 237   static int setspecific (ACE_thread_key_t key,
 238                           void *value);
 239
 240   /// Stores the current value bound to @a key for the calling thread
 241   /// into the location pointed to by @a valuep.
 242   static int getspecific (ACE_thread_key_t key,
 243                           void **valuep);
 244
 245   /// Disable thread cancellation.
 246   static int disablecancel (struct cancel_state *old_state);
 247
 248   /// Enable thread cancellation.
 249   static int enablecancel (struct cancel_state *old_state,
 250                            int flag);
 251
 252   /// Set the cancellation state.
 253   static int setcancelstate (struct cancel_state &new_state,
 254                              struct cancel_state *old_state);
 255
 256   /**
 257    * Cancel a thread.
 258    * @note This method is only portable on platforms, such as POSIX pthreads,
 259    * that support thread cancellation.
 260    */
 261   static int cancel (ACE_thread_t t_id);
 262
 263   /// Test the cancel.
 264   static void testcancel ();
 265
 266 private:
 267   /// Ensure that we don't get instantiated.
 268   ACE_Thread ();
 269 };
 270
 271 ACE_END_VERSIONED_NAMESPACE_DECL
 272
 273 #if defined (__ACE_INLINE__)
 274 #include "ace/Thread.inl"
 275 #endif /* __ACE_INLINE__ */
 276
 277 #include /**/ "ace/post.h"
 278
 279 #endif /* ACE_THREAD_H */