Panda3D
 All Classes Functions Variables Enumerations
thread.I
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 &copy) : _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 &copy) {
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 }
 All Classes Functions Variables Enumerations