`CWinThread` 類別

發行項
07/05/2024

代表應用程式內執行的執行緒。

語法

class CWinThread : public CCmdTarget

成員

公用建構函式

名稱	描述
`CWinThread::CWinThread`	建構 `CWinThread` 物件。

公用方法

名稱	描述
`CWinThread::CreateThread`	開始執行 `CWinThread` 物件。
`CWinThread::ExitInstance`	覆寫以在線程終止時清除。
`CWinThread::GetMainWnd`	擷取線程主視窗的指標。
`CWinThread::GetThreadPriority`	取得目前線程的優先順序。
`CWinThread::InitInstance`	覆寫以執行線程實例初始化。
`CWinThread::IsIdleMessage`	檢查是否有特殊訊息。
`CWinThread::OnIdle`	覆寫以執行線程特定的閑置時間處理。
`CWinThread::PostThreadMessage`	將訊息張貼至另一個 `CWinThread` 物件。
`CWinThread::PreTranslateMessage`	先篩選訊息，再分派至 Windows 函式 `TranslateMessage` 和 `DispatchMessage`。
`CWinThread::ProcessMessageFilter`	在到達應用程式之前攔截特定訊息。
`CWinThread::ProcessWndProcException`	攔截線程訊息和命令處理程序擲回的所有未處理的例外狀況。
`CWinThread::PumpMessage`	包含線程的訊息迴圈。
`CWinThread::ResumeThread`	遞減線程的暫停計數。
`CWinThread::Run`	使用訊息幫浦控制線程的函式。覆寫以自定義預設訊息迴圈。
`CWinThread::SetThreadPriority`	設定目前線程的優先順序。
`CWinThread::SuspendThread`	遞增線程的暫停計數。

公用運算子

名稱	描述
`CWinThread::operator HANDLE`	擷取物件的句柄 `CWinThread` 。

公用資料成員

名稱	描述
`CWinThread::m_bAutoDelete`	指定是否要在線程終止時終結物件。
`CWinThread::m_hThread`	目前線程的句柄。
`CWinThread::m_nThreadID`	目前線程的標識碼。
`CWinThread::m_pActiveWnd`	當 OLE 伺服器就地作用中時，容器應用程式主視窗的指標。
`CWinThread::m_pMainWnd`	保留應用程式主視窗的指標。

備註

執行的主要線程通常是由衍生自 CWinApp的物件提供; CWinApp 衍生自 CWinThread。其他 CWinThread 物件允許指定應用程式內的多個線程。

有兩種一般類型的線程 CWinThread 支援：背景工作線程和使用者介面線程。背景工作線程沒有訊息幫浦：例如，在電子錶格應用程式中執行背景計算的線程。使用者介面線程具有從系統接收的訊息幫浦和處理訊息。 CWinApp 衍生自它的和類別是使用者介面線程的範例。其他使用者介面線程也可以直接從衍生自 CWinThread。

類別 CWinThread 的物件通常存在於線程的持續時間內。如果您要變更此行為，請將設定 m_bAutoDelete 為 FALSE。

類別 CWinThread 必須讓程式代碼和MFC完全安全線程。架構用來維護線程特定資訊的線程區域數據是由 CWinThread 物件所管理。由於此相依於 CWinThread 來處理線程本機數據，因此任何使用MFC的線程都必須由MFC 建立。例如，運行時間函_beginthread_beginthreadex式所建立的線程無法使用任何 MFC API。

若要建立線程，請呼叫 AfxBeginThread。有兩種形式，視您想要背景工作角色或使用者介面線程而定。如果您想要使用者介面線程，請傳遞至AfxBeginThread衍生類別的CWinThread指標CRuntimeClass。如果您想要建立背景工作線程，請傳遞至 AfxBeginThread 控制函式的指標，並將參數傳遞至控制函式。針對背景工作線程和使用者介面線程，您可以指定選擇性參數來修改優先順序、堆疊大小、建立旗標和安全性屬性。 AfxBeginThread 會傳回新 CWinThread 物件的指標。

