CAMThread Class

Microsoft DirectX 9.0

CAMThread Class

The CAMThread class is an abstract class for managing worker threads.

Requirements

Header: Declared in Wxutil.h; include Streams.h.

Library: Use Strmbase.lib (retail builds) or Strmbasd.lib (debug builds).

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.

Remarks

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:

Derive a class from CAMThread and override the pure virtual method CAMThread::ThreadProc. This method is the thread procedure that gets called at the start of the thread.
In your application, create an instance of your derived class. Creating the object does not create the thread. To create the thread, call the CAMThread::Create method.
To send requests to the thread, call the CAMThread::CallWorker method. This method takes a DWORD parameter, whose meaning is defined by your class. The method blocks until the thread responds (see below).
In your thread procedure, respond to requests by calling either CAMThread::GetRequest or CAMThread::CheckRequest. The GetRequest method blocks until another thread calls CallWorker. The CheckRequest method is non-blocking, which enables the thread to check for new requests while working asynchronously.
When the thread receives a request, call CAMThread::Reply to unblock the calling thread. The Reply method takes a DWORD parameter, which is passed to the calling thread as the return value for CallWorker.

When you are done with the thread, call the CAMThread::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 CAMThread::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 CAMThread::m_WorkerLock to lock data that is shared among threads.