Main Page   Class Hierarchy   Alphabetical List   Compound List   File List   Compound Members   File Members   Related Pages  

Thread.h

Go to the documentation of this file.
00001 // -*- C++ -*-
00002 
00003 //==========================================================================
00004 /**
00005  *  @file    Thread.h
00006  *
00007  *  $Id: Thread.h,v 1.1.1.4.2.1 2003/05/19 16:25:44 chad Exp $
00008  *
00009  *  @author Douglas Schmidt <schmidt@cs.wustl.edu>
00010  */
00011 //==========================================================================
00012 
00013 #ifndef ACE_THREAD_H
00014 #define ACE_THREAD_H
00015 
00016 #include "ace/pre.h"
00017 
00018 #include "ace/ACE_export.h"
00019 
00020 #if !defined (ACE_LACKS_PRAGMA_ONCE)
00021 # pragma once
00022 #endif /* ACE_LACKS_PRAGMA_ONCE */
00023 
00024 #include "ace/OS.h"
00025 #include "ace/Thread_Adapter.h"
00026 
00027 /**
00028  * @class ACE_Thread
00029  *
00030  * @brief Provides a wrapper for threads.
00031  *
00032  * This class provides a common interface that is mapped onto
00033  * POSIX Pthreads, Solaris threads, Win32 threads, VxWorks
00034  * threads, or pSoS threads.  Note, however, that it is
00035  * generally a better idea to use the <ACE_Thread_Manager>
00036  * programming API rather than the <ACE_Thread> API since the
00037  * thread manager is more powerful.
00038  */
00039 class ACE_Export ACE_Thread
00040 {
00041 public:
00042   /**
00043    * Creates a new thread having <flags> attributes and running <func>
00044    * with <args> (if <thread_adapter> is non-0 then <func> and <args>
00045    * are ignored and are obtained from <thread_adapter>).  <thr_id>
00046    * and <t_handle> are set to the thread's ID and handle (?),
00047    * respectively.  The thread runs at <priority> priority (see
00048    * below).
00049    *
00050    * The <flags> are a bitwise-OR of the following:
00051    * = BEGIN<INDENT>
00052    * THR_CANCEL_DISABLE, THR_CANCEL_ENABLE, THR_CANCEL_DEFERRED,
00053    * THR_CANCEL_ASYNCHRONOUS, THR_BOUND, THR_NEW_LWP, THR_DETACHED,
00054    * THR_SUSPENDED, THR_DAEMON, THR_JOINABLE, THR_SCHED_FIFO,
00055    * THR_SCHED_RR, THR_SCHED_DEFAULT, THR_EXPLICIT_SCHED,
00056    * THR_SCOPE_SYSTEM, THR_SCOPE_PROCESS
00057    * = END<INDENT>
00058    *
00059    * By default, or if <priority> is set to
00060    * ACE_DEFAULT_THREAD_PRIORITY, an "appropriate" priority value for
00061    * the given scheduling policy (specified in <flags}>, e.g.,
00062    * <THR_SCHED_DEFAULT>) is used.  This value is calculated
00063    * dynamically, and is the median value between the minimum and
00064    * maximum priority values for the given policy.  If an explicit
00065    * value is given, it is used.  Note that actual priority values are
00066    * EXTREMEMLY implementation-dependent, and are probably best
00067    * avoided.
00068    *
00069    * Note that <thread_adapter> is always deleted when <spawn>
00070    * is called, so it must be allocated with global operator new.
00071    */
00072   static int spawn (ACE_THR_FUNC func,
00073                     void *arg = 0,
00074                     long flags = THR_NEW_LWP | THR_JOINABLE,
00075                     ACE_thread_t *t_id = 0,
00076                     ACE_hthread_t *t_handle = 0,
00077                     long priority = ACE_DEFAULT_THREAD_PRIORITY,
00078                     void *stack = 0,
00079                     size_t stack_size = 0,
00080                     ACE_Thread_Adapter *thread_adapter = 0);
00081 
00082   /**
00083    * Spawn N new threads, which execute <func> with argument <arg> (if
00084    * <thread_adapter> is non-0 then <func> and <args> are ignored and
00085    * are obtained from <thread_adapter>).  If <stack> != 0 it is
00086    * assumed to be an array of <n> pointers to the base of the stacks
00087    * to use for the threads being spawned.  Likewise, if <stack_size>
00088    * != 0 it is assumed to be an array of <n> values indicating how
00089    * big each of the corresponding <stack>s are.  Returns the number
00090    * of threads actually spawned (if this doesn't equal the number
00091    * requested then something has gone wrong and <errno> will
00092    * explain...).
00093    *
00094    * @see spawn()
00095    */
00096   static size_t spawn_n (size_t n,
00097                          ACE_THR_FUNC func,
00098                          void *arg = 0,
00099                          long flags = THR_NEW_LWP | THR_JOINABLE,
00100                          long priority = ACE_DEFAULT_THREAD_PRIORITY,
00101                          void *stack[] = 0,
00102                          size_t stack_size[] = 0,
00103                          ACE_Thread_Adapter *thread_adapter = 0);
00104 
00105   /**
00106    * Spawn <n> new threads, which execute <func> with argument <arg>
00107    * (if <thread_adapter> is non-0 then <func> and <args> are ignored
00108    * and are obtained from <thread_adapter>).  The thread_ids of
00109    * successfully spawned threads will be placed into the <thread_ids>
00110    * buffer (which must be the same size as <n>).  If <stack> != 0 it
00111    * is assumed to be an array of <n> pointers to the base of the
00112    * stacks to use for the threads being spawned.  If <stack_size> !=
00113    * 0 it is assumed to be an array of <n> values indicating how big
00114    * each of the corresponding <stack>s are.  If <thread_handles> != 0
00115    * it is assumed to be an array of <n> thread_handles that will be
00116    * assigned the values of the thread handles being spawned.  Returns
00117    * the number of threads actually spawned (if this doesn't equal the
00118    * number requested then something has gone wrong and <errno> will
00119    * explain...).
00120    *
00121    * @see spawn()
00122    */
00123   static size_t spawn_n (ACE_thread_t thread_ids[],
00124                          size_t n,
00125                          ACE_THR_FUNC func,
00126                          void *arg,
00127                          long flags,
00128                          long priority = ACE_DEFAULT_THREAD_PRIORITY,
00129                          void *stack[] = 0,
00130                          size_t stack_size[] = 0,
00131                          ACE_hthread_t thread_handles[] = 0,
00132                          ACE_Thread_Adapter *thread_adapter = 0);
00133 
00134   /// Wait for one or more threads to exit and reap their exit status.
00135   static int join (ACE_thread_t,
00136                    ACE_thread_t *,
00137                    ACE_THR_FUNC_RETURN *status);
00138 
00139   /// Wait for one thread to exit and reap its exit status.
00140   static int join (ACE_hthread_t,
00141                    ACE_THR_FUNC_RETURN * = 0);
00142 
00143   /// Continue the execution of a previously suspended thread.
00144   static int resume (ACE_hthread_t);
00145 
00146   /// Suspend the execution of a particular thread.
00147   static int suspend (ACE_hthread_t);
00148 
00149   /// Get the priority of a particular thread.
00150   static int getprio (ACE_hthread_t id, int &priority);
00151 
00152   /// Get the priority and policy of a particular thread.
00153   static int getprio (ACE_hthread_t id, int &priority, int &policy);
00154 
00155   /// Set the priority of a particular thread.
00156   static int setprio (ACE_hthread_t id, int priority, int policy = -1);
00157 
00158   /// Send a signal to the thread.
00159   static int kill (ACE_thread_t, int signum);
00160 
00161   /// Yield the thread to another.
00162   static void yield (void);
00163 
00164   /**
00165    * Return the unique kernel handle of the thread.  Note that on
00166    * Win32 this is actually a pseudohandle, which cannot be shared
00167    * with other processes or waited on by threads.  To locate the real
00168    * handle, please use the <ACE_Thread_Manager::thr_self> method.
00169    */
00170   static void self (ACE_hthread_t &t_handle);
00171 
00172   /// Return the unique ID of the thread.
00173   static ACE_thread_t self (void);
00174 
00175   /// Exit the current thread and return "status".
00176   /// Should _not_ be called by main thread.
00177   static void exit (ACE_THR_FUNC_RETURN status = 0);
00178 
00179   /// Get the LWP concurrency level of the process.
00180   static int getconcurrency (void);
00181 
00182   /// Set the LWP concurrency level of the process.
00183   static int setconcurrency (int new_level);
00184 
00185   /// Change and/or examine calling thread's signal mask.
00186   static int sigsetmask (int how,
00187                          const sigset_t *sigset,
00188                          sigset_t *osigset = 0);
00189 
00190   static int keycreate (ACE_thread_key_t *keyp,
00191 #if defined (ACE_HAS_THR_C_DEST)
00192                         ACE_THR_C_DEST destructor,
00193 #else
00194                         ACE_THR_DEST destructor,
00195 #endif /* ACE_HAS_THR_C_DEST */
00196   /**
00197    * Allocates a <keyp> that is used to identify data that is specific
00198    * to each thread in the process.  The key is global to all threads
00199    * in the process.
00200    */
00201                         void * = 0);
00202 
00203   /// Free up the key so that other threads can reuse it.
00204   static int keyfree (ACE_thread_key_t key);
00205 
00206   /// Bind value to the thread-specific data key, <key>, for the calling
00207   /// thread.
00208   static int setspecific (ACE_thread_key_t key,
00209                           void *value);
00210 
00211   /// Stores the current value bound to <key> for the calling thread
00212   /// into the location pointed to by <valuep>.
00213   static int getspecific (ACE_thread_key_t key,
00214                           void **valuep);
00215 
00216   /// Disable thread cancellation.
00217   static int disablecancel (struct cancel_state *old_state);
00218 
00219   /// Enable thread cancellation.
00220   static int enablecancel (struct cancel_state *old_state,
00221                            int flag);
00222 
00223   /// Set the cancellation state.
00224   static int setcancelstate (struct cancel_state &new_state,
00225                              struct cancel_state *old_state);
00226 
00227   /**
00228    * Cancel a thread.  Note that this method is only portable on
00229    * platforms, such as POSIX pthreads, that support thread
00230    * cancellation.
00231    */
00232   static int cancel (ACE_thread_t t_id);
00233 
00234   /// Test the cancel.
00235   static void testcancel (void);
00236 
00237 private:
00238   /// Ensure that we don't get instantiated.
00239   ACE_Thread (void);
00240 };
00241 
00242 #if defined (__ACE_INLINE__)
00243 #include "ace/Thread.i"
00244 #endif /* __ACE_INLINE__ */
00245 
00246 #include "ace/post.h"
00247 
00248 #endif /* ACE_THREAD_H */

Generated on Mon Jun 16 11:21:45 2003 for ACE by doxygen1.2.14 written by Dimitri van Heesch, © 1997-2002