您可以建構CWinThread衍生的物件，然後呼叫 CreateThread，而不是呼叫 AfxBeginThread。如果您想要在連續建立和終止線程執行之間重複使用 CWinThread 對象，這個雙階段建構方法會很有用。

如需的詳細資訊CWinThread，請參閱使用 C++ 和 MFC 的多線程、多線程：建立使用者介面線程、多線程：建立背景工作線程和多線程：如何使用同步處理類別一文。

繼承階層架構

CObject

CCmdTarget

CWinThread

需求

標頭： afxwin.h

`CWinThread::CreateThread`

建立線程，以在呼叫進程的位址空間內執行。

BOOL CreateThread(
    DWORD dwCreateFlags = 0,
    UINT nStackSize = 0,
    LPSECURITY_ATTRIBUTES lpSecurityAttrs = NULL);

參數

dwCreateFlags
指定控制線程建立的其他旗標。此旗標可以包含兩個值的其中一個：

CREATE_SUSPENDED 使用暫停計數啟動線程。 CREATE_SUSPENDED如果您要線上程開始執行之前初始化物件的任何成員資料CWinThread，例如 m_bAutoDelete 或衍生類別的任何成員，請使用。初始化完成之後，請使用 CWinThread::ResumeThread 來啟動執行中的線程。在呼叫之前 CWinThread::ResumeThread ，線程將不會執行。
0 建立之後立即啟動線程。

nStackSize
指定新線程堆疊的位元組大小。如果 為 0，堆疊大小會預設為與進程主要線程的大小相同。

lpSecurityAttrs
指向 SECURITY_ATTRIBUTES 結構，指定線程的安全性屬性。

傳回值

如果成功建立線程，則為非零;否則為 0。

備註

使用 AfxBeginThread 來建立線程物件，並在一個步驟中執行它。如果您要在後續建立和終止線程執行之間重複使用線程物件，請使用 CreateThread 。

`CWinThread::CWinThread`

建構 CWinThread 物件。

CWinThread();

備註

若要開始線程的執行，請呼叫 CreateThread 成員函式。您通常會藉由呼叫來 AfxBeginThread建立線程，這會呼叫這個建構函式和 CreateThread。

`CWinThread::ExitInstance`

由架構從很少覆 Run 寫的成員函式中呼叫，以結束這個線程實例，或呼叫 InitInstance 失敗時。

virtual int ExitInstance();

傳回值

線程的結束代碼;0 表示沒有錯誤，且大於 0 的值表示錯誤。呼叫即可擷 GetExitCodeThread取此值。

備註

請勿從任何位置呼叫這個成員函式，而是從成員函式內 Run 呼叫。這個成員函式只會用於使用者介面線程中。

如果 m_bAutoDelete 為 TRUE，CWinThread則此函式的預設實作會刪除物件。如果您想要在線程終止時執行額外的清除，請覆寫此函式。的實 ExitInstance 作應該在執行程式代碼之後呼叫基類的版本。

`CWinThread::GetMainWnd`

如果您的應用程式是 OLE 伺服器，請呼叫此函式來擷取應用程式作用中主視窗的指標，而不是直接參考 m_pMainWnd 應用程式對象的成員。

virtual CWnd* GetMainWnd();

傳回值

此函式會傳回兩種窗口類型之一的指標。如果您的線程是 OLE 伺服器的一部分，且對象位於使用中容器內，則此函式會傳 CWinApp::m_pActiveWnd 回對象的數據成員 CWinThread 。

如果容器內沒有就地作用中的物件，或您的應用程式不是 OLE 伺服器，則此函式會 m_pMainWnd 傳回線程對象的數據成員。

備註

對於使用者介面線程，這相當於直接參考 m_pActiveWnd 應用程式對象的成員。

