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.

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

Top of Page