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.35 2003/10/08 21:39:34 dereksmithies 00031 * Add a #define to cope with backward compatability issues for PThreadIdentifier 00032 * Thanks to Andrey S Pankov and Craig Southeren for their input. 00033 * 00034 * Revision 1.34 2003/09/17 05:41:59 csoutheren 00035 * Removed recursive includes 00036 * 00037 * Revision 1.33 2003/09/17 01:18:02 csoutheren 00038 * Removed recursive include file system and removed all references 00039 * to deprecated coooperative threading support 00040 * 00041 * Revision 1.32 2002/10/04 04:33:27 robertj 00042 * Added functions for getting operating system thread identifier values. 00043 * 00044 * Revision 1.31 2002/09/16 01:08:59 robertj 00045 * Added #define so can select if #pragma interface/implementation is used on 00046 * platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan. 00047 * 00048 * Revision 1.30 2002/06/27 06:44:28 robertj 00049 * Changed "" to PString::Empty() where assigning to PString. 00050 * 00051 * Revision 1.29 2002/04/24 01:49:22 robertj 00052 * Fixed error in PTRACE_BLOCk nesting level to now work when no tracing enabled. 00053 * 00054 * Revision 1.28 2002/04/24 01:09:56 robertj 00055 * Fixed problem with PTRACE_BLOCK indent level being correct across threads. 00056 * 00057 * Revision 1.27 2001/09/10 02:51:22 robertj 00058 * Major change to fix problem with error codes being corrupted in a 00059 * PChannel when have simultaneous reads and writes in threads. 00060 * 00061 * Revision 1.26 2001/05/22 12:49:32 robertj 00062 * Did some seriously wierd rewrite of platform headers to eliminate the 00063 * stupid GNU compiler warning about braces not matching. 00064 * 00065 * Revision 1.25 2000/11/28 12:55:36 robertj 00066 * Added static function to create a new thread class and automatically 00067 * run a function on another class in the context of that thread. 00068 * 00069 * Revision 1.24 2000/10/20 05:31:09 robertj 00070 * Added function to change auto delete flag on a thread. 00071 * 00072 * Revision 1.23 2000/06/26 11:17:19 robertj 00073 * Nucleus++ port (incomplete). 00074 * 00075 * Revision 1.22 2000/02/29 12:26:14 robertj 00076 * Added named threads to tracing, thanks to Dave Harvey 00077 * 00078 * Revision 1.21 1999/06/06 05:07:17 robertj 00079 * Fixed documentation error. 00080 * 00081 * Revision 1.20 1999/03/09 02:59:51 robertj 00082 * Changed comments to doc++ compatible documentation. 00083 * 00084 * Revision 1.19 1999/02/16 08:11:17 robertj 00085 * MSVC 6.0 compatibility changes. 00086 * 00087 * Revision 1.18 1998/11/20 03:18:33 robertj 00088 * Added thread WaitForTermination() function. 00089 * 00090 * Revision 1.17 1998/10/31 12:47:59 robertj 00091 * Removed ability to start threads immediately, race condition with vtable (Main() function). 00092 * 00093 * Revision 1.16 1998/09/23 06:21:41 robertj 00094 * Added open source copyright license. 00095 * 00096 * Revision 1.15 1996/03/02 03:15:51 robertj 00097 * Added automatic deletion of thread object instances on thread completion. 00098 * 00099 * Revision 1.14 1995/12/10 11:44:32 robertj 00100 * Fixed bug in non-platform threads and semaphore timeouts. 00101 * 00102 * Revision 1.13 1995/11/21 11:49:44 robertj 00103 * Added timeout on semaphore wait. 00104 * 00105 * Revision 1.12 1995/07/31 12:10:40 robertj 00106 * Added semaphore class. 00107 * 00108 * Revision 1.11 1995/06/17 11:13:35 robertj 00109 * Documentation update. 00110 * 00111 * Revision 1.10 1995/03/14 12:42:49 robertj 00112 * Updated documentation to use HTML codes. 00113 * 00114 * Revision 1.9 1995/01/16 09:42:13 robertj 00115 * Documentation. 00116 * 00117 * Revision 1.8 1994/09/25 10:45:22 robertj 00118 * Virtualised IsNoLongerBlocked for unix platform. 00119 * 00120 * Revision 1.6 1994/08/22 00:46:48 robertj 00121 * Added pragma fro GNU C++ compiler. 00122 * 00123 * Revision 1.5 1994/08/21 23:43:02 robertj 00124 * Added SuspendBlock state to cooperative multi-threading to fix logic fault. 00125 * 00126 * Revision 1.4 1994/08/04 12:32:22 robertj 00127 * Better name of thread block check function. 00128 * 00129 * Revision 1.3 1994/07/21 12:33:49 robertj 00130 * Moved cooperative threads to common. 00131 * 00132 * Revision 1.2 1994/07/02 03:03:49 robertj 00133 * Added restartable threads. 00134 * 00135 * Revision 1.1 1994/06/25 11:55:15 robertj 00136 * Initial revision 00137 * 00138 */ 00139 00140 #ifndef _PTHREAD 00141 #define _PTHREAD 00142 00143 #ifdef P_USE_PRAGMA 00144 #pragma interface 00145 #endif 00146 00147 #ifdef Priority 00148 #undef Priority 00149 #endif 00150 00151 class PSemaphore; 00152 00153 #define PThreadIdentifer PThreadIdentifier 00154 00155 typedef P_THREADIDENTIFIER PThreadIdentifier; 00156 00158 // PThread 00159 00173 class PThread : public PObject 00174 { 00175 PCLASSINFO(PThread, PObject); 00176 00177 public: 00180 00181 enum Priority { 00183 LowestPriority, 00184 00186 LowPriority, 00187 00189 NormalPriority, 00190 00192 HighPriority, 00193 00195 HighestPriority, 00196 00197 NumPriorities 00198 }; 00199 00201 enum AutoDeleteFlag { 00203 AutoDeleteThread, 00204 00206 NoAutoDeleteThread 00207 }; 00208 00231 PThread( 00232 PINDEX , 00233 AutoDeleteFlag deletion = AutoDeleteThread, 00235 Priority priorityLevel = NormalPriority, 00236 const PString & threadName = PString::Empty() 00237 ); 00238 00246 ~PThread(); 00248 00255 void PrintOn( 00256 ostream & strm 00257 ) const; 00259 00267 virtual void Restart(); 00268 00280 virtual void Terminate(); 00281 00287 virtual BOOL IsTerminated() const; 00288 00294 void WaitForTermination() const; 00295 BOOL WaitForTermination( 00296 const PTimeInterval & maxWait 00297 ) const; 00298 00311 virtual void Suspend( 00312 BOOL susp = TRUE 00313 ); 00314 00318 virtual void Resume(); 00319 00327 virtual BOOL IsSuspended() const; 00328 00330 static void Sleep( 00331 const PTimeInterval & delay 00332 ); 00333 00337 virtual void SetPriority( 00338 Priority priorityLevel 00339 ); 00340 00346 virtual Priority GetPriority() const; 00347 00351 virtual void SetAutoDelete( 00352 AutoDeleteFlag deletion = AutoDeleteThread 00353 ); 00354 00358 void SetNoAutoDelete() { SetAutoDelete(NoAutoDeleteThread); } 00359 00365 virtual PString GetThreadName() const; 00366 00372 virtual void SetThreadName( 00373 const PString & name 00374 ); 00376 00381 virtual PThreadIdentifier GetThreadId() const; 00382 00385 static PThreadIdentifier GetCurrentThreadId(); 00386 00394 virtual void Main() = 0; 00395 00405 static PThread * Current(); 00406 00413 static void Yield(); 00414 00419 static PThread * Create( 00420 const PNotifier & notifier, 00421 INT parameter = 0, 00422 AutoDeleteFlag deletion = AutoDeleteThread, 00424 Priority priorityLevel = NormalPriority, 00425 const PString & threadName = PString::Empty(), 00426 PINDEX stackSize = 10000 00427 ); 00429 00430 protected: 00431 void InitialiseProcessThread(); 00432 /* Initialialise the primordial thread, the one in the PProcess. This is 00433 required due to the bootstrap logic of processes and threads. 00434 */ 00435 00436 private: 00437 PThread(); 00438 // Create a new thread instance as part of a PProcess class. 00439 00440 friend class PProcess; 00441 // So a PProcess can get at PThread() constructor but nothing else. 00442 00443 PThread(const PThread &) { } 00444 // Empty constructor to prevent copying of thread instances. 00445 00446 PThread & operator=(const PThread &) { return *this; } 00447 // Empty assignment operator to prevent copying of thread instances. 00448 00449 BOOL autoDelete; 00450 // Automatically delete the thread on completion. 00451 00452 // Give the thread a name for debugging purposes. 00453 PString threadName; 00454 00455 private: 00456 unsigned traceBlockIndentLevel; 00457 friend class PTrace::Block; 00458 00459 00460 // Include platform dependent part of class 00461 #ifdef _WIN32 00462 #include "msos/ptlib/thread.h" 00463 #else 00464 #include "unix/ptlib/thread.h" 00465 #endif 00466 }; 00467 00468 #endif // _PTHREAD 00469 00470 // End Of File ///////////////////////////////////////////////////////////////