如果您的應用程式不是 OLE 伺服器，則呼叫此函式和直接參考應用程式物件的 m_pMainWnd 成員的功用相同。

覆寫此函式以修改預設行為。

`CWinThread::GetThreadPriority`

取得這個線程的目前線程優先順序層級。

int GetThreadPriority();

傳回值

目前線程優先順序層級在其優先順序類別內。傳回的值會是下列其中一項，從最高優先順序列到最低：

THREAD_PRIORITY_TIME_CRITICAL
THREAD_PRIORITY_HIGHEST
THREAD_PRIORITY_ABOVE_NORMAL
THREAD_PRIORITY_NORMAL
THREAD_PRIORITY_BELOW_NORMAL
THREAD_PRIORITY_LOWEST
THREAD_PRIORITY_IDLE

如需這些優先順序的詳細資訊，請參閱 SetThreadPriority Windows SDK。

`CWinThread::InitInstance`

InitInstance 必須覆寫，才能初始化使用者介面線程的每個新實例。

virtual BOOL InitInstance();

傳回值

如果初始化成功，則為非零;否則為 0。

備註

一般而言，您會覆寫 InitInstance 以執行第一次建立線程時必須完成的工作。

這個成員函式只會用於使用者介面線程中。在傳遞至 AfxBeginThread的控制函式中執行背景工作線程初始化。

`CWinThread::IsIdleMessage`

覆寫此函式，使其在產生特定訊息之後不 OnIdle 呼叫。

virtual BOOL IsIdleMessage(MSG* pMsg);

參數

pMsg
指向正在處理的目前訊息。

傳回值

如果 OnIdle 應該在處理訊息之後呼叫，則為非零，否則為0。

備註

默認實作不會在重複的滑鼠訊息和閃爍插入號所產生的訊息之後呼叫 OnIdle 。

如果應用程式已建立簡短定時器， OnIdle 將會經常呼叫，而導致效能問題。若要改善這類應用程式的效能，請在應用程式的 CWinApp衍生類別中覆寫 IsIdleMessage ，以檢查WM_TIMER訊息，如下所示：

BOOL CMyWinApp::IsIdleMessage(MSG* pMsg)
{
   if (!CWinApp::IsIdleMessage(pMsg) || pMsg->message == WM_TIMER)
      return FALSE;
   else
      return TRUE;
}

以這種方式處理 WM_TIMER 可改善使用簡短定時器之應用程式的效能。

`CWinThread::m_bAutoDelete`

指定在執行緒終止時是否要自動刪除 CWinThread 物件。

BOOL m_bAutoDelete;

備註

數據 m_bAutoDelete 成員是 BOOL 類型的公用變數。

的值 m_bAutoDelete 不會影響基礎線程句柄的關閉方式，但會影響關閉句柄的時間。在 CWinThread 物件終結時，執行緒控制代碼永遠關閉。

`CWinThread::m_hThread`

附加至這個 CWinThread的線程句柄。

HANDLE m_hThread;

備註

數據 m_hThread 成員是類型的 HANDLE公用變數。只有在基礎核心線程物件目前存在且句柄尚未關閉時，它才有效。

解CWinThread構函式會在上m_hThread呼叫 CloseHandle 。如果 m_bAutoDelete 為 TRUE 線程終止時， CWinThread 就會終結物件，使物件及其成員變數的任何指標 CWinThread 失效。您可能需要成員 m_hThread 來檢查線程結束值，或等候訊號。若要在CWinThread線程執行期間和終止之後保留物件及其m_hThread成員，請在允許線程執行繼續之前，將設定m_bAutoDeleteFALSE為。否則，線程可能會終止、終結 CWinThread 物件，並在您嘗試使用它之前關閉句柄。如果您使用這項技術，您必須負責刪除 CWinThread 物件。

`CWinThread::m_nThreadID`

附加至這個 CWinThread之線程的標識碼。

