CMsgThread Class

The CMsgThread class is a worker thread class that queues requests to the queuing thread for completion asynchronously. To use this class, derive your class from it and override the CMsgThread::ThreadMessageProc member function. The ThreadMessageProc member function carries out each request. Your client functions and the ThreadMessageProc member function must share a common definition of the parameters in the CMsg object.

A negotiated mechanism tells the worker thread to exit. Typically, this will be one value of the CMsg class's uMsg message code.

It is a good idea to send this message from the destructor of your derived class, and call the CMsgThread::WaitForThreadExit member function before completing the destruction of the derived class.

Protected Data Members

m_hSem Indicates a handle used for signaling.
m_Lock Protects access to lists.
m_lWaiting Indicates waiting for a free thread.
m_ThreadQueue Overrides the CMsgThread::GetThreadMsg member function and blocks on things other than this queue.

Member Functions

CMsgThread Constructs a CMsgThread object.
CreateThread Creates a thread.
GetThreadHandle Retrieves the thread handle.
GetThreadID Retrieves the identifier of the thread.
GetThreadPriority Retrieves the current thread priority.
PutThreadMsg Queues a request for execution by the worker thread.
ResumeThread Continues the operation of the worker thread.
SetThreadPriority Sets the priority of the thread to a new value.
SuspendThread Suspends the operation of a running thread.
WaitForThreadExit Blocks until the thread has exited after a call to the CMsgThread::SuspendThread member function.

Overridable Member Functions

GetThreadMsg Retrieves a queued CMsg object containing a request.
OnThreadInit Provides initialization on a thread.
ThreadMessageProc Processes requests. This is a pure virtual member function.

CMsgThread::CMsgThread

CMsgThread Class

Constructs a CMsgThread object.

Syntax

CMsgThread(void);

Return Value

No return value.

Remarks

Constructing a message thread object does not automatically create the thread. You must call the CMsgThread::CreateThread member function to create the thread.

CMsgThread::CreateThread

CMsgThread Class

Creates a thread.

Syntax

BOOL CreateThread(void);

Return Value

Returns one of the following values.
TRUE Thread was successfully created.
FALSE Thread was not successfully created.

Remarks

The thread will loop, blocking until a request is queued (through the CMsgThread::PutThreadMsg member function) and then calling the CMsgThread::ThreadMessageProc member function with each message.

CMsgThread::GetThreadHandle

CMsgThread Class

Retrieves the handle to the thread in the CMsgThread object.

Syntax

HANDLE GetThreadHandle(void);

Return Value

Returns the thread handle.

Remarks

The thread handle can be passed to Microsoft® Win32® application programming interface (API) functions, such as WaitForMultipleObjects. The thread handle is signaled when the thread has exited.

CMsgThread::GetThreadID

CMsgThread Class

Retrieves the thread's identifier.

Syntax

DWORD GetThreadID(void);

Return Value

Returns the m_ThreadId private data member.

Remarks

This function returns the Microsoft Win32 identifier for the worker thread. You can call this member function on either the worker thread or a client thread.

CMsgThread::GetThreadMsg

CMsgThread Class

Retrieves a queued CMsg object containing a request.

Syntax

void virtual GetThreadMsg(
    CMsg *msg
    );

Parameters

msg
Pointer to an allocated CMsg object.

Remarks

This member function is called from the worker thread's private ThreadProc function to retrieve the next member function. The msg parameter should point to an allocated CMsg object that will be filled with the parameters to the next request in the queue. If there are no queued requests, this member function blocks until the next request is queued (by a call to the CMsgThread::PutThreadMsg member function).

CMsgThread::GetThreadPriority

CMsgThread Class

Uses the Microsoft Win32 GetThreadPriority function to retrieve the priority of the current worker thread.

Syntax

int GetThreadPriority(void);

Return Value

Returns the thread priority as an integer.

CMsgThread::OnThreadInit

CMsgThread Class

Provides initialization on a thread.

Syntax

virtual void OnThreadInit(void);

Return Value

No return value.

Remarks

Override this function if you want to do your own specific initialization on thread startup.

CMsgThread::PutThreadMsg

CMsgThread Class

Queues a request for execution by the worker thread.

Syntax

void PutThreadMsg(
    UINT uMsg,
    DWORD dwMsgFlags,
    LPVOID lpMsgParam,
    CAMEvent *pEvent = NULL
    );

Parameters

uMsg
Request code.
dwMsgFlags
Optional flags parameter.
lpMsgParam
Optional pointer to a data block containing additional parameters or return values. Must be statically or heap-allocated and not automatic.
pEvent
Optional pointer to an event object to be signaled upon completion.

Return Value

No return value.

Remarks

This member function queues a request for execution by the worker thread. The parameters of this member function will be queued (in a CMsg object) and passed to the CMsgThread::ThreadMessageProc member function of the worker thread. This member function returns immediately after queuing the request and does not wait for the thread to fulfill the request. The CMsgThread::ThreadMessageProc member function of the derived class defines the four parameters.
This member function uses a multithread safe list, so multiple calls to this member function from different threads can be made safely.

