## CMsgThread Class

This 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

Name | Description
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

Name | Description
CMsgThread | Constructs a CMsgThread object.
CreateThread | Creates a thread.
GetThreadHandle | Returns the thread handle.
GetThreadID | Returns 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

Name | Description
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.

CMsgThread( );

##### Return Values

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.

BOOL CreateThread( );

##### Return Values

Returns one of the following values.

Value | Meaning
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.

HANDLE GetThreadHandle( );

##### Return Values

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.

DWORD GetThreadID( );

##### Return Values

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.

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.

int GetThreadPriority( );

##### Return Values

Returns the thread priority as an integer.

###

CMsgThread::OnThreadInit

CMsgThread Class

Provides initialization on a thread.

virtual void OnThreadInit( );

##### Return Values

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.

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 Values

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.

DWORD ResumeThread( );

##### Return Values

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.

BOOL SetThreadPriority(
int nPriority
);

##### Parameters

nPriority
  Priority of the thread.

##### Return Values

Returns one of the following values.

Value | Meaning
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.

DWORD SuspendThread( );

##### Return Values

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.

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 Values

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.

BOOL WaitForThreadExit(
LPDWORD lpdwExitCode
);

##### Parameters

lpdwExitCode
  Exit code returned by the thread.

##### Return Values

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.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.