DWORD m_nThreadID;

備註

數據 m_nThreadID 成員是類型的 DWORD公用變數。只有在基礎核心線程物件目前存在時才有效。另請參閱有關存留 m_hThread 期的備註。

範例

請參閱 AfxGetThread 的範例。

`CWinThread::m_pActiveWnd`

使用此資料成員來儲存線程使用中視窗物件的指標。

CWnd* m_pActiveWnd;

備註

當所 m_pActiveWnd 參考的窗口關閉時，Microsoft Foundation Class Library 會自動終止您的線程。如果此線程是應用程式的主要線程，應用程式也會終止。如果這個資料成員是 NULL，則會繼承應用程式 CWinApp 物件的使用中視窗。 m_pActiveWnd 是類型的 CWnd*公用變數。

一般而言，當您覆寫 InitInstance時，會設定這個成員變數。在背景工作線程中，此數據成員的值繼承自其父線程。

`CWinThread::m_pMainWnd`

使用此資料成員來儲存線程主視窗物件的指標。

CWnd* m_pMainWnd;

備註

當所 m_pMainWnd 參考的窗口關閉時，Microsoft Foundation Class Library 會自動終止您的線程。如果此線程是應用程式的主要線程，應用程式也會終止。如果這個資料成員是 NULL，則會使用應用程式 CWinApp 物件的主視窗來判斷終止線程的時機。 m_pMainWnd 是類型的 CWnd*公用變數。

一般而言，當您覆寫 InitInstance時，會設定這個成員變數。在背景工作線程中，此數據成員的值繼承自其父線程。

`CWinThread::OnIdle`

覆寫此成員函式以執行閑置時間處理。

virtual BOOL OnIdle(LONG lCount);

參數

lCount
每次呼叫線程消息隊列為空白時，都會 OnIdle 遞增計數器。每次處理新訊息時，此計數會重設為 0。您可以使用 lCount 參數來判斷線程閑置的相對時間長度，而不需要處理訊息。

傳回值

非零接收更多閑置處理時間;如果不再需要閑置的處理時間，則為 0。

備註

OnIdle 當線程的訊息佇列是空的時，會在預設訊息循環中呼叫。使用覆寫呼叫您自己的背景閑置處理程式工作。

OnIdle 應該傳回 0，表示不需要額外的閑置處理時間。 lCount每次OnIdle呼叫消息隊列為空時，都會遞增參數，而且每次處理新訊息時都會重設為 0。您可以根據這個計數呼叫不同的閑置例程。

這個成員函式的預設實作會從記憶體釋放暫存物件和未使用的動態連結庫。

這個成員函式只會用於使用者介面線程中。

由於應用程式在傳回之前 OnIdle 無法處理訊息，所以請勿在此函式中執行冗長的工作。

`CWinThread::operator HANDLE`

擷取物件的句柄 CWinThread 。

operator HANDLE() const;

傳回值

如果成功，線程物件的句柄;否則為 NULL。

備註

使用句柄直接呼叫 Windows API。

`CWinThread::PostThreadMessage`

呼叫以將使用者定義訊息張貼至另一個 CWinThread 物件。

BOOL PostThreadMessage(
    UINT message,
    WPARAM wParam,
    LPARAM lParam);

參數

message
使用者定義訊息的識別碼。

wParam
第一個訊息參數。

lParam
第二個訊息參數。

傳回值

如果成功則為非零；否則為 0。

備註

張貼的訊息會由訊息對應巨集 ON_THREAD_MESSAGE對應至適當的訊息處理程式。

注意

當您呼叫 PostThreadMessage時，訊息會放在線程的消息佇列中。不過，由於以這種方式張貼的訊息與窗口無關，因此MFC不會將它們分派至訊息或命令處理程式。若要處理這些訊息，請覆寫 PreTranslateMessage() 衍生類別的 CWinApp函式，並手動處理訊息。

