00001 /* 00002 * Thread.hpp 00003 * 00004 * Copyright (c) 2000, 2010, Oracle and/or its affiliates. All rights reserved. 00005 * 00006 * Oracle is a registered trademarks of Oracle Corporation and/or its 00007 * affiliates. 00008 * 00009 * This software is the confidential and proprietary information of Oracle 00010 * Corporation. You shall not disclose such confidential and proprietary 00011 * information and shall use it only in accordance with the terms of the 00012 * license agreement you entered into with Oracle. 00013 * 00014 * This notice may not be removed or altered. 00015 */ 00016 #ifndef COH_THREAD_HPP 00017 #define COH_THREAD_HPP 00018 00019 #include "coherence/lang/compatibility.hpp" 00020 00021 #include "coherence/lang/FinalHandle.hpp" 00022 #include "coherence/lang/FinalView.hpp" 00023 #include "coherence/lang/Object.hpp" 00024 #include "coherence/lang/ObjectArray.hpp" 00025 #include "coherence/lang/MemberView.hpp" 00026 #include "coherence/lang/Runnable.hpp" 00027 #include "coherence/lang/String.hpp" 00028 #include "coherence/lang/ThreadGroup.hpp" 00029 #include "coherence/lang/TypedHandle.hpp" 00030 #include "coherence/lang/Volatile.hpp" 00031 00032 COH_OPEN_NAMESPACE2(coherence,lang) 00033 00034 /** 00035 * An Object representing a thread of execution. 00036 * 00037 * @author mf 2007.12.10 00038 */ 00039 class COH_EXPORT Thread 00040 : public class_spec<Thread, 00041 extends<Object>, 00042 implements<Runnable> > 00043 { 00044 friend class factory<Thread>; 00045 00046 // ----- State definition ----------------------------------------------- 00047 00048 public: 00049 typedef enum 00050 { 00051 NEW = 0, // the thread has not yet started 00052 RUNNABLE = 1, // the thread has started 00053 INTERRUPTED = 2, // the thread has been interrupted 00054 TERMINATED = 3 // the thread has completed execution 00055 } State; 00056 00057 00058 // ----- constructors --------------------------------------------------- 00059 00060 private: 00061 /** 00062 * Create a Thread. 00063 * 00064 * @param hRunnable the Runnable to execute 00065 * @param vsName the thread's name, or NULL for default 00066 * @param hGroup the thread's group, or NULL for parent's 00067 * @param cBytesStack the stack size, or 0 for default 00068 * 00069 * @return the handle to the new Thread 00070 */ 00071 Thread(Runnable::Handle hRunnable, 00072 String::View vsName = String::NULL_STRING, 00073 ThreadGroup::Handle hGroup = NULL, 00074 size32_t cBytesStack = 0); 00075 00076 00077 // ----- Runnable interface --------------------------------------------- 00078 00079 public: 00080 /** 00081 * {@inheritDoc} 00082 */ 00083 virtual void run(); 00084 00085 00086 // ----- Thread interface ----------------------------------------------- 00087 00088 public: 00089 /** 00090 * Return the Thread's unique ID. 00091 * 00092 * No two live thread's will have the same ID and no thread will have 00093 * an id of 0. 00094 * 00095 * @return the Thread's unique ID. 00096 */ 00097 virtual int64_t getId() const; 00098 00099 /** 00100 * Return the Thread's current state. 00101 * 00102 * @return the Thread's current state 00103 */ 00104 virtual State getState() const; 00105 00106 /** 00107 * Return the Thread's name. 00108 * 00109 * @return the Thread's name 00110 */ 00111 virtual String::View getName() const; 00112 00113 /** 00114 * Return this thread's group, or NULL if the thread has terminated. 00115 * 00116 * @return this thread's group 00117 */ 00118 virtual ThreadGroup::Handle getThreadGroup(); 00119 00120 /** 00121 * Return this thread's group, or NULL if the thread has terminated. 00122 * 00123 * @return this thread's group 00124 */ 00125 virtual ThreadGroup::View getThreadGroup() const; 00126 00127 /** 00128 * Begin executing the Thread's runnable on a new system thread. 00129 * 00130 * This method may only be called once per Thread instance. 00131 * 00132 * @throw IllegalStateException if a called on a Thread which is not 00133 * in the state NEW. 00134 */ 00135 virtual void start(); 00136 00137 /** 00138 * Request that the Thread stop executing. 00139 */ 00140 virtual void interrupt(); 00141 00142 /** 00143 * Return true iff the thread is interrupted. 00144 * 00145 * @return true iff the thread is interrupted 00146 */ 00147 virtual bool isInterrupted() const; 00148 00149 /** 00150 * Wait for the Thread to reach the TERMINATED state. 00151 */ 00152 virtual void join() const; 00153 00154 /** 00155 * Wait for the Thread to reach the TERMINATED state. 00156 * 00157 * @param cMillis the maximum duration to wait, or zero for infinite 00158 */ 00159 virtual void join(int64_t cMillis) const; 00160 00161 /** 00162 * Set the Thread's name. 00163 * 00164 * @param vsName the Thread's name 00165 */ 00166 virtual void setName(String::View vsName); 00167 00168 protected: 00169 /** 00170 * Called automatically on the thread prior to termination. 00171 * 00172 * Any class extending this Thread and overriding this method much 00173 * call this implementation to ensure that join() operations complete. 00174 */ 00175 virtual void onExit(); 00176 00177 /** 00178 * Instruct the thread to collect its stack. 00179 */ 00180 virtual void collectStackTrace() const; 00181 00182 00183 // ----- static helper methods ------------------------------------------ 00184 00185 public: 00186 /** 00187 * Return the Thread on which the caller is executing. 00188 * 00189 * @return the caller's thread 00190 */ 00191 static Thread::Handle currentThread(); 00192 00193 /** 00194 * Return a stack trace for this thread. 00195 * 00196 * @param cTrim the number of frames to trim from the top of the stack 00197 * 00198 * @return an array of StackTraceElements describing as much of the 00199 * thread's stack as can be determined 00200 */ 00201 static ObjectArray::Handle getStackTrace(size32_t cTrim = 0); 00202 00203 /** 00204 * Output a stack trace to the supplied stream. 00205 * 00206 * @param out the stream to output to 00207 * @param vaStack the array of StackTraceElements to output, or NULL 00208 * for the stack of the current thread 00209 */ 00210 static void outputStackTrace(std::ostream& out, 00211 ObjectArray::View vaStack = NULL); 00212 00213 /** 00214 * Output the stack trace of all known threads to the specified stream. 00215 * 00216 * This is a blocking operation, while the calling thread waits for 00217 * all known threads to report their stack. 00218 * 00219 * Note: This operation can also be manually triggered by sending a 00220 * SIGQUIT signal to the process. This can be done via CTRL+/ on UNIX 00221 * and CTRL+BREAK on Windows. 00222 * 00223 * @param out the stream to output to 00224 * @param cMillisTimeout the maximum amount of time to wait for all 00225 * threads to report their stacks, or -1 for 00226 * the system default of twice the interrupt 00227 * resolution 00228 */ 00229 static void dumpStacks(std::ostream& out, int64_t cMillisTimeout = -1); 00230 00231 /** 00232 * Return true iff the caller's thread has been interrupted. 00233 * 00234 * The thread's interrupt state is reset as part of this operation. 00235 * 00236 * @return true iff the caller's thread has been interrupted 00237 */ 00238 static bool interrupted(); 00239 00240 /** 00241 * Pause the current thread for the specified duration. 00242 * 00243 * @param cMillis the duration to pause the thread for. 00244 * 00245 * @throw InterruptedException if the thread is interrupted while 00246 * sleeping. 00247 */ 00248 static void sleep(int64_t cMillis); 00249 00250 /** 00251 * Temporarily pause the current thread. 00252 */ 00253 static void yield(); 00254 00255 00256 // ----- Object interface ----------------------------------------------- 00257 00258 public: 00259 /** 00260 * {@inheritDoc} 00261 * 00262 * If the associated Runnable implements the 00263 * coherence::util::Describable interface that content will be included 00264 * as well. 00265 */ 00266 virtual void toStream(std::ostream &out) const; 00267 00268 00269 // ----- data members --------------------------------------------------- 00270 00271 protected: 00272 /** 00273 * The thread's group. 00274 */ 00275 MemberHandle<ThreadGroup> m_hGroup; 00276 00277 /** 00278 * The inner runnable associated with this Thread. 00279 */ 00280 MemberHandle<Runnable> m_hRunnable; 00281 00282 /** 00283 * The thread's name. 00284 */ 00285 MemberView<String> m_vsName; 00286 00287 /** 00288 * The thread's description. 00289 */ 00290 FinalView<String> m_vsDescription; 00291 00292 /** 00293 * The configured stack size; 00294 */ 00295 size32_t m_cBytesStack; 00296 00297 /** 00298 * The current thread state. 00299 */ 00300 Volatile<int32_t> m_nState; 00301 00302 /** 00303 * True if a request has been made for a stack dump. 00304 */ 00305 mutable bool m_fCollectStack; 00306 00307 00308 // ----- friends -------------------------------------------------------- 00309 00310 friend void coh_thread_cleanup(Thread*); 00311 friend Thread* coh_thread_current(); 00312 }; 00313 00314 COH_CLOSE_NAMESPACE2 00315 00316 #endif // COH_THREAD_HPP