Microsoft DirectX 8.0 |
Abstract class for managing worker threads.
Declaration: Wxutil.h
This class provides methods for creating a worker thread, passing requests to the thread, and waiting for the thread to exit. To use this class, do the following:
When you are done with the thread, call the Close method. This method waits for the thread to exit, and then closes the thread handle. Your ThreadProc message must be guaranteed to exit, either on its own or in response to a CallWorker request. The destructor method also calls Close.
The following example illustrates these steps:
class MyThread : public CAMThread { protected: DWORD ThreadProc(void); }; DWORD MyThread::ThreadProc() { BOOL bShutDown = FALSE; while (!bShutDown) { DWORD req = GetRequest(); printf("Request: %d\n", req); bShutDown = (req == 0); Reply(bShutDown ? S_FALSE : S_OK); } printf("Quitting Thread\n"); return 1; } void main() { MyThread thread; DWORD reply; thread.Create(); reply = thread.CallWorker(3); reply = thread.CallWorker(0); // Thread exits. }
In your derived class, you can also define member functions that validate the parameters to CallWorker. The following example shows a typical way to do this:
enum Command {CMD_INIT, CMD_RUN, CMD_STOP, CMD_EXIT}; HRESULT Init(void) { return CallWorker(CMD_INIT); } HRESULT Run(void) { return CallWorker(CMD_RUN); } HRESULT Stop(void) { return CallWorker(CMD_STOP); } HRESULT Exit(void) { return CallWorker(CMD_EXIT); }
The CAMThread class provides two critical sections as public member variables. Use m_AccessLock to lock the thread from being accessed by other threads. (For example, the Create and CallWorker methods hold this lock, to serialize operations on the thread.) Use m_WorkerLock to lock data that is shared among threads.
Protected Member Variables | |
---|---|
m_hThread | Handle to the thread. |
Public Member Variables | |
m_AccessLock | Critical section that locks the thread from being accessed by other threads. |
m_WorkerLock | Critical section that locks data shared among threads. |
Public Methods | |
CAMThread | Constructor method. |
~CAMThread | Destructor method. Virtual. |
InitialThreadProc | Calls the ThreadProc method when the thread is created. |
Create | Creates the thread. |
CallWorker | Signals the thread with a request. |
Close | Waits for the thread to exit, then releases its resources. |
ThreadExists | Queries whether the thread exists. |
GetRequest | Waits for the next request. |
CheckRequest | Checks if there is a request, without blocking. |
Reply | Replies to a request. |
GetRequestHandle | Retrieves a handle to the event signaled by the CallWorker method. |
GetRequestParam | Retrieves the latest request. |
CoInitializeHelper | Calls CoInitializeEx at the start of the thread. |
Pure Virtual Methods | |
ThreadProc | Thread procedure. |
Critical section that locks the thread from being accessed by other threads.
Syntax
CCritSec m_AccessLock;
Remarks
The Create and CallWorker methods hold this lock, to serialize operations on the thread.
Critical section that locks data shared among threads.
Syntax
CCritSec m_WorkerLock;
Handle to the thread.
Syntax
HANDLE m_hThread;
Remarks
This variable is initialized as NULL. The Create method sets this variable to the thread handle. To determine whether the thread exists, call the ThreadExists method.
Constructor method.
Syntax
CAMThread(void);
Remarks
The constructor method does not create the thread. To create the thread, call the Create method.
Destructor method.
Syntax
virtual ~CAMThread(void);
Remarks
The destructor method calls the Close method, which waits for the thread to exit.
Signals the thread with a request.
Syntax
DWORD CallWorker( DWORD dwParam );
Parameters
- dwParam
- Request parameter. The derived class defines the meaning of the parameter.
Return Value
Returns a value that is defined by the derived class.
Remarks
The GetRequest and CheckRequest methods retrieve the value of the dwParam parameter. The GetRequest method blocks until CallWorker is called.
This method blocks until the Reply method is called. The return value is the parameter given to Reply.
This method holds the m_AccessLock lock to serialize requests. Therefore, do call this method from the thread itself or from any member function that executes in the context of the thread.
Checks if there is a request, without blocking.
Syntax
BOOL CheckRequest( DWORD *pParam );
Parameters
- pParam
- Pointer to a variable that receives the value passed in the last call to the CallWorker method.
Return Value
Returns TRUE if there is a pending request, or FALSE otherwise.
Remarks
This method is a non-blocking version of the GetRequest method.
If another thread is waiting on a call to CallWorker, this method retrieves the request parameter and returns TRUE. Otherwise, it returns FALSE. If the method returns TRUE, call the Reply method to release the requesting thread.
Waits for the thread to exit, then releases its resources.
Syntax
void Close(void);
Return Value
No return value.
Remarks
Before calling this method, you must provide a way for the thread to exit. For example, in your ThreadProc method, define a request that signals the thread to exit. Then call the CAMThread::CallWorker method with that value.
The ~CAMThread destructor method calls this method.
Creates the thread.
Syntax
BOOL Create(void);
Return Value
Returns TRUE if successful, or FALSE otherwise.
Remarks
This method creates the thread, using the InitialThreadProc method for the thread procedure and this for the thread argument.
The method fails if the thread already exists.
Calls the CoInitializeEx function at the start of the thread.
Syntax
static HRESULT CoInitializeHelper(void);
Return Value
Returns an HRESULT value. The following are possible values.
S_FALSE The CoInitializeEx function is not available. S_OK Success. E_FAIL Failure.
Remarks
The InitialThreadProc method calls this helper method, which calls the CoInitializeEx function. It uses the COINIT_DISABLE_OLE1DDE flag, to disable Dynamic Data Exchange (DDE). For more information, see the Platform SDK.
Waits for the next request.
Syntax
DWORD GetRequest(void);
Return Value
Returns a value that is defined by the derived class.
Remarks
This method blocks until another thread calls the CallWorker method. Then it returns the parameter that was passed to CallWorker. Call the Reply method to release the requesting thread.
Retrieves a handle to the event signaled by the CallWorker method.
Syntax
HANDLE GetRequestHandle(void) const;
Return Value
Returns an event handle.
Remarks
The CAMEvent class keeps a private manual-reset event, which is set by CallWorker and reset by the Reply method.
If you call a function such as WaitForMultipleObjects, use GetRequestHandle to retrieve the event handle.
Retrieves the latest request.
Syntax
DWORD GetRequestParam(void) const;
Return Value
Returns the value of the parameter that was passed most recently to the CallWorker method.
Calls the ThreadProc method when the thread is created.
Syntax
DWORD InitialThreadProc( LPVOID pv );
Parameters
- pv
- this pointer.
Return Value
Returns the DWORD returned by CAMThread::ThreadProc. The derived class defines this value.
Remarks
The Create method uses this method for the thread procedure when it creates the thread. It uses the this pointer as the thread argument.
This method calls the CoInitializeHelper method and then ThreadProc.
Replies to a request.
Syntax
void Reply( DWORD dw );
Parameters
- dw
- Value to return in the CallWorker method.
Remarks
The CallWorker method blocks until this method is called. The dw parameter supplies the return value for CallWorker. Call this method in your thread procedure after you retrieve a request, to release the requesting thread.
Queries whether the thread exists.
Syntax
BOOL ThreadExists(void);
Return Value
Returns TRUE if the thread exists, or FALSE if the thread does not exist.
Thread procedure.
Syntax
virtual DWORD ThreadProc(void) = 0;
Return Value
Returns a DWORD value whose meaning is defined by the derived class.
Remarks
This is a pure virtual method. Implement this method in your derived class to supply a thread procedure. When the Create method creates a thread, it gives the address of the InitialThreadProc method, which in turn calls your ThreadProc method.
Typically, your ThreadProc method will enter a loop that retrieves requests (by calling the GetRequest or CheckRequest methods) and processes data.
When this method returns, the thread exits.