`CWinThread::PreTranslateMessage`

覆寫此函式以在分派至 Windows 函 TranslateMessage 式和 DispatchMessage之前篩選視窗訊息。

virtual BOOL PreTranslateMessage(MSG* pMsg);

參數

pMsg
指向 MSG 包含要處理之訊息的結構。

傳回值

如果訊息已在中 PreTranslateMessage 完全處理，且不應該進一步處理，則為非零。如果訊息應該以正常方式處理，則為零。

備註

這個成員函式只會用於使用者介面線程中。

`CWinThread::ProcessMessageFilter`

架構的攔截函式會呼叫此成員函式，以篩選和回應特定 Windows 訊息。

virtual BOOL ProcessMessageFilter(
    int code,
    LPMSG lpMsg);

參數

code
指定勾點程序代碼。此成員函式會使用程式代碼來判斷如何處理 lpMsg。

lpMsg
Windows MSG 結構的指標。

傳回值

如果處理訊息，則為非零;否則為 0。

備註

攔截函式會先處理事件，再傳送至應用程式的一般訊息處理。

如果您覆寫此進階功能，請務必呼叫基類版本，以維護架構的攔截處理。

`CWinThread::ProcessWndProcException`

每當處理程式未攔截在其中一個線程訊息或命令處理程式中擲回的例外狀況時，架構就會呼叫這個成員函式。

virtual LRESULT ProcessWndProcException(
    CException* e,
    const MSG* pMsg);

參數

e
指向未處理的例外狀況。

pMsg
MSG指向結構，其中包含導致架構擲回例外狀況之 Windows 訊息的相關信息。

傳回值

如果產生例外狀況，則為 -1，否則為 WM_CREATE 0。

備註

請勿直接呼叫這個成員函式。

這個成員函式的預設實作只會處理從下列訊息產生的例外狀況：

Command	動作
`WM_CREATE`	失敗。
`WM_PAINT`	驗證受影響的視窗，以避免產生另一則 `WM_PAINT` 訊息。

覆寫此成員函式以提供例外狀況的全域處理。只有在您想要顯示預設行為時，才呼叫基底功能。

此成員函式只會用於具有訊息幫浦的線程中。

`CWinThread::PumpMessage`

包含線程的訊息迴圈。

virtual BOOL PumpMessage();

備註

PumpMessage 包含線程的訊息迴圈。 PumpMessage 由呼叫 CWinThread 以提取線程的訊息。您可以直接呼叫 PumpMessage 以強制處理訊息，也可以覆寫 PumpMessage 以變更其預設行為。

建議僅針對進階使用者直接呼叫 PumpMessage 並覆寫其默認行為。

`CWinThread::ResumeThread`

呼叫以繼續執行成員函式暫停 SuspendThread 的線程，或使用旗標建立的 CREATE_SUSPENDED 線程。

DWORD ResumeThread();

傳回值

如果成功，則線程先前的暫停計數; 0xFFFFFFFF 否則。如果傳回值為零，則目前的線程未暫停。如果傳回值是其中一個，線程已暫停，但現在會重新啟動。任何大於一個的傳回值表示線程會維持暫停狀態。

備註

目前線程的暫停計數會減少一個。如果暫停計數縮減為零，線程會繼續執行;否則線程會維持暫停狀態。

`CWinThread::Run`

提供使用者介面線程的預設訊息迴圈。

virtual int Run();

傳回值

int線程所傳回的值。呼叫即可擷 GetExitCodeThread取此值。

備註

Run 取得並分派 Windows 訊息，直到應用程式收到 WM_QUIT 訊息為止。如果線程的訊息佇列目前未包含任何訊息， Run 則呼叫 OnIdle 以執行閑置時間處理。傳入訊息會移至成員函式以進行特殊處理，然後移至 PreTranslateMessage Windows 函 TranslateMessage 式進行標準鍵盤翻譯。最後，會 DispatchMessage 呼叫 Windows 函式。

