00001 /* 00002 * thread.h 00003 * 00004 * Executable thread encapsulation class (pre-emptive if OS allows). 00005 * 00006 * Portable Windows Library 00007 * 00008 * Copyright (c) 1993-1998 Equivalence Pty. Ltd. 00009 * 00010 * The contents of this file are subject to the Mozilla Public License 00011 * Version 1.0 (the "License"); you may not use this file except in 00012 * compliance with the License. You may obtain a copy of the License at 00013 * http://www.mozilla.org/MPL/ 00014 * 00015 * Software distributed under the License is distributed on an "AS IS" 00016 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See 00017 * the License for the specific language governing rights and limitations 00018 * under the License. 00019 * 00020 * The Original Code is Portable Windows Library. 00021 * 00022 * The Initial Developer of the Original Code is Equivalence Pty. Ltd. 00023 * 00024 * Portions are Copyright (C) 1993 Free Software Foundation, Inc. 00025 * All Rights Reserved. 00026 * 00027 * Contributor(s): ______________________________________. 00028 * 00029 * $Log: thread.h,v $ 00030 * Revision 1.38.2.1 2006/01/29 23:34:53 csoutheren 00031 * Backported thread destruction patch from Derek Smithies 00032 * 00033 * Revision 1.39 2006/01/29 22:35:46 csoutheren 00034 * Added fix for thread termination problems on SMP machines 00035 * Thanks to Derek Smithies 00036 * 00037 * Revision 1.38 2006/01/11 22:27:44 dereksmithies 00038 * Add extra comments describing the usage of Resume() in the constructor of a 00039 * class descended of PThread 00040 * 00041 * Revision 1.37 2005/11/30 12:47:38 csoutheren 00042 * Removed tabs, reformatted some code, and changed tags for Doxygen 00043 * 00044 * Revision 1.36 2005/11/25 03:43:47 csoutheren 00045 * Fixed function argument comments to be compatible with Doxygen 00046 * 00047 * Revision 1.35 2003/10/08 21:39:34 dereksmithies 00048 * Add a #define to cope with backward compatability issues for PThreadIdentifier 00049 * Thanks to Andrey S Pankov and Craig Southeren for their input. 00050 * 00051 * Revision 1.34 2003/09/17 05:41:59 csoutheren 00052 * Removed recursive includes 00053 * 00054 * Revision 1.33 2003/09/17 01:18:02 csoutheren 00055 * Removed recursive include file system and removed all references 00056 * to deprecated coooperative threading support 00057 * 00058 * Revision 1.32 2002/10/04 04:33:27 robertj 00059 * Added functions for getting operating system thread identifier values. 00060 * 00061 * Revision 1.31 2002/09/16 01:08:59 robertj 00062 * Added #define so can select if #pragma interface/implementation is used on 00063 * platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan. 00064 * 00065 * Revision 1.30 2002/06/27 06:44:28 robertj 00066 * Changed "" to PString::Empty() where assigning to PString. 00067 * 00068 * Revision 1.29 2002/04/24 01:49:22 robertj 00069 * Fixed error in PTRACE_BLOCk nesting level to now work when no tracing enabled. 00070 * 00071 * Revision 1.28 2002/04/24 01:09:56 robertj 00072 * Fixed problem with PTRACE_BLOCK indent level being correct across threads. 00073 * 00074 * Revision 1.27 2001/09/10 02:51:22 robertj 00075 * Major change to fix problem with error codes being corrupted in a 00076 * PChannel when have simultaneous reads and writes in threads. 00077 * 00078 * Revision 1.26 2001/05/22 12:49:32 robertj 00079 * Did some seriously wierd rewrite of platform headers to eliminate the 00080 * stupid GNU compiler warning about braces not matching. 00081 * 00082 * Revision 1.25 2000/11/28 12:55:36 robertj 00083 * Added static function to create a new thread class and automatically 00084 * run a function on another class in the context of that thread. 00085 * 00086 * Revision 1.24 2000/10/20 05:31:09 robertj 00087 * Added function to change auto delete flag on a thread. 00088 * 00089 * Revision 1.23 2000/06/26 11:17:19 robertj 00090 * Nucleus++ port (incomplete). 00091 * 00092 * Revision 1.22 2000/02/29 12:26:14 robertj 00093 * Added named threads to tracing, thanks to Dave Harvey 00094 * 00095 * Revision 1.21 1999/06/06 05:07:17 robertj 00096 * Fixed documentation error. 00097 * 00098 * Revision 1.20 1999/03/09 02:59:51 robertj 00099 * Changed comments to doc++ compatible documentation. 00100 * 00101 * Revision 1.19 1999/02/16 08:11:17 robertj 00102 * MSVC 6.0 compatibility changes. 00103 * 00104 * Revision 1.18 1998/11/20 03:18:33 robertj 00105 * Added thread WaitForTermination() function. 00106 * 00107 * Revision 1.17 1998/10/31 12:47:59 robertj 00108 * Removed ability to start threads immediately, race condition with vtable (Main() function). 00109 * 00110 * Revision 1.16 1998/09/23 06:21:41 robertj 00111 * Added open source copyright license. 00112 * 00113 * Revision 1.15 1996/03/02 03:15:51 robertj 00114 * Added automatic deletion of thread object instances on thread completion. 00115 * 00116 * Revision 1.14 1995/12/10 11:44:32 robertj 00117 * Fixed bug in non-platform threads and semaphore timeouts. 00118 * 00119 * Revision 1.13 1995/11/21 11:49:44 robertj 00120 * Added timeout on semaphore wait. 00121 * 00122 * Revision 1.12 1995/07/31 12:10:40 robertj 00123 * Added semaphore class. 00124 * 00125 * Revision 1.11 1995/06/17 11:13:35 robertj 00126 * Documentation update. 00127 * 00128 * Revision 1.10 1995/03/14 12:42:49 robertj 00129 * Updated documentation to use HTML codes. 00130 * 00131 * Revision 1.9 1995/01/16 09:42:13 robertj 00132 * Documentation. 00133 * 00134 * Revision 1.8 1994/09/25 10:45:22 robertj 00135 * Virtualised IsNoLongerBlocked for unix platform. 00136 * 00137 * Revision 1.6 1994/08/22 00:46:48 robertj 00138 * Added pragma fro GNU C++ compiler. 00139 * 00140 * Revision 1.5 1994/08/21 23:43:02 robertj 00141 * Added SuspendBlock state to cooperative multi-threading to fix logic fault. 00142 * 00143 * Revision 1.4 1994/08/04 12:32:22 robertj 00144 * Better name of thread block check function. 00145 * 00146 * Revision 1.3 1994/07/21 12:33:49 robertj 00147 * Moved cooperative threads to common. 00148 * 00149 * Revision 1.2 1994/07/02 03:03:49 robertj 00150 * Added restartable threads. 00151 * 00152 * Revision 1.1 1994/06/25 11:55:15 robertj 00153 * Initial revision 00154 * 00155 */ 00156 00157 #ifndef _PTHREAD 00158 #define _PTHREAD 00159 00160 #ifdef P_USE_PRAGMA 00161 #pragma interface 00162 #endif 00163 00164 #ifdef Priority 00165 #undef Priority 00166 #endif 00167 00168 class PSemaphore; 00169 00170 #define PThreadIdentifer PThreadIdentifier 00171 00172 typedef P_THREADIDENTIFIER PThreadIdentifier; 00173 00175 // PThread 00176 00190 class PThread : public PObject 00191 { 00192 PCLASSINFO(PThread, PObject); 00193 00194 public: 00197 00198 enum Priority { 00200 LowestPriority, 00201 00203 LowPriority, 00204 00206 NormalPriority, 00207 00209 HighPriority, 00210 00212 HighestPriority, 00213 00214 NumPriorities 00215 }; 00216 00218 enum AutoDeleteFlag { 00220 AutoDeleteThread, 00221 00223 NoAutoDeleteThread 00224 }; 00225 00248 PThread( 00249 PINDEX , 00250 AutoDeleteFlag deletion = AutoDeleteThread, 00252 Priority priorityLevel = NormalPriority, 00253 const PString & threadName = PString::Empty() 00254 ); 00255 00263 ~PThread(); 00265 00272 void PrintOn( 00273 ostream & strm 00274 ) const; 00276 00284 virtual void Restart(); 00285 00297 virtual void Terminate(); 00298 00304 virtual BOOL IsTerminated() const; 00305 00311 void WaitForTermination() const; 00312 BOOL WaitForTermination( 00313 const PTimeInterval & maxWait 00314 ) const; 00315 00328 virtual void Suspend( 00329 BOOL susp = TRUE 00330 ); 00331 00351 virtual void Resume(); 00352 00360 virtual BOOL IsSuspended() const; 00361 00363 static void Sleep( 00364 const PTimeInterval & delay 00365 ); 00366 00370 virtual void SetPriority( 00371 Priority priorityLevel 00372 ); 00373 00379 virtual Priority GetPriority() const; 00380 00384 virtual void SetAutoDelete( 00385 AutoDeleteFlag deletion = AutoDeleteThread 00386 ); 00387 00391 void SetNoAutoDelete() { SetAutoDelete(NoAutoDeleteThread); } 00392 00398 virtual PString GetThreadName() const; 00399 00405 virtual void SetThreadName( 00406 const PString & name 00407 ); 00409 00417 virtual PThreadIdentifier GetThreadId() const; 00418 static PThreadIdentifier GetCurrentThreadId(); 00419 00427 virtual void Main() = 0; 00428 00438 static PThread * Current(); 00439 00446 static void Yield(); 00447 00452 static PThread * Create( 00453 const PNotifier & notifier, 00454 INT parameter = 0, 00455 AutoDeleteFlag deletion = AutoDeleteThread, 00457 Priority priorityLevel = NormalPriority, 00458 const PString & threadName = PString::Empty(), 00459 PINDEX stackSize = 10000 00460 ); 00462 00463 protected: 00464 void InitialiseProcessThread(); 00465 /* Initialialise the primordial thread, the one in the PProcess. This is 00466 required due to the bootstrap logic of processes and threads. 00467 */ 00468 00469 private: 00470 PThread(); 00471 // Create a new thread instance as part of a PProcess class. 00472 00473 friend class PProcess; 00474 // So a PProcess can get at PThread() constructor but nothing else. 00475 00476 PThread(const PThread &) { } 00477 // Empty constructor to prevent copying of thread instances. 00478 00479 PThread & operator=(const PThread &) { return *this; } 00480 // Empty assignment operator to prevent copying of thread instances. 00481 00482 BOOL autoDelete; 00483 // Automatically delete the thread on completion. 00484 00485 // Give the thread a name for debugging purposes. 00486 PString threadName; 00487 00488 private: 00489 unsigned traceBlockIndentLevel; 00490 friend class PTrace::Block; 00491 00492 00493 // Include platform dependent part of class 00494 #ifdef _WIN32 00495 #include "msos/ptlib/thread.h" 00496 #else 00497 #include "unix/ptlib/thread.h" 00498 #endif 00499 }; 00500 00501 #endif // _PTHREAD 00502 00503 // End Of File ///////////////////////////////////////////////////////////////