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_ThreadQueue | Overrides the CMsgThread::GetThreadMsg member function and blocks on things other than this queue. |
| m_Lock | Protects access to lists. |
| m_hSem | Indicates a handle used for signaling. |
| m_lWaiting | Indicates waiting for a free thread. |
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. |
Constructs a CMsgThread object.
CMsgThread( );
No return value.
Constructing a message thread object does not automatically create the thread. You must call the CMsgThread::CreateThread member function to create the thread.
Creates a thread.
BOOL CreateThread( );
Returns one of the following values.
| Value | Meaning |
| TRUE | Thread was successfully created. |
| FALSE | Thread was not successfully created. |
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.
Retrieves the handle to the thread in the CMsgThread object.
HANDLE GetThreadHandle( );
Returns the thread handle.
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.
Retrieves the thread's identifier.
DWORD GetThreadID( );
Returns the m_ThreadId private data member.
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.
Retrieves a queued CMsg object containing a request.
void virtual GetThreadMsg(
CMsg *msg
);
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).
Uses the Microsoft Win32 GetThreadPriority function to retrieve the priority of the current worker thread.
int GetThreadPriority( );
Returns the thread priority as an integer.
Provides initialization on a thread.
virtual void OnThreadInit( );
No return value.
Override this function if you want to do your own specific initialization on thread startup.
Queues a request for execution by the worker thread.
void PutThreadMsg(
UINT uMsg,
DWORD dwMsgFlags,
LPVOID lpMsgParam,
CAMEvent *pEvent = NULL
);
No return value.
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.
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( );
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.
Uses the Microsoft Win32 SetThreadPriority function to set the priority of the thread to a new value.
BOOL SetThreadPriority(
int nPriority
);
Returns one of the following values.
| Value | Meaning |
| TRUE | Priority was successfully set. |
| FALSE | Priority was not set. |
The client and the worker thread can call this member function.
Uses the Microsoft Win32 SuspendThread function to suspend the operation of a running thread.
DWORD SuspendThread( );
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.
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.
Processes requests. This is a pure virtual member function.
virtual LRESULT ThreadMessageProc(
UINT uMsg,
DWORD dwFlags,
LPVOID lpParam,
CAMEvent *pEvent
);
Any nonzero return causes the thread to exit. Returns zero unless an exit request has been processed recently.
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.
Blocks until the thread exits.
BOOL WaitForThreadExit(
LPDWORD lpdwExitCode
);
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.
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.