CAMThread Class
CAMThread is an abstract class, a worker thread class that provides creation, synchronization, and communication with a worker thread. The worker thread can be accessed from several client threads. The class provides member functions to create the thread, pass commands to it, and wait for it to exit.
Use a CCritSec object to ensure that only one thread can make a request at a time. Use two CAMEvent objects: one to signal to the worker that a request is outstanding, and the other to signal to the client thread that the request has been completed. A nonblocking CAMThread::CheckRequest member function allows the worker thread to check for new requests while working asynchronously.
Derive from this class to provide your own thread member function. You might also want to provide type-safe signaling member functions that package parameters and return values using the CAMThread::CallWorker member function.
Thread creation is independent of object creation. Create a member variable derived from CAMThread, and then use the member functions to start and stop the thread when needed.
m_AccessLock Critical section object that locks access by client threads. m_WorkerLock Critical section object that locks access to shared objects.
Member Functions
CallWorker Makes a request to the worker thread. CAMThread Constructs a CAMThread object. CheckRequest Determines if there is an outstanding request. This is a nonblocking member function. Close Blocks until the thread has exited and released its resources. Create Starts the thread running. GetRequest Blocks until the next request is made and then returns a DWORD value. GetRequestHandle Retrieves an event handle. GetRequestParam Retrieves the latest request. InitialThreadProc Retrieves a this pointer. Carry out this member function before calling the CAMThread::ThreadProc member function. Reply Retrieves a DWORD value to the requesting thread and releases it, signaling completion of the request. ThreadExists Determines whether a thread exists or has exited. ThreadProc Indicates a pure virtual member function that is called on the worker thread.
CAMThread::CallWorker
Makes a request to the worker thread and blocks for a response.
Syntax
DWORD CallWorker(
DWORD dw
);
Parameters
- dw
- Derived class defines the meaning of the parameter.
Return Value
Returns a value that is defined by the derived class.
Remarks
This member function uses a CCritSec object to ensure that only one request is made at a time. It is therefore not valid to call the CAMThread::CallWorker member function from the thread itself or from any member function that is executing in the context of the thread.
CAMThread::CAMThread
Constructs a CAMThread object.
Syntax
CAMThread(void);
Return Value
No return value.
Remarks
Creates a CAMThread object but does not create an actual thread. You call the CAMThread::Create member function to create a thread.
CAMThread::CheckRequest
Determines if there is an outstanding request. This is a nonblocking member function.
Syntax
BOOL CheckRequest(
DWORD *pParam
);
Parameters
- pParam
- Pointer to the value passed by the last call to the CAMThread::CallWorker member function.
Return Value
Returns TRUE if an outstanding request is still active, or FALSE is no request is active.
Remarks
If there is an outstanding request, the requesting thread will block until the CAMThread::GetRequest member function is called. The request remains outstanding (that is, this member function continues to return TRUE) until either the CAMThread::Reply or CAMThread::GetRequest member function is called.
CAMThread::Close
Blocks until the thread has exited and released its resources.
Syntax
void Close(void);
Return Value
No return value.
Remarks
You must instruct the thread to exit by some other means; for example, call the CAMThread::CallWorker member function with a request that is interpreted by the derived class to mean complete and exit.
If the thread is still running when the CAMThread object is destroyed, the CAMThread::Close member function is called internally.
CAMThread::Create
Starts the thread running.
Syntax
BOOL Create(void);
Return Value
Returns TRUE if the thread started successfully, or FALSE if the thread is already running.
Remarks
This member function creates the thread and calls the CAMThread::ThreadProc member function from the derived class.
CAMThread::GetRequest
Blocks until the next request is made.
Syntax
DWORD GetRequest(void);
Return Value
Returns a value that is defined by the derived class.
Remarks
This member function blocks the requesting thread until the CAMThread::Reply function is called.
CAMThread::GetRequestHandle
Retrieves an event handle for performance improvements.
Syntax
HANDLE GetRequestHandle(void) const;
Return Value
Returns an event handle.
Remarks
To use the Microsoft Win32 WaitForMultipleObjects function, you will need this handle in the thread's wait list or the thread will not be responsive.
CAMThread::GetRequestParam
Retrieves the most recent request.
Syntax
DWORD GetRequestParam(void) const;
Return Value
Returns a DWORD value that indicates the request made previously by the CAMThread::GetRequest member function.
CAMThread::InitialThreadProc
Receives a this pointer and calls the CAMThread::ThreadProc member function.
Syntax
DWORD InitialThreadProc(
LPVOID pv
);
Parameters
- pv
- The this pointer.
Return Value
Returns the DWORD returned by CAMThread::ThreadProc. This DWORD is not defined by this class.
CAMThread::Reply
Retrieves a DWORD value to the requesting thread and releases it, signaling completion of the request.
Syntax
void Reply(
DWORD dw
);
Parameters
- dw
- Value returned by the CAMThread::CallWorker member function on the client side.
Return Value
No return value.
CAMThread::ThreadExists
Determines whether the thread has been created and has not yet exited.
Syntax
BOOL ThreadExists(void);
Return Value
Returns TRUE if the thread exists and hasn't exited, or FALSE if the thread doesn't exist.
CAMThread::ThreadProc
Overridden member function in which to implement a thread.
Syntax
virtual DWORD ThreadProc(void);
Return Value
The meaning of this return value is not defined by the CAMThread class.
Remarks
The thread calls this member function upon startup. Derived classes must override this member function. When this member function returns, the thread terminates. This member function is protected.
Top of Page
© 2000 Microsoft and/or its suppliers. All rights reserved. Terms of Use.