CMsgThread::ResumeThread

CMsgThread Class

Uses the Microsoft Win32 ResumeThread function to continue the operation of the worker thread after a previous call to the CMsgThread::SuspendThread member function.

Syntax

DWORD ResumeThread(void);

Return Value

If the member function succeeds, the return value is the previous suspend count of the thread. If the member function fails, the return value is 0xFFFFFFFF. To obtain extended error information, call the Microsoft Win32 GetLastError function.

CMsgThread::SetThreadPriority

CMsgThread Class

Uses the Microsoft Win32 SetThreadPriority function to set the priority of the thread to a new value.

Syntax

BOOL SetThreadPriority(
    int nPriority
    );

Parameters

nPriority
Priority of the thread.

Return Value

Returns one of the following values.
TRUE Priority was successfully set.
FALSE Priority was not set.

Remarks

The client and the worker thread can call this member function.

CMsgThread::SuspendThread

CMsgThread Class

Uses the Microsoft Win32 SuspendThread function to suspend the operation of a running thread.

Syntax

DWORD SuspendThread(void);

Return Value

If the member function succeeds, the return value is the previous suspend count of the thread. If the member function fails, the return value is 0xFFFFFFFF. To obtain extended error information, call the Microsoft Win32 GetLastError function.

Remarks

The client thread calls this member function to suspend the operation of the worker thread. The worker thread remains suspended and will not execute until an additional call to the CMsgThread::ResumeThread member function is made.

CMsgThread::ThreadMessageProc

CMsgThread Class

Processes requests. This is a pure virtual member function.

Syntax

virtual LRESULT ThreadMessageProc(
    UINT uMsg,
    DWORD dwFlags,
    LPVOID lpParam,
    CAMEvent *pEvent
    );

Parameters

uMsg
Request code.
dwFlags
Optional flag parameter to request.
lpParam
Optional pointer to extra data or a return data block.
pEvent
Optional pointer to an event object.

Return Value

Any nonzero return causes the thread to exit. Returns zero unless an exit request has been processed recently.

Remarks

This pure virtual function must be overridden in your derived class. It will be called once for each request queued by a call to the CMsgThread::PutThreadMsg member function.
The member function defines the four parameters. Typically, use the uMsg parameter to indicate the request, and the other three parameters will be optional additional parameters. The calling application can supply a pointer to a CAMEvent object in the pEvent parameter if your application requires it. You must set this event after processing the event by using an expression such as:
pEvent->SetEvent
One request code must be set aside to tell the worker thread to exit. Upon receiving this request, return 1 from this member function. Return 0 if you do not want the worker thread to exit.

CMsgThread::WaitForThreadExit

CMsgThread Class

Blocks until the thread exits.

Syntax

BOOL WaitForThreadExit(
    LPDWORD lpdwExitCode
    );

Parameters

lpdwExitCode
Pointer to the exit code returned by the thread.

Return Value

Returns either TRUE or FALSE, the meaning of which is determined by the class supplying the overridden CMsgThread::ThreadMessageProc member function and the calling member function.

Remarks

Ensure that the worker thread has exited completely before completing the destruction of your derived class; otherwise, the thread might still execute after your dynamic-link library (DLL) has been unloaded from the address space of the process. Even if the only instruction left to exit is a single-return instruction, this would cause an exception. The only reliable way to ensure that the thread has exited is to signal the thread to exit (using a privately negotiated CMsg object sent to the CMsgThread::PutThreadMsg member function) and then call this member function. You should do this in the destructor for your derived class.

m_hSem	Indicates a handle used for signaling.
m_Lock	Protects access to lists.
m_lWaiting	Indicates waiting for a free thread.
m_ThreadQueue	Overrides the CMsgThread::GetThreadMsg member function and blocks on things other than this queue.

CMsgThread	Constructs a CMsgThread object.
CreateThread	Creates a thread.
GetThreadHandle	Retrieves the thread handle.
GetThreadID	Retrieves the identifier of the thread.
GetThreadPriority	Retrieves the current thread priority.
PutThreadMsg	Queues a request for execution by the worker thread.
ResumeThread	Continues the operation of the worker thread.
SetThreadPriority	Sets the priority of the thread to a new value.
SuspendThread	Suspends the operation of a running thread.
WaitForThreadExit	Blocks until the thread has exited after a call to the CMsgThread::SuspendThread member function.

GetThreadMsg	Retrieves a queued CMsg object containing a request.
OnThreadInit	Provides initialization on a thread.
ThreadMessageProc	Processes requests. This is a pure virtual member function.

TRUE	Thread was successfully created.
FALSE	Thread was not successfully created.

TRUE	Priority was successfully set.
FALSE	Priority was not set.