Run 很少被覆寫，但您可以覆寫它以實作特殊行為。

這個成員函式只會用於使用者介面線程中。

`CWinThread::SetThreadPriority`

此函式會設定目前線程在其優先順序類別內的優先順序層級。

BOOL SetThreadPriority(int nPriority);

參數

nPriority
指定其優先順序類別內的新線程優先順序層級。此參數必須是下列其中一個值，從優先順序最高到最低：

THREAD_PRIORITY_TIME_CRITICAL
THREAD_PRIORITY_HIGHEST
THREAD_PRIORITY_ABOVE_NORMAL
THREAD_PRIORITY_NORMAL
THREAD_PRIORITY_BELOW_NORMAL
THREAD_PRIORITY_LOWEST
THREAD_PRIORITY_IDLE

如需這些優先順序的詳細資訊，請參閱 SetThreadPriority Windows SDK。

傳回值

如果函式成功，則為非零;否則為 0。

備註

它只能在成功傳回之後 CreateThread 呼叫。

`CWinThread::SuspendThread`

遞增目前線程的暫停計數。

DWORD SuspendThread();

傳回值

如果成功，則線程先前的暫停計數; 0xFFFFFFFF 否則。

備註

如果任何線程的暫停計數高於零，該線程就不會執行。您可以藉由呼叫 ResumeThread 成員函式來繼續線程。

另請參閱

CCmdTarget 類
 階層架構圖表
 CWinApp 類
 CCmdTarget 類

共用方式為

CWinThread 類別

語法

成員

公用建構函式

公用方法

公用運算子

公用資料成員

備註

繼承階層架構

需求

CWinThread::CreateThread

參數

傳回值

備註

CWinThread::CWinThread

備註

CWinThread::ExitInstance

傳回值

備註

CWinThread::GetMainWnd

傳回值

備註

CWinThread::GetThreadPriority

傳回值

CWinThread::InitInstance

傳回值

備註

CWinThread::IsIdleMessage

參數

傳回值

備註

CWinThread::m_bAutoDelete

備註

CWinThread::m_hThread

備註

CWinThread::m_nThreadID

備註

範例

CWinThread::m_pActiveWnd

備註

CWinThread::m_pMainWnd

備註

CWinThread::OnIdle

參數

傳回值

備註

CWinThread::operator HANDLE

傳回值

備註

CWinThread::PostThreadMessage

參數

傳回值

備註

CWinThread::PreTranslateMessage

參數

傳回值

備註

CWinThread::ProcessMessageFilter

參數

傳回值

備註

CWinThread::ProcessWndProcException

參數

傳回值

備註

CWinThread::PumpMessage

備註

CWinThread::ResumeThread

傳回值

備註

CWinThread::Run

傳回值

備註

CWinThread::SetThreadPriority

參數

傳回值

備註

CWinThread::SuspendThread

傳回值

`CWinThread` 類別

`CWinThread::CreateThread`

`CWinThread::CWinThread`

`CWinThread::ExitInstance`

`CWinThread::GetMainWnd`

`CWinThread::GetThreadPriority`

`CWinThread::InitInstance`

`CWinThread::IsIdleMessage`

`CWinThread::m_bAutoDelete`

`CWinThread::m_hThread`

`CWinThread::m_nThreadID`

`CWinThread::m_pActiveWnd`

`CWinThread::m_pMainWnd`

`CWinThread::OnIdle`

`CWinThread::operator HANDLE`

`CWinThread::PostThreadMessage`

`CWinThread::PreTranslateMessage`

`CWinThread::ProcessMessageFilter`

`CWinThread::ProcessWndProcException`

`CWinThread::PumpMessage`

`CWinThread::ResumeThread`

`CWinThread::Run`

`CWinThread::SetThreadPriority`

`CWinThread::SuspendThread`