Microsoft DirectX 8.0

CAMThread Class

CAMThread class hierarchy

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_hThreadHandle to the thread.
Public Member Variables
m_AccessLockCritical section that locks the thread from being accessed by other threads.
m_WorkerLockCritical section that locks data shared among threads.
Public Methods
CAMThreadConstructor method.
~CAMThreadDestructor method. Virtual.
InitialThreadProcCalls the ThreadProc method when the thread is created.
CreateCreates the thread.
CallWorkerSignals the thread with a request.
CloseWaits for the thread to exit, then releases its resources.
ThreadExistsQueries whether the thread exists.
GetRequestWaits for the next request.
CheckRequestChecks if there is a request, without blocking.
ReplyReplies to a request.
GetRequestHandleRetrieves a handle to the event signaled by the CallWorker method.
GetRequestParamRetrieves the latest request.
CoInitializeHelperCalls CoInitializeEx at the start of the thread.
Pure Virtual Methods
ThreadProcThread procedure.

CAMThread.m_AccessLock

CAMThread Class

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.

CAMThread.m_WorkerLock

CAMThread Class

Critical section that locks data shared among threads.

Syntax

CCritSec m_WorkerLock;

CAMThread.m_hThread

CAMThread Class

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.

CAMThread::CAMThread

CAMThread Class

Constructor method.

Syntax

CAMThread(void);

Remarks

The constructor method does not create the thread. To create the thread, call the Create method.

CAMThread::~CAMThread

CAMThread Class

Destructor method.

Syntax

virtual ~CAMThread(void);

Remarks

The destructor method calls the Close method, which waits for the thread to exit.

CAMThread::CallWorker

CAMThread Class

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.

CAMThread::CheckRequest

CAMThread Class

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.

CAMThread::Close

CAMThread Class

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.

CAMThread::Create

CAMThread Class

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.

CAMThread::CoInitializeHelper

CAMThread Class

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_FALSEThe CoInitializeEx function is not available.
S_OKSuccess.
E_FAILFailure.

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.

CAMThread::GetRequest

CAMThread Class

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.

CAMThread::GetRequestHandle

CAMThread Class

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.

CAMThread::GetRequestParam

CAMThread Class

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.

CAMThread::InitialThreadProc

CAMThread Class

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.

CAMThread::Reply

CAMThread Class

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.

CAMThread::ThreadExists

CAMThread Class

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.

CAMThread::ThreadProc

CAMThread Class

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.