Main Page | Namespace List | Class Hierarchy | Class List | Directories | File List | Class Members | File Members

thread.h

Go to the documentation of this file.
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 ///////////////////////////////////////////////////////////////

Generated on Mon Feb 21 20:43:10 2005 for PWLib by  doxygen 1.4.1