00001 /* 00002 * Thread.hpp 00003 * 00004 * Copyright (c) 2000, 2014, 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 state_initial = 0, // the thread has not yet started 00052 state_runnable = 1, // the thread has started 00053 state_interrupted = 2, // the thread has been interrupted 00054 state_terminated = 3 // the thread has completed execution 00055 } State; 00056 00057 00058 // ----- Maintenance definition ------------------------------------------ 00059 00060 protected: 00061 /** 00062 * Defines various thread maintenance tasks. 00063 */ 00064 typedef enum 00065 { 00066 none = 0, 00067 collect_stack = 1, 00068 compact_tls = 2 00069 } Maintenance; 00070 00071 00072 // ----- constructors --------------------------------------------------- 00073 00074 private: 00075 /** 00076 * Create a Thread. 00077 * 00078 * @param hRunnable the Runnable to execute 00079 * @param vsName the thread's name, or NULL for default 00080 * @param hGroup the thread's group, or NULL for parent's 00081 * @param cBytesStack the stack size, or 0 for default 00082 * 00083 * @return the handle to the new Thread 00084 */ 00085 Thread(Runnable::Handle hRunnable, 00086 String::View vsName = String::null_string, 00087 ThreadGroup::Handle hGroup = NULL, 00088 size32_t cBytesStack = 0); 00089 00090 00091 // ----- Runnable interface --------------------------------------------- 00092 00093 public: 00094 /** 00095 * {@inheritDoc} 00096 */ 00097 virtual void run(); 00098 00099 00100 // ----- Thread interface ----------------------------------------------- 00101 00102 public: 00103 /** 00104 * Return the Thread's unique ID. 00105 * 00106 * No two live thread's will have the same ID and no thread will have 00107 * an id of 0. 00108 * 00109 * @return the Thread's unique ID. 00110 */ 00111 virtual int64_t getId() const; 00112 00113 /** 00114 * Return the Thread's current state. 00115 * 00116 * @return the Thread's current state 00117 */ 00118 virtual State getState() const; 00119 00120 /** 00121 * Return the Thread's name. 00122 * 00123 * @return the Thread's name 00124 */ 00125 virtual String::View getName() const; 00126 00127 /** 00128 * Return this thread's group, or NULL if the thread has terminated. 00129 * 00130 * @return this thread's group 00131 */ 00132 virtual ThreadGroup::Handle getThreadGroup(); 00133 00134 /** 00135 * Return this thread's group, or NULL if the thread has terminated. 00136 * 00137 * @return this thread's group 00138 */ 00139 virtual ThreadGroup::View getThreadGroup() const; 00140 00141 /** 00142 * Begin executing the Thread's runnable on a new system thread. 00143 * 00144 * This method may only be called once per Thread instance. 00145 * 00146 * @throw IllegalStateException if a called on a Thread which is not 00147 * in the state state_initial. 00148 */ 00149 virtual void start(); 00150 00151 /** 00152 * Request that the Thread stop executing. 00153 */ 00154 virtual void interrupt(); 00155 00156 /** 00157 * Return true iff the thread is interrupted. 00158 * 00159 * @return true iff the thread is interrupted 00160 */ 00161 virtual bool isInterrupted() const; 00162 00163 /** 00164 * Wait for the Thread to reach the state_terminated state. 00165 */ 00166 virtual void join() const; 00167 00168 /** 00169 * Wait for the Thread to reach the state_terminated state. 00170 * 00171 * @param cMillis the maximum duration to wait, or zero for infinite 00172 */ 00173 virtual void join(int64_t cMillis) const; 00174 00175 /** 00176 * Set the Thread's name. 00177 * 00178 * @param vsName the Thread's name 00179 */ 00180 virtual void setName(String::View vsName); 00181 00182 protected: 00183 /** 00184 * Called automatically on the thread prior to termination. 00185 * 00186 * Any class extending this Thread and overriding this method much 00187 * call this implementation to ensure that join() operations complete. 00188 */ 00189 virtual void onExit(); 00190 00191 /** 00192 * Instruct the thread to perform maintenance. 00193 */ 00194 virtual void scheduleMaintenance(Maintenance nMaintenance) const; 00195 00196 00197 // ----- static helper methods ------------------------------------------ 00198 00199 public: 00200 /** 00201 * Return the Thread on which the caller is executing. 00202 * 00203 * @return the caller's thread 00204 */ 00205 static Thread::Handle currentThread(); 00206 00207 /** 00208 * Return a stack trace for this thread. 00209 * 00210 * @param cTrim the number of frames to trim from the top of the stack 00211 * 00212 * @return an array of StackTraceElements describing as much of the 00213 * thread's stack as can be determined 00214 */ 00215 static ObjectArray::Handle getStackTrace(size32_t cTrim = 0); 00216 00217 /** 00218 * Output a stack trace to the supplied stream. 00219 * 00220 * @param out the stream to output to 00221 * @param vaStack the array of StackTraceElements to output, or NULL 00222 * for the stack of the current thread 00223 */ 00224 static void outputStackTrace(std::ostream& out, 00225 ObjectArray::View vaStack = NULL); 00226 00227 /** 00228 * Output the stack trace of all known threads to the specified stream. 00229 * 00230 * This is a blocking operation, while the calling thread waits for 00231 * all known threads to report their stack. 00232 * 00233 * Note: This operation can also be manually triggered by sending a 00234 * SIGQUIT signal to the process. This can be done via CTRL+/ on UNIX 00235 * and CTRL+BREAK on Windows. 00236 * 00237 * @param out the stream to output to 00238 * @param cMillisTimeout the maximum amount of time to wait for all 00239 * threads to report their stacks, or -1 for 00240 * the system default of twice the interrupt 00241 * resolution 00242 */ 00243 static void dumpStacks(std::ostream& out, int64_t cMillisTimeout = -1); 00244 00245 /** 00246 * Return true iff the caller's thread has been interrupted. 00247 * 00248 * The thread's interrupt state is reset as part of this operation. 00249 * 00250 * @return true iff the caller's thread has been interrupted 00251 */ 00252 static bool interrupted(); 00253 00254 /** 00255 * Pause the current thread for the specified duration. 00256 * 00257 * @param cMillis the duration to pause the thread for. 00258 * 00259 * @throw InterruptedException if the thread is interrupted while 00260 * sleeping. 00261 */ 00262 static void sleep(int64_t cMillis); 00263 00264 /** 00265 * Temporarily pause the current thread. 00266 */ 00267 static void yield(); 00268 00269 protected: 00270 /** 00271 * Instruct all threads to perform maintenance. 00272 */ 00273 static void doGlobalMaintenance(Maintenance nMaintenance); 00274 00275 00276 // ----- Object interface ----------------------------------------------- 00277 00278 public: 00279 /** 00280 * {@inheritDoc} 00281 * 00282 * If the associated Runnable implements the 00283 * coherence::util::Describable interface that content will be included 00284 * as well. 00285 */ 00286 virtual void toStream(std::ostream &out) const; 00287 00288 00289 // ----- data members --------------------------------------------------- 00290 00291 protected: 00292 /** 00293 * The thread's group. 00294 */ 00295 MemberHandle<ThreadGroup> m_hGroup; 00296 00297 /** 00298 * The inner runnable associated with this Thread. 00299 */ 00300 MemberHandle<Runnable> m_hRunnable; 00301 00302 /** 00303 * The thread's name. 00304 */ 00305 MemberView<String> m_vsName; 00306 00307 /** 00308 * The thread's description. 00309 */ 00310 FinalView<String> f_vsDescription; 00311 00312 /** 00313 * The configured stack size; 00314 */ 00315 size32_t m_cBytesStack; 00316 00317 /** 00318 * The current thread state. 00319 */ 00320 Volatile<int32_t> m_nState; 00321 00322 /** 00323 * Bit mask identifying required maintenance tasks. 00324 */ 00325 mutable int m_nMaintenanceMask; 00326 00327 00328 // ----- friends -------------------------------------------------------- 00329 00330 friend void coh_thread_cleanup(Thread*); 00331 friend Thread* coh_thread_current(); 00332 friend class System; 00333 }; 00334 00335 COH_CLOSE_NAMESPACE2 00336 00337 #endif // COH_THREAD_HPP