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.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 ///////////////////////////////////////////////////////////////

Generated on Fri Sep 21 14:40:11 2007 for PWLib by  doxygen 1.5.3