home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
OS/2 Shareware BBS: 10 Tools
/
10-Tools.zip
/
cset21v1.zip
/
IBMCPP
/
IBMCLASS
/
ITHREAD.HPP
< prev
next >
Wrap
C/C++ Source or Header
|
1993-10-22
|
34KB
|
649 lines
#ifndef _ITHREAD_
#define _ITHREAD_
/*******************************************************************************
* FILE NAME: ithread.hpp *
* *
* DESCRIPTION: *
* Declaration of the class(es): *
* IThread - Objects representing OS/2 threads of execution. *
* IThreadFn - Abstract "threadable function" class. *
* IThreadMemberFn - Template class for "threadable member function." *
* ICurrentThread - Additional functions that can only be applied to the *
* current thread of execution. *
* *
* COPYRIGHT: *
* Licensed Materials - Property of IBM *
* (C) Copyright IBM Corporation 1992, 1993 *
* All Rights Reserved *
* US Government Users Restricted Rights - Use, duplication, or disclosure *
* restricted by GSA ADP Schedule Contract with IBM Corp. *
* *
*******************************************************************************/
#ifndef _IVBASE_
#include <ivbase.hpp>
#endif
#ifndef _IREFCNT_
#include <irefcnt.hpp>
#endif
#ifndef _IHANDLE_
#include <ihandle.hpp>
#endif
#ifndef _IAPP_
#include <iapp.hpp>
#endif
/*----------------------------------------------------------------------------*/
/* Align classes on four byte boundary. */
/*----------------------------------------------------------------------------*/
#pragma pack(4)
/*----------------------------------------------------------------------------*/
/* Turn off warning for compiler generated copy/assignment */
/*----------------------------------------------------------------------------*/
#pragma info(nocpy)
class IThreadFn : public IRefCounted {
typedef IRefCounted
Inherited;
/*******************************************************************************
* The IThreadFn class is an abstract thread function class. *
* *
* Objects of this class are used to represent functions to be dispatched on *
* secondary threads of execution when an IThread is started. These objects *
* are reference counted to manage their destruction (after the thread has *
* terminated); a reference to such an IThreadFn is passed to IThread::start. *
* *
* See IThread for details on usage of this class. *
* *
* Example: *
* *
* class MyFunction : public IThreadFn { *
* public: *
* virtual void *
* run ( ) *
* { *
* // Place your code here. *
* } *
* }; *
* //... *
* IThread newThread( new MyFunction ); *
*******************************************************************************/
public:
IThreadFn ( );
virtual
~IThreadFn ( );
/*---------------------------- Callback Function -------------------------------
| The following function is a callback function: |
| run - Called when the thread function object is invoked. |
------------------------------------------------------------------------------*/
virtual void
run ( ) = 0;
}; // class IThreadFn
template < class T >
class IThreadMemberFn : public IThreadFn {
typedef IThreadFn
Inherited;
/*******************************************************************************
* The IThreadMemberFn template class is an IThreadFn derived class for *
* dispatching C++ member functions against an object on a new thread. The *
* template argument is: *
* *
* T - The class of object against which the member functions will be *
* applied. *
* *
* Instances of this class are used to dispatch C++ member functions on a *
* separate thread. The template argument is the class of the object for *
* which the functions are called. The constructor for such objects requires *
* a reference to the object the member functions are to be applied to and a *
* pointer to the member functions. *
* *
* The member functions return void and accept no arguments. Support for *
* other member functions can be added by subclassing this class. *
* *
* Example: *
* class MyClass { *
* public: *
* void job() *
* { *
* // Code to run on separate thread. *
* } *
* }; *
* //... *
* MyClass myObj; *
* IThread thread; *
* thread.start( new IThreadMemberFn<MyClass>( myObj, MyClass::job ) ); *
*******************************************************************************/
public:
/*------------------------------- Constructor ----------------------------------
| The constructor requires an object of the template argument class T and a |
| pointer to a member function of that class (returning void and accepting no |
| arguments). |
------------------------------------------------------------------------------*/
IThreadMemberFn ( T &obj,
void ( T :: *mem )( ) )
: member( mem ), object( obj )
{
}
/*-------------------------------- Overrides -----------------------------------
| This class overrides the following inherited function: |
| run - Calls the pointed-to member function to the argument provided at |
| construction. |
------------------------------------------------------------------------------*/
virtual void
run ( )
{
(object.*member)();
}
private: /*------------------------ PRIVATE ----------------------------------*/
T
&object;
void ( T ::
*member )( );
}; // IThreadMemberFn
class IStartedThread;
class IWindowList;
struct tib_s;
class ICurrentThread;
class IThread : public IVBase {
typedef IVBase
Inherited;
/*******************************************************************************
* The IThread class's objects represent threads of execution within the *
* current program. This class provides support for implementing multi- *
* threaded programs. IThread objects provide access to all the tasking APIs *
* of the operating system. In addition, these objects serve as the anchor *
* for thread-specific information (for example, the Presentation Manager *
* anchor block). *
* *
* IThread objects are generally used in one of the following ways: *
* *
* - To apply thread functions to the current thread. In most cases, these *
* functions will be applied to the IThread object reference returned by *
* the static member IThread::current. *
* *
* - To create additional threads of execution by instantiating new IThread *
* objects and starting them. *
* *
* - To manipulate threads of execution initiated using alternate means, *
* and for which only the thread's ID is known. *
* *
* EXAMPLE: *
* *
* // This is typical code appearing in main(): *
* IThread::current().initializePM(); // Initialize PM environment. *
* // Create windows... *
* IThread::current().processMsgs(); // Process window messages. *
* IThread::current().terminatePM(); // Terminate PM environment. *
* *
* // This is typical code to spawn a new thread to execute *
* // member function foo() against the "this" object: *
* IThread thread; *
* thread.start( IThreadMemberFn< MyClass >( this, foo ) ); *
* *
* // This is typical code that operates on a thread with ID tid: *
* IThread thread( tid ); *
* thread.suspend(); *
* //... *
* thread.resume(); *
*******************************************************************************/
public:
/*------------------------------ Function Types --------------------------------
| These typedefs define the two types of (non-member) functions that can |
| be dispatched on a separate thread: |
| OptlinkFnPtr - Pointer to a function with _Optlink linkage. |
| SystemFnPtr - Pointer to a function with _System linkage. |
------------------------------------------------------------------------------*/
typedef void ( _Optlink *OptlinkFnPtr ) ( void * );
typedef void ( _System *SystemFnPtr ) ( unsigned long );
/*------------------------- Constructors/Destructor ----------------------------
| You can construct instances of this class in the following ways: |
| |
| - Using the default constructor. The default constructor is used to |
| build an IThread to be subsequently started using the start member |
| function. |
| |
| - With specification of code to run. This form of the constructor is |
| used to construct a new IThread and immediately dispatch it. It is |
| equivalent to constructing using the default constructor and then |
| dispatching the thread using start. |
| |
| This constructor permits specification of whether or not the new |
| thread is to be a Presentation Manager thread. If it is, then |
| initializePM is called automatically after the thread is started. |
| |
| - From the thread ID of a previously started thread. This constructor |
| is used to provide IThread functionality to threads created using |
| alternate means (either using _beginthread or DosCreateThread). |
| |
| IThread has a virtual destructor that takes care of deallocating resources. |
| |
| NOTE: The destructor does not stop the thread. |
| |
| Multi-threaded programs (those that invoke the start member function) |
| should be compiled with /Gm+ in order to avoid unresolved externals at link |
| time. |
------------------------------------------------------------------------------*/
IThread ( );
IThread ( const IThread &aThread );
IThread ( const IThreadId &anID );
IThread ( const IReference<IThreadFn> &aFnObjRef,
Boolean autoInitPM = IThread::defaultAutoInitPM() );
IThread ( OptlinkFnPtr pfn,
void *anArg,
Boolean autoInitPM = IThread::defaultAutoInitPM() );
IThread ( SystemFnPtr pfn,
unsigned long anArg,
Boolean autoInitPM = IThread::defaultAutoInitPM() );
virtual
~IThread ( );
/*------------------------------ Starting/Stopping -----------------------------
| These functions enable the starting and stopping of threads: |
| start - Starts an asynchronous thread. Threads can be started using |
| any of the following means: |
| o With an arbitrary IThreadFn. The IThreadFn is passed in |
| using an IReference so that the IThreadFn can be deleted |
| (if necessary) when the thread terminates. |
| o With an OptlinkFnPtr function and void* argument. This is |
| to provide support for functions otherwise startable using |
| _beginthread. |
| o With a SystemFnPtr function and unsigned long argument. |
| This is to provide support for functions otherwise |
| startable using DosCreateThread. |
| stop - Stops the thread. |
| suspend - Suspends the thread's execution. |
| resume - Resumes the thread's execution. |
------------------------------------------------------------------------------*/
void
start ( const IReference<IThreadFn> &aFnObjRef,
Boolean autoInitPM = IThread::defaultAutoInitPM() ),
start ( OptlinkFnPtr pfn,
void *anArg,
Boolean autoInitPM = IThread::defaultAutoInitPM() ),
start ( SystemFnPtr pfn,
unsigned long anArg,
Boolean autoInitPM = IThread::defaultAutoInitPM() );
virtual void
stop ( ),
suspend ( ),
resume ( );
/*-------------------------------- Accessing -----------------------------------
| These functions provide a means of getting and setting various thread |
| attributes: |
| id - Obtains the ID of the thread (0 indicates the thread is not |
| started). |
| current - Returns a reference to a thread object that represents the |
| currently executing thread. |
| currentId - Returns the current thread ID. |
| asString - Returns a string of the form "IThread(tid)". |
| asDebugInfo - Returns a representation of the thread as diagnostic |
| information. |
------------------------------------------------------------------------------*/
static ICurrentThread
¤t ( );
virtual IThreadId
id ( ) const;
static IThreadId
currentId ( );
virtual IString
asString ( ) const,
asDebugInfo ( ) const;
/*----------------------------- Window Information List ------------------------
| These functions provide access to the thread window information list. |
| windowList - Obtains a pointer to the window information list for this |
| thread. |
| setWindowList - Sets a pointer to the window information list for this |
| thread. |
------------------------------------------------------------------------------*/
IWindowList
*windowList ( ) const;
IThread
&setWindowList ( IWindowList *list );
/*-------------------------------- Stack Size ----------------------------------
| These functions provide access to the thread stack size: |
| stackSize - Obtains the thread stack size (in bytes). |
| setStackSize - Sets the thread stack size (in bytes). If the |
| thread is started, this value will take effect only |
| when the thread is stopped and restarted. |
| defaultStackSize - Obtains the default stack size (the value used by |
| default for new IThreads). |
| setDefaultStackSize - Sets the default stack size. |
------------------------------------------------------------------------------*/
virtual unsigned long
stackSize ( ) const;
virtual IThread
&setStackSize ( unsigned long aSize );
static unsigned long
defaultStackSize ( );
static void
setDefaultStackSize ( unsigned long aSize );
/*----------------------- Presentation Manager Support -------------------------
| These functions provide basic Presentation Manager (PM) support for |
| threads. Additional Presenation Manager functions can be applied to the |
| current thread (see ICurrentThread): |
| autoInitPM - Obtains the setting of the flag that automatically |
| initializes Presentation Manager for this thread. |
| setAutoInitPM - Sets the flag that automatically initializes |
| Presentation Manager for this thread. |
| defaultAutoInitPM - Obtains the default flag that automatically |
| initializes Presentation Manager. Unless this |
| flag is explicitly set using the |
| setDefaultAutoInitPM function, this will return |
| true for programs running in a Presentation |
| Manager session and false for programs running in |
| a non-Presentation Manager session. |
| setDefaultAutoInitPM - Sets the default flag that automatically |
| initializes Presentation Manager. |
| stopProcessingMsgs - Terminates the processing of window events | |
| (messages) initiated by the |
| ICurrentThread::processMsgs member function. | |
------------------------------------------------------------------------------*/
virtual Boolean
autoInitPM ( ) const;
virtual IThread
&setAutoInitPM ( Boolean initFlag );
static Boolean
defaultAutoInitPM ( );
static void
setDefaultAutoInitPM ( Boolean initFlag );
virtual IThread
&stopProcessingMsgs ( );
/*---------------------------- Message Queue Size ------------------------------
| These functions control the size of the Presentation Manager message queue: |
| queueSize - Obtains the Presentation Manager message queue size |
| to be used (or being used) for this thread. |
| setQueueSize - Sets the Presentation Manager message queue size |
| for this thread. |
| defaultQueueSize - Obtains the default Presentation Manager message |
| queue size to be used for new IThreads. |
| setDefaultQueueSize - Sets the default Presentation Manager message queue |
| size. |
------------------------------------------------------------------------------*/
virtual long
queueSize ( ) const;
virtual IThread
&setQueueSize ( long queueSize );
static long
defaultQueueSize ( );
static void
setDefaultQueueSize ( long queueSize );
/*----------------------------- Thread Priority --------------------------------
| These functions control the thread priority: |
| priorityClass - Obtains the priority class of the thread (a value of |
| type IApplication::PriorityClass). |
| setPriority - Sets the priority class and level of the thread. |
| priorityLevel - Obtains the priority level of the thread (a value in the |
| range 0-31). |
| adjustPriority - Changes the thread priority level by a given amount (a |
| value between -31 and 31). |
------------------------------------------------------------------------------*/
virtual unsigned
priorityLevel ( ) const;
virtual IApplication::PriorityClass
priorityClass ( ) const;
virtual IThread
&setPriority ( IApplication::PriorityClass aClass,
unsigned level ),
&adjustPriority ( int delta );
/*--------------------------------- Testing ------------------------------------
| This function tests various attributes of the thread: |
| isStarted - Returns true if the thread is currently active. |
------------------------------------------------------------------------------*/
virtual Boolean
isStarted ( ) const;
/*-------------------------------- Iteration -----------------------------------
| The following provide utilities for iterating over the active threads for |
| the current application: |
| Cursor - Nested cursor class used to iterate over the set of active |
| threads. Note that this class will only provide access to |
| threads "known" by IThread. |
------------------------------------------------------------------------------*/
class Cursor : public IVBase {
typedef IVBase
Inherited;
public:
/*------------------------------- Constructor ----------------------------------
| The constructor accepts an optional flag indicating whether all threads |
| should be enumerated or only those which have ICLUI windows. The default |
| is all threads. |
------------------------------------------------------------------------------*/
Cursor ( Boolean allThreads = true );
~Cursor ( );
/*----------------------------- Cursor Functions -------------------------------
| These functions provide the basic cursor functionality of this class: |
| setToFirst - Initializes the cursor to the first thread. |
| setToNext - Advances cursor to the next thread. |
| isValid - Returns true if the cursor is valid. |
| invalidate - Invalidates the cursor. |
| threadId - Returns the Id of the thread at the current cursor position. |
------------------------------------------------------------------------------*/
Boolean
setToFirst ( ),
setToNext ( ),
isValid ( ) const;
void
invalidate ( );
IThreadId
threadId ( ) const;
private: /*------------------------ PRIVATE ----------------------------------*/
Boolean
all,
advance ( );
unsigned
cursor,
created;
friend class IStartedThread;
static unsigned
timeStamp;
}; // class IThread::Cursor
protected:
/*------------------------------ Implementation --------------------------------
| These functions provide utilities used to implement this class: |
| startedThread - Returns the address of the corresponding |
| IStartedThread. |
| newStartedThread - Returns a pointer to the new IStartedThread. |
------------------------------------------------------------------------------*/
virtual IStartedThread
*startedThread ( ) const;
static IStartedThread
*newStartedThread ( );
/*-------------------------------- Assignment ----------------------------------
| This operator is used for assignment: |
| operator = - Provides for assignment of one IThread to another |
| (preserving resource allocation). |
------------------------------------------------------------------------------*/
IThread
&operator = ( const IThread &aThread );
private: /*------------------------ PRIVATE ----------------------------------*/
friend class ICurrentThread;
friend class IWindow;
IStartedThread
*prepareToStart ( const IReference<IThreadFn> &, Boolean );
void
threadStarted ( IStartedThread *, int );
IString
variable( const IString &key ) const;
IThread
&setVariable( const IString &key,
const IString &value );
static Boolean
inPMSession ( );
Boolean
inMsgLoop ( ) const;
IStartedThread
*thread;
static unsigned long
dfltStackSize;
static Boolean
dfltAutoInitPM;
static long
dfltQueueSize;
static ICurrentThread
*pCurrent;
}; // IThread
class ICurrentThread : public IThread {
typedef IThread
Inherited;
/*******************************************************************************
* The ICurrentThread class provides additional functions that can only be *
* applied to the current thread of execution. *
* *
* A reference to the sole instance of this class is obtained only by using *
* the static IThread::current member function. *
* *
* The resulting object is used to call the thread APIs that can only be *
* applied to the current thread of execution. Essentially, these are the *
* APIs that operate on a per-thread basis but do not accept a thread ID as *
* an argument. *
*******************************************************************************/
public:
/*------------------Presentation Manager Support -------------------------------
| These functions provide support for performing windowing (Presentation |
| Manager) activities on the current thread: |
| |
| initializePM - Sets up the Presentation Manager environment (anchor |
| block and message queue). |
| processMsgs - Gets and dispatches Presentation Manager messages until |
| WM_QUIT is received. |
| terminatePM - Shuts down the Presentation Manager environment. |
| isPMInitialized - Returns true if the Presentation Manager environment is |
| active for this thread. |
| anchorBlock - Obtains the anchor block handle for the thread (0 if not |
| initialized). |
| messageQueue - Obtains the message queue handle for the thread (0 if |
| not initialized). |
------------------------------------------------------------------------------*/
virtual void
initializePM ( long queueSize = 0 ),
processMsgs ( ),
terminatePM ( );
virtual Boolean
isPMInitialized ( ) const;
virtual IAnchorBlockHandle
anchorBlock ( ) const;
virtual IMessageQueueHandle
messageQueue ( ),
messageQueue ( ) const;
/*-------------------------- Current Thread Function ---------------------------
| These functions enable thread operations only applicable to the current |
| thread: |
| remainingStack - Returns an approximation of the number of stack |
| bytes remaining (0 if no started). |
| sleep - Suspends the thread for a given number of |
| milliseconds. |
| waitFor - Causes the current thread to wait for a given |
| thread to terminate. |
| waitForAnyThread - Causes the current thread to wait for any thread |
| to terminate (and returns its ID). |
| waitForAllThreads - Causes the current thread to wait for all |
| secondary threads to terminate. |
| exit - Terminates the current thread with a given return |
| value. |
------------------------------------------------------------------------------*/
virtual unsigned long
remainingStack ( ) const;
virtual ICurrentThread
&sleep ( unsigned long msecs ),
&waitFor ( const IThread &anotherThread ),
&waitForAllThreads ( );
virtual IThreadId
waitForAnyThread ( );
virtual void
exit ( unsigned long rc );
/*--------------------------------- Overrides----------------------------------
| This class reimplements these functions: |
| id - Returns the current thread's ID. |
| suspend - Checks that the current thread is not a Presentation |
| Manager thread. |
| startedThread - Returns a pointer to IStartedThread for the current thread.|
------------------------------------------------------------------------------*/
virtual IThreadId
id ( ) const;
virtual void
suspend ( );
protected:
virtual IStartedThread
*startedThread ( ) const;
/*------------------------------- Constructor ----------------------------------
| The constructor for this class is protected in order to prevent creation |
| of objects of this class except from within IThread::current. |
------------------------------------------------------------------------------*/
ICurrentThread ( );
private: /*------------------------ PRIVATE ----------------------------------*/
friend class IThread;
~ICurrentThread ( );
}; // ICurrentThread
/*----------------------------------------------------------------------------*/
/* Resume compiler default packing and warning messages. */
/*----------------------------------------------------------------------------*/
#pragma pack()
#pragma info(restore)
#ifndef I_NO_INLINES
#include <ithread.inl>
#endif
#endif /* _ITHREAD_ */
