00001 // Filename: thread.I 00002 // Created by: drose (08Aug02) 00003 // 00004 //////////////////////////////////////////////////////////////////// 00005 // 00006 // PANDA 3D SOFTWARE 00007 // Copyright (c) Carnegie Mellon University. All rights reserved. 00008 // 00009 // All use of this software is subject to the terms of the revised BSD 00010 // license. You should have received a copy of this license along 00011 // with this source code in a file named "LICENSE." 00012 // 00013 //////////////////////////////////////////////////////////////////// 00014 00015 00016 //////////////////////////////////////////////////////////////////// 00017 // Function: Thread::Copy Constructor 00018 // Access: Private 00019 // Description: Do not attempt to copy threads. 00020 //////////////////////////////////////////////////////////////////// 00021 INLINE Thread:: 00022 Thread(const Thread ©) : _impl(this) { 00023 nassertv(false); 00024 } 00025 00026 //////////////////////////////////////////////////////////////////// 00027 // Function: Thread::Copy Assignment Operator 00028 // Access: Private 00029 // Description: Do not attempt to copy threads. 00030 //////////////////////////////////////////////////////////////////// 00031 INLINE void Thread:: 00032 operator = (const Thread ©) { 00033 nassertv(false); 00034 } 00035 00036 //////////////////////////////////////////////////////////////////// 00037 // Function: Thread::get_sync_name 00038 // Access: Published 00039 // Description: Returns the sync name of the thread. This name 00040 // collects threads into "sync groups", which are 00041 // expected to run synchronously. This is mainly used 00042 // for the benefit of PStats; threads with the same sync 00043 // name can be ticked all at once via the thread_tick() 00044 // call. 00045 //////////////////////////////////////////////////////////////////// 00046 INLINE const string &Thread:: 00047 get_sync_name() const { 00048 return _sync_name; 00049 } 00050 00051 //////////////////////////////////////////////////////////////////// 00052 // Function: Thread::get_pstats_index 00053 // Access: Published 00054 // Description: Returns the PStats index associated with this thread, 00055 // or -1 if no index has yet been associated with this 00056 // thread. This is used internally by the PStatClient; 00057 // you should not need to call this directly. 00058 //////////////////////////////////////////////////////////////////// 00059 INLINE int Thread:: 00060 get_pstats_index() const { 00061 return _pstats_index; 00062 } 00063 00064 //////////////////////////////////////////////////////////////////// 00065 // Function: Thread::get_unique_id 00066 // Access: Published 00067 // Description: Returns a string that is guaranteed to be unique to 00068 // this thread, across all processes on the machine, 00069 // during at least the lifetime of this process. 00070 //////////////////////////////////////////////////////////////////// 00071 INLINE string Thread:: 00072 get_unique_id() const { 00073 return _impl.get_unique_id(); 00074 } 00075 00076 //////////////////////////////////////////////////////////////////// 00077 // Function: Thread::get_pipeline_stage 00078 // Access: Published 00079 // Description: Returns the Pipeline stage number associated with 00080 // this thread. The default stage is 0 if no stage is 00081 // specified otherwise. See set_pipeline_stage(). 00082 //////////////////////////////////////////////////////////////////// 00083 INLINE int Thread:: 00084 get_pipeline_stage() const { 00085 return _pipeline_stage; 00086 } 00087 00088 //////////////////////////////////////////////////////////////////// 00089 // Function: Thread::set_min_pipeline_stage 00090 // Access: Published 00091 // Description: Sets this thread's pipeline stage number to at least 00092 // the indicated value, unless it is already larger. 00093 // See set_pipeline_stage(). 00094 //////////////////////////////////////////////////////////////////// 00095 INLINE void Thread:: 00096 set_min_pipeline_stage(int min_pipeline_stage) { 00097 set_pipeline_stage(max(_pipeline_stage, min_pipeline_stage)); 00098 } 00099 00100 //////////////////////////////////////////////////////////////////// 00101 // Function: Thread::get_main_thread 00102 // Access: Published, Static 00103 // Description: Returns a pointer to the "main" Thread object--this 00104 // is the Thread that started the whole process. 00105 //////////////////////////////////////////////////////////////////// 00106 INLINE Thread *Thread:: 00107 get_main_thread() { 00108 if (_main_thread == (Thread *)NULL) { 00109 init_main_thread(); 00110 } 00111 return _main_thread; 00112 } 00113 00114 //////////////////////////////////////////////////////////////////// 00115 // Function: Thread::get_external_thread 00116 // Access: Published, Static 00117 // Description: Returns a pointer to the "external" Thread 00118 // object--this is a special Thread object that 00119 // corresponds to any thread spawned outside of Panda's 00120 // threading interface. Note that multiple different 00121 // threads may share this same pointer. 00122 //////////////////////////////////////////////////////////////////// 00123 INLINE Thread *Thread:: 00124 get_external_thread() { 00125 if (_external_thread == (Thread *)NULL) { 00126 init_external_thread(); 00127 } 00128 return _external_thread; 00129 } 00130 00131 //////////////////////////////////////////////////////////////////// 00132 // Function: Thread::get_current_thread 00133 // Access: Published, Static 00134 // Description: Returns a pointer to the currently-executing Thread 00135 // object. If this is called from the main thread, this 00136 // will return the same value as get_main_thread(). 00137 // 00138 // This will always return some valid Thread pointer. 00139 // It will never return NULL, even if the current thread 00140 // was spawned outside of Panda's threading system, 00141 // although all non-Panda threads will return the exact 00142 // same Thread pointer. 00143 //////////////////////////////////////////////////////////////////// 00144 INLINE Thread *Thread:: 00145 get_current_thread() { 00146 TAU_PROFILE("Thread *Thread::get_current_thread()", " ", TAU_USER); 00147 #ifndef HAVE_THREADS 00148 return get_main_thread(); 00149 #else // HAVE_THREADS 00150 Thread *thread = ThreadImpl::get_current_thread(); 00151 if (thread == (Thread *)NULL) { 00152 return Thread::get_external_thread(); 00153 } 00154 return thread; 00155 #endif // HAVE_THREADS 00156 } 00157 00158 //////////////////////////////////////////////////////////////////// 00159 // Function: Thread::get_current_pipeline_stage 00160 // Access: Published, Static 00161 // Description: Returns the integer pipeline stage associated with 00162 // the current thread. This is the same thing as 00163 // get_current_thread()->get_pipeline_stage(), but it 00164 // may be faster to retrieve in some contexts. 00165 //////////////////////////////////////////////////////////////////// 00166 INLINE int Thread:: 00167 get_current_pipeline_stage() { 00168 TAU_PROFILE("int Thread::get_current_pipeline_stage()", " ", TAU_USER); 00169 #ifndef THREADED_PIPELINE 00170 // Without threaded pipelining, the result is always 0. 00171 return 0; 00172 #else 00173 return get_current_thread()->get_pipeline_stage(); 00174 #endif // !THREADED_PIPELINE 00175 } 00176 00177 //////////////////////////////////////////////////////////////////// 00178 // Function: Thread::is_threading_supported 00179 // Access: Published, Static 00180 // Description: Returns true if threading support has been compiled 00181 // in and enabled, or false if no threading is available 00182 // (and Thread::start() will always fail). 00183 //////////////////////////////////////////////////////////////////// 00184 INLINE bool Thread:: 00185 is_threading_supported() { 00186 if (!support_threads) { 00187 return false; 00188 } 00189 return ThreadImpl::is_threading_supported(); 00190 } 00191 00192 //////////////////////////////////////////////////////////////////// 00193 // Function: Thread::is_true_threads 00194 // Access: Published, Static 00195 // Description: Returns true if a real threading library is available 00196 // that supports actual OS-implemented threads, or false 00197 // if the only threading we can provide is simulated 00198 // user-space threading. 00199 //////////////////////////////////////////////////////////////////// 00200 INLINE bool Thread:: 00201 is_true_threads() { 00202 if (!support_threads) { 00203 return false; 00204 } 00205 return ThreadImpl::is_true_threads(); 00206 } 00207 00208 //////////////////////////////////////////////////////////////////// 00209 // Function: Thread::is_simple_threads 00210 // Access: Published, Static 00211 // Description: Returns true if Panda is currently compiled for 00212 // "simple threads", which is to say, cooperative 00213 // context switching only, reducing the need for quite 00214 // so many critical section protections. This is not 00215 // necessarily the opposite of "true threads", since one 00216 // possible implementation of simple threads is via true 00217 // threads with mutex protection to ensure only one runs 00218 // at a time. 00219 //////////////////////////////////////////////////////////////////// 00220 INLINE bool Thread:: 00221 is_simple_threads() { 00222 if (!support_threads) { 00223 return false; 00224 } 00225 return ThreadImpl::is_simple_threads(); 00226 } 00227 00228 //////////////////////////////////////////////////////////////////// 00229 // Function: Thread::sleep 00230 // Access: Published, Static 00231 // Description: Suspends the current thread for at least the 00232 // indicated amount of time. It might be suspended for 00233 // longer. 00234 //////////////////////////////////////////////////////////////////// 00235 INLINE void Thread:: 00236 sleep(double seconds) { 00237 TAU_PROFILE("void Thread::sleep(double)", " ", TAU_USER); 00238 ThreadImpl::sleep(seconds); 00239 } 00240 00241 //////////////////////////////////////////////////////////////////// 00242 // Function: Thread::field_yield 00243 // Access: Published, Static 00244 // Description: Suspends the current thread for the rest of the 00245 // current epoch. 00246 //////////////////////////////////////////////////////////////////// 00247 INLINE void Thread:: 00248 force_yield() { 00249 TAU_PROFILE("void Thread::yield()", " ", TAU_USER); 00250 ThreadImpl::yield(); 00251 } 00252 00253 //////////////////////////////////////////////////////////////////// 00254 // Function: Thread::consider_yield 00255 // Access: Published, Static 00256 // Description: Possibly suspends the current thread for the rest of 00257 // the current epoch, if it has run for enough this 00258 // epoch. This is especially important for the simple 00259 // thread implementation, which relies on cooperative 00260 // yields like this. 00261 //////////////////////////////////////////////////////////////////// 00262 INLINE void Thread:: 00263 consider_yield() { 00264 TAU_PROFILE("void Thread::consider_yield()", " ", TAU_USER); 00265 ThreadImpl::consider_yield(); 00266 } 00267 00268 //////////////////////////////////////////////////////////////////// 00269 // Function: Thread::is_started 00270 // Access: Published 00271 // Description: Returns true if the thread has been started, false if 00272 // it has not, or if join() has already been called. 00273 //////////////////////////////////////////////////////////////////// 00274 INLINE bool Thread:: 00275 is_started() const { 00276 return _started; 00277 } 00278 00279 //////////////////////////////////////////////////////////////////// 00280 // Function: Thread::is_joinable 00281 // Access: Published 00282 // Description: Returns the value of joinable that was passed to the 00283 // start() call. 00284 //////////////////////////////////////////////////////////////////// 00285 INLINE bool Thread:: 00286 is_joinable() const { 00287 return _joinable; 00288 } 00289 00290 //////////////////////////////////////////////////////////////////// 00291 // Function: Thread::join 00292 // Access: Published 00293 // Description: Blocks the calling process until the thread 00294 // terminates. If the thread has already terminated, 00295 // this returns immediately. 00296 //////////////////////////////////////////////////////////////////// 00297 INLINE void Thread:: 00298 join() { 00299 TAU_PROFILE("void Thread::join()", " ", TAU_USER); 00300 if (_started) { 00301 _impl.join(); 00302 _started = false; 00303 } 00304 } 00305 00306 //////////////////////////////////////////////////////////////////// 00307 // Function: Thread::preempt 00308 // Access: Published 00309 // Description: Indicates that this thread should run as soon as 00310 // possible, preemptying any other threads that may be 00311 // scheduled to run. This may not be implemented on 00312 // every platform. 00313 //////////////////////////////////////////////////////////////////// 00314 INLINE void Thread:: 00315 preempt() { 00316 if (_started) { 00317 _impl.preempt(); 00318 } 00319 } 00320 00321 //////////////////////////////////////////////////////////////////// 00322 // Function: Thread::get_current_task 00323 // Access: Published 00324 // Description: Returns the task currently executing on this thread 00325 // (via the AsyncTaskManager), if any, or NULL if the 00326 // thread is not currently servicing a task. 00327 //////////////////////////////////////////////////////////////////// 00328 INLINE AsyncTaskBase *Thread:: 00329 get_current_task() const { 00330 return _current_task; 00331 } 00332 00333 //////////////////////////////////////////////////////////////////// 00334 // Function: Thread::prepare_for_exit 00335 // Access: Published 00336 // Description: Should be called by the main thread just before 00337 // exiting the program, this blocks until any remaining 00338 // thread cleanup has finished. 00339 //////////////////////////////////////////////////////////////////// 00340 INLINE void Thread:: 00341 prepare_for_exit() { 00342 ThreadImpl::prepare_for_exit(); 00343 } 00344 00345 //////////////////////////////////////////////////////////////////// 00346 // Function: Thread::set_pstats_index 00347 // Access: Public 00348 // Description: Stores a PStats index to be associated with this 00349 // thread. This is used internally by the PStatClient; 00350 // you should not need to call this directly. 00351 //////////////////////////////////////////////////////////////////// 00352 INLINE void Thread:: 00353 set_pstats_index(int pstats_index) { 00354 _pstats_index = pstats_index; 00355 } 00356 00357 //////////////////////////////////////////////////////////////////// 00358 // Function: Thread::set_pstats_callback 00359 // Access: Public 00360 // Description: Stores a PStats callback to be associated with this 00361 // thread. This is used internally by the PStatClient; 00362 // you should not need to call this directly. 00363 //////////////////////////////////////////////////////////////////// 00364 INLINE void Thread:: 00365 set_pstats_callback(Thread::PStatsCallback *pstats_callback) { 00366 _pstats_callback = pstats_callback; 00367 } 00368 00369 //////////////////////////////////////////////////////////////////// 00370 // Function: Thread::get_pstats_callback 00371 // Access: Public 00372 // Description: Returns the PStats callback associated with this thread, 00373 // or NULL if no callback has yet been associated with 00374 // this thread. This is used internally by the 00375 // PStatClient; you should not need to call this 00376 // directly. 00377 //////////////////////////////////////////////////////////////////// 00378 INLINE Thread::PStatsCallback *Thread:: 00379 get_pstats_callback() const { 00380 return _pstats_callback; 00381 } 00382 00383 INLINE ostream & 00384 operator << (ostream &out, const Thread &thread) { 00385 thread.output(out); 00386 return out; 00387 }