ThreadPool.RegisterWaitForSingleObject 方法

定義

命名空間:

System.Threading

組件:

System.Threading.ThreadPool.dll

註冊正在等候 WaitHandle 的委派。

多載

RegisterWaitForSingleObject(WaitHandle, WaitOrTimerCallback, Object, UInt32, Boolean)	指定 32 位元帶正負號的整數表示逾時值 (以毫秒為單位)，藉此註冊要等候 WaitHandle 的委派。
RegisterWaitForSingleObject(WaitHandle, WaitOrTimerCallback, Object, TimeSpan, Boolean)	指定 WaitHandle 值表示逾時值，藉此註冊要等候 TimeSpan 的委派。
RegisterWaitForSingleObject(WaitHandle, WaitOrTimerCallback, Object, Int32, Boolean)	指定 32 位元帶正負號的整數表示逾時值 (以毫秒為單位)，藉此註冊要等候 WaitHandle 的委派。
RegisterWaitForSingleObject(WaitHandle, WaitOrTimerCallback, Object, Int64, Boolean)	指定 64 位元帶正負號的整數表示逾時值 (以毫秒為單位)，藉此註冊要等候 WaitHandle 的委派。

RegisterWaitForSingleObject(WaitHandle, WaitOrTimerCallback, Object, UInt32, Boolean)

來源:

ThreadPoolWorkQueue.cs

重要

此 API 不符合 CLS 規範。

指定 32 位元帶正負號的整數表示逾時值 (以毫秒為單位)，藉此註冊要等候 WaitHandle 的委派。

public:
 static System::Threading::RegisteredWaitHandle ^ RegisterWaitForSingleObject(System::Threading::WaitHandle ^ waitObject, System::Threading::WaitOrTimerCallback ^ callBack, System::Object ^ state, System::UInt32 millisecondsTimeOutInterval, bool executeOnlyOnce);

[System.CLSCompliant(false)]
[System.Runtime.Versioning.UnsupportedOSPlatform("browser")]
public static System.Threading.RegisteredWaitHandle RegisterWaitForSingleObject (System.Threading.WaitHandle waitObject, System.Threading.WaitOrTimerCallback callBack, object? state, uint millisecondsTimeOutInterval, bool executeOnlyOnce);

[<System.CLSCompliant(false)>]
[<System.Runtime.Versioning.UnsupportedOSPlatform("browser")>]
static member RegisterWaitForSingleObject : System.Threading.WaitHandle * System.Threading.WaitOrTimerCallback * obj * uint32 * bool -> System.Threading.RegisteredWaitHandle

Public Shared Function RegisterWaitForSingleObject (waitObject As WaitHandle, callBack As WaitOrTimerCallback, state As Object, millisecondsTimeOutInterval As UInteger, executeOnlyOnce As Boolean) As RegisteredWaitHandle

參數

waitObject

WaitHandle

要註冊的 WaitHandle。 使用 WaitHandle，而不要使用 Mutex。

callBack

WaitOrTimerCallback

通知 waitObject 參數時要呼叫的 WaitOrTimerCallback 委派。

state

Object

傳送至委派的物件。

millisecondsTimeOutInterval

UInt32

逾時以毫秒為單位。 如果 millisecondsTimeOutInterval 參數為 0 (零)，函式會測試物件的狀態並立即傳回。 如果 millisecondsTimeOutInterval 為 -1，則絕對不會耗用函式的逾時間隔。

executeOnlyOnce

Boolean

true 表示在呼叫委派之後，執行緒將不再等候 waitObject 參數；false 表示每當等候作業完成即重設計時器，直到移除註冊等候作業為止。

傳回

RegisteredWaitHandle

可用來取消已註冊之等候作業的 RegisteredWaitHandle。

屬性

CLSCompliantAttribute UnsupportedOSPlatformAttribute

例外狀況

ArgumentOutOfRangeException

millisecondsTimeOutInterval 參數小於 -1。

範例

下列範例示範如何在發出指定的等候句柄時，使用 RegisterWaitForSingleObject 方法來執行指定的回呼方法。 在這裡範例中，回呼方法是 WaitProc，而等候句柄是 AutoResetEvent。

此範例會定義類別 TaskInfo ，以保存在執行時傳遞至回呼的資訊。 此範例會 TaskInfo 建立 物件，並指派一些字串數據。 方法傳RegisterWaitForSingleObject回的 TaskInfo 會指派給 Handle 物件的欄位，讓回呼方法可以存取 RegisteredWaitHandle。RegisteredWaitHandle

除了指定要TaskInfo傳遞至回呼方法的物件之外，對方法的呼叫RegisterWaitForSingleObject還會指定要AutoResetEvent等候的工作、代表WaitProc回呼方法的委派、WaitOrTimerCallback一秒逾時間隔和多個回呼。

當主線程藉由呼叫 其 Set 方法發出訊AutoResetEvent號時，WaitOrTimerCallback會叫用委派。 方法 WaitProc 會測試 RegisteredWaitHandle 以判斷是否發生逾時。 如果因為已發出等候句柄而叫用回呼，則方法會取消註冊 RegisteredWaitHandle，WaitProc停止其他回呼。 在逾時的情況下，工作會繼續等候。 方法會 WaitProc 以將訊息列印至主控台結束。

using namespace System;
using namespace System::Threading;

// TaskInfo contains data that will be passed to the callback
// method.
public ref class TaskInfo
{
public:
   TaskInfo()
   {
      Handle = nullptr;
      OtherInfo = "default";
   }

   RegisteredWaitHandle^ Handle;
   String^ OtherInfo;
};

ref class Example
{
public:

   // The callback method executes when the registered wait times out,
   // or when the WaitHandle (in this case AutoResetEvent) is signaled.
   // WaitProc unregisters the WaitHandle the first time the event is 
   // signaled.
   static void WaitProc( Object^ state, bool timedOut )
   {
      
      // The state Object must be cast to the correct type, because the
      // signature of the WaitOrTimerCallback delegate specifies type
      // Object.
      TaskInfo^ ti = static_cast<TaskInfo^>(state);
      String^ cause = "TIMED OUT";
      if (  !timedOut )
      {
         cause = "SIGNALED";
         
         // If the callback method executes because the WaitHandle is
         // signaled, stop future execution of the callback method
         // by unregistering the WaitHandle.
         if ( ti->Handle != nullptr )
                  ti->Handle->Unregister( nullptr );
      }

      Console::WriteLine( "WaitProc( {0}) executes on thread {1}; cause = {2}.", ti->OtherInfo, Thread::CurrentThread->GetHashCode(), cause );
   }

};

int main()
{
   
   // The main thread uses AutoResetEvent to signal the
   // registered wait handle, which executes the callback
   // method.
   AutoResetEvent^ ev = gcnew AutoResetEvent( false );
   TaskInfo^ ti = gcnew TaskInfo;
   ti->OtherInfo = "First task";
   
   // The TaskInfo for the task includes the registered wait
   // handle returned by RegisterWaitForSingleObject.  This
   // allows the wait to be terminated when the object has
   // been signaled once (see WaitProc).
   ti->Handle = ThreadPool::RegisterWaitForSingleObject( ev, gcnew WaitOrTimerCallback( Example::WaitProc ), ti, 1000, false );
   
   // The main thread waits three seconds, to demonstrate the
   // time-outs on the queued thread, and then signals.
   Thread::Sleep( 3100 );
   Console::WriteLine( "Main thread signals." );
   ev->Set();
   
   // The main thread sleeps, which should give the callback
   // method time to execute.  If you comment out this line, the
   // program usually ends before the ThreadPool thread can execute.
   Thread::Sleep( 1000 );
   
   // If you start a thread yourself, you can wait for it to end
   // by calling Thread::Join.  This option is not available with 
   // thread pool threads.
   return 0;
}

using System;
using System.Threading;

// TaskInfo contains data that will be passed to the callback
// method.
public class TaskInfo {
    public RegisteredWaitHandle Handle = null;
    public string OtherInfo = "default";
}

public class Example {
    public static void Main(string[] args) {
        // The main thread uses AutoResetEvent to signal the
        // registered wait handle, which executes the callback
        // method.
        AutoResetEvent ev = new AutoResetEvent(false);

        TaskInfo ti = new TaskInfo();
        ti.OtherInfo = "First task";
        // The TaskInfo for the task includes the registered wait
        // handle returned by RegisterWaitForSingleObject.  This
        // allows the wait to be terminated when the object has
        // been signaled once (see WaitProc).
        ti.Handle = ThreadPool.RegisterWaitForSingleObject(
            ev,
            new WaitOrTimerCallback(WaitProc),
            ti,
            1000,
            false
        );

        // The main thread waits three seconds, to demonstrate the
        // time-outs on the queued thread, and then signals.
        Thread.Sleep(3100);
        Console.WriteLine("Main thread signals.");
        ev.Set();

        // The main thread sleeps, which should give the callback
        // method time to execute.  If you comment out this line, the
        // program usually ends before the ThreadPool thread can execute.
        Thread.Sleep(1000);
        // If you start a thread yourself, you can wait for it to end
        // by calling Thread.Join.  This option is not available with 
        // thread pool threads.
    }
   
    // The callback method executes when the registered wait times out,
    // or when the WaitHandle (in this case AutoResetEvent) is signaled.
    // WaitProc unregisters the WaitHandle the first time the event is 
    // signaled.
    public static void WaitProc(object state, bool timedOut) {
        // The state object must be cast to the correct type, because the
        // signature of the WaitOrTimerCallback delegate specifies type
        // Object.
        TaskInfo ti = (TaskInfo) state;

        string cause = "TIMED OUT";
        if (!timedOut) {
            cause = "SIGNALED";
            // If the callback method executes because the WaitHandle is
            // signaled, stop future execution of the callback method
            // by unregistering the WaitHandle.
            if (ti.Handle != null)
                ti.Handle.Unregister(null);
        } 

        Console.WriteLine("WaitProc( {0} ) executes on thread {1}; cause = {2}.",
            ti.OtherInfo, 
            Thread.CurrentThread.GetHashCode().ToString(), 
            cause
        );
    }
}

Imports System.Threading

' TaskInfo contains data that will be passed to the callback
' method.
Public Class TaskInfo
    public Handle As RegisteredWaitHandle = Nothing
    public OtherInfo As String = "default"
End Class

Public Class Example

    <MTAThread> _
    Public Shared Sub Main()
        ' The main thread uses AutoResetEvent to signal the
        ' registered wait handle, which executes the callback
        ' method.
        Dim ev As New AutoResetEvent(false)

        Dim ti As New TaskInfo()
        ti.OtherInfo = "First task"
        ' The TaskInfo for the task includes the registered wait
        ' handle returned by RegisterWaitForSingleObject.  This
        ' allows the wait to be terminated when the object has
        ' been signaled once (see WaitProc).
        ti.Handle = ThreadPool.RegisterWaitForSingleObject( _
            ev, _
            New WaitOrTimerCallback(AddressOf WaitProc), _
            ti, _
            1000, _
            false _
        )

        ' The main thread waits about three seconds, to demonstrate 
        ' the time-outs on the queued task, and then signals.
        Thread.Sleep(3100)
        Console.WriteLine("Main thread signals.")
        ev.Set()

        ' The main thread sleeps, which should give the callback
        ' method time to execute.  If you comment out this line, the
        ' program usually ends before the ThreadPool thread can execute.
        Thread.Sleep(1000)
        ' If you start a thread yourself, you can wait for it to end
        ' by calling Thread.Join.  This option is not available with 
        ' thread pool threads.
    End Sub
   
    ' The callback method executes when the registered wait times out,
    ' or when the WaitHandle (in this case AutoResetEvent) is signaled.
    ' WaitProc unregisters the WaitHandle the first time the event is 
    ' signaled.
    Public Shared Sub WaitProc(state As Object, timedOut As Boolean)
        ' The state object must be cast to the correct type, because the
        ' signature of the WaitOrTimerCallback delegate specifies type
        ' Object.
        Dim ti As TaskInfo = CType(state, TaskInfo)

        Dim cause As String = "TIMED OUT"
        If Not timedOut Then
            cause = "SIGNALED"
            ' If the callback method executes because the WaitHandle is
            ' signaled, stop future execution of the callback method
            ' by unregistering the WaitHandle.
            If Not ti.Handle Is Nothing Then
                ti.Handle.Unregister(Nothing)
            End If
        End If 

        Console.WriteLine("WaitProc( {0} ) executes on thread {1}; cause = {2}.", _
            ti.OtherInfo, _
            Thread.CurrentThread.GetHashCode().ToString(), _
            cause _
        )
    End Sub
End Class

備註

當您完成使用 RegisteredWaitHandle 這個方法所傳回的 時，請呼叫其 RegisteredWaitHandle.Unregister 方法來釋放等候句柄的參考。 即使您為 executeOnlyOnce指定 true ，也建議您一律呼叫 RegisteredWaitHandle.Unregister 方法。 如果您呼叫 方法， RegisteredWaitHandle.Unregister 而不是根據已註冊的等候句柄完成項而定，垃圾收集更有效率。

方法會將 RegisterWaitForSingleObject 指定的委派排入線程集區。 當發生下列其中一項時，背景工作線程會執行委派：

• 指定的物件處於訊號狀態。
• 逾時間隔經過。

方法 RegisterWaitForSingleObject 會檢查指定之物件的 WaitHandle目前狀態。 如果物件的狀態未簽署，則方法會註冊等候作業。 等候作業是由線程集區中的線程執行。 當物件的狀態變成訊號或逾時間隔經過時，背景工作線程會執行委派。 timeOutInterval如果參數不是 0 (零) 且 executeOnlyOnce 參數為 false，則每次發出訊號或逾時間隔時，都會重設定時器。

重要

Mutex使用的 waitObject 不提供回呼的相互排除，因為基礎 Windows API 會使用預設WT_EXECUTEDEFAULT旗標，因此每個回呼都會分派在不同的線程集區線程上。 而不是 Mutex，請使用 Semaphore 計數上限為 1 的 。

若要取消等候作業，請呼叫 RegisteredWaitHandle.Unregister 方法。

等候線程會使用 Win32 WaitForMultipleObjects 函式來監視已註冊的等候作業。 因此，如果您必須在多次呼叫 RegisterWaitForSingleObject中使用相同的原生操作系統句柄，則必須使用 Win32 DuplicateHandle 函式複製句柄。 請注意，您不應該對傳遞至 RegisterWaitForSingleObject的事件對象發出脈衝，因為等候線程可能不會偵測到事件在重設之前發出訊號。

傳回之前，函式會修改某些同步處理物件類型的狀態。 修改只會發生在發出訊號狀態導致滿足等候條件的物件。 例如，旗號的計數會減少一個。

另請參閱

• 受控線程集區

RegisterWaitForSingleObject(WaitHandle, WaitOrTimerCallback, Object, TimeSpan, Boolean)

來源:

ThreadPoolWorkQueue.cs

指定 WaitHandle 值表示逾時值，藉此註冊要等候 TimeSpan 的委派。

public:
 static System::Threading::RegisteredWaitHandle ^ RegisterWaitForSingleObject(System::Threading::WaitHandle ^ waitObject, System::Threading::WaitOrTimerCallback ^ callBack, System::Object ^ state, TimeSpan timeout, bool executeOnlyOnce);

[System.Runtime.Versioning.UnsupportedOSPlatform("browser")]
public static System.Threading.RegisteredWaitHandle RegisterWaitForSingleObject (System.Threading.WaitHandle waitObject, System.Threading.WaitOrTimerCallback callBack, object? state, TimeSpan timeout, bool executeOnlyOnce);

[<System.Runtime.Versioning.UnsupportedOSPlatform("browser")>]
static member RegisterWaitForSingleObject : System.Threading.WaitHandle * System.Threading.WaitOrTimerCallback * obj * TimeSpan * bool -> System.Threading.RegisteredWaitHandle

Public Shared Function RegisterWaitForSingleObject (waitObject As WaitHandle, callBack As WaitOrTimerCallback, state As Object, timeout As TimeSpan, executeOnlyOnce As Boolean) As RegisteredWaitHandle

參數

waitObject

WaitHandle

要註冊的 WaitHandle。 使用 WaitHandle，而不要使用 Mutex。

callBack

WaitOrTimerCallback

通知 waitObject 參數時要呼叫的 WaitOrTimerCallback 委派。

state

Object

傳送至委派的物件。

timeout

TimeSpan

以 TimeSpan 表示的逾時值。 如果 timeout 為 0 (零)，則函式會測試物件的狀態並立即傳回。 如果 timeout 為 -1，則絕對不會耗用函式的逾時間隔。

executeOnlyOnce

Boolean

true 表示在呼叫委派之後，執行緒將不再等候 waitObject 參數；false 表示每當等候作業完成即重設計時器，直到移除註冊等候作業為止。

傳回

RegisteredWaitHandle

封裝原生控制代碼的 RegisteredWaitHandle。

屬性

UnsupportedOSPlatformAttribute

例外狀況

ArgumentOutOfRangeException

timeout 參數小於 -1。

NotSupportedException

參數 timeout 大於 Int32.MaxValue。

備註

當您完成使用 RegisteredWaitHandle 這個方法所傳回的 時，請呼叫其 RegisteredWaitHandle.Unregister 方法來釋放等候句柄的參考。 即使您為 executeOnlyOnce指定 true ，也建議您一律呼叫 RegisteredWaitHandle.Unregister 方法。 如果您呼叫 方法， RegisteredWaitHandle.Unregister 而不是根據已註冊的等候句柄完成項而定，垃圾收集更有效率。

方法會將 RegisterWaitForSingleObject 指定的委派排入線程集區。 當發生下列其中一項時，背景工作線程會執行委派：

• 指定的物件處於訊號狀態。
• 逾時間隔經過。

方法 RegisterWaitForSingleObject 會檢查指定之物件的 WaitHandle目前狀態。 如果物件的狀態未簽署，則方法會註冊等候作業。 等候作業是由線程集區中的線程執行。 當物件的狀態變成訊號或逾時間隔經過時，背景工作線程會執行委派。 timeOutInterval如果參數不是 0 (零) 且 executeOnlyOnce 參數為 false，則每次發出訊號或逾時間隔時，都會重設定時器。

重要

Mutex使用的 waitObject 不提供回呼的相互排除，因為基礎 Windows API 會使用預設WT_EXECUTEDEFAULT旗標，因此每個回呼都會分派在不同的線程集區線程上。 而不是 Mutex，請使用 Semaphore 計數上限為 1 的 。

若要取消等候作業，請呼叫 RegisteredWaitHandle.Unregister 方法。

等候線程會使用 Win32 WaitForMultipleObjects 函式來監視已註冊的等候作業。 因此，如果您必須在多次呼叫 RegisterWaitForSingleObject中使用相同的原生操作系統句柄，則必須使用 Win32 DuplicateHandle 函式複製句柄。 請注意，您不應該對傳遞至 RegisterWaitForSingleObject的事件對象發出脈衝，因為等候線程可能不會偵測到事件在重設之前發出訊號。

傳回之前，函式會修改某些同步處理物件類型的狀態。 修改只會發生在發出訊號狀態導致滿足等候條件的物件。 例如，旗號的計數會減少一個。

另請參閱

• 受控線程集區

RegisterWaitForSingleObject(WaitHandle, WaitOrTimerCallback, Object, Int32, Boolean)

來源:

ThreadPoolWorkQueue.cs

指定 32 位元帶正負號的整數表示逾時值 (以毫秒為單位)，藉此註冊要等候 WaitHandle 的委派。

public:
 static System::Threading::RegisteredWaitHandle ^ RegisterWaitForSingleObject(System::Threading::WaitHandle ^ waitObject, System::Threading::WaitOrTimerCallback ^ callBack, System::Object ^ state, int millisecondsTimeOutInterval, bool executeOnlyOnce);

[System.Runtime.Versioning.UnsupportedOSPlatform("browser")]
public static System.Threading.RegisteredWaitHandle RegisterWaitForSingleObject (System.Threading.WaitHandle waitObject, System.Threading.WaitOrTimerCallback callBack, object? state, int millisecondsTimeOutInterval, bool executeOnlyOnce);

[<System.Runtime.Versioning.UnsupportedOSPlatform("browser")>]
static member RegisterWaitForSingleObject : System.Threading.WaitHandle * System.Threading.WaitOrTimerCallback * obj * int * bool -> System.Threading.RegisteredWaitHandle

Public Shared Function RegisterWaitForSingleObject (waitObject As WaitHandle, callBack As WaitOrTimerCallback, state As Object, millisecondsTimeOutInterval As Integer, executeOnlyOnce As Boolean) As RegisteredWaitHandle

參數

waitObject

WaitHandle

要註冊的 WaitHandle。 使用 WaitHandle，而不要使用 Mutex。

callBack

WaitOrTimerCallback

通知 waitObject 參數時要呼叫的 WaitOrTimerCallback 委派。

state

Object

傳遞至委派的物件。

millisecondsTimeOutInterval

Int32

逾時以毫秒為單位。 如果 millisecondsTimeOutInterval 參數為 0 (零)，函式會測試物件的狀態並立即傳回。 如果 millisecondsTimeOutInterval 為 -1，則絕對不會耗用函式的逾時間隔。

executeOnlyOnce

Boolean

true 表示在呼叫委派之後，執行緒將不再等候 waitObject 參數；false 表示每當等候作業完成即重設計時器，直到移除註冊等候作業為止。

傳回

RegisteredWaitHandle

封裝原生控制代碼的 RegisteredWaitHandle。

屬性

UnsupportedOSPlatformAttribute

例外狀況

ArgumentOutOfRangeException

millisecondsTimeOutInterval 參數小於 -1。

備註

當您完成使用 RegisteredWaitHandle 這個方法所傳回的 時，請呼叫其 RegisteredWaitHandle.Unregister 方法來釋放等候句柄的參考。 即使您為 executeOnlyOnce指定 true ，也建議您一律呼叫 RegisteredWaitHandle.Unregister 方法。 如果您呼叫 方法， RegisteredWaitHandle.Unregister 而不是根據已註冊的等候句柄完成項而定，垃圾收集更有效率。

方法會將 RegisterWaitForSingleObject 指定的委派排入線程集區。 當發生下列其中一項時，背景工作線程會執行委派：

• 指定的物件處於訊號狀態。
• 逾時間隔經過。

方法 RegisterWaitForSingleObject 會檢查指定之物件的 WaitHandle目前狀態。 如果物件的狀態未簽署，則方法會註冊等候作業。 等候作業是由線程集區中的線程執行。 當物件的狀態變成訊號或逾時間隔經過時，背景工作線程會執行委派。 timeOutInterval如果參數不是 0 (零) 且 executeOnlyOnce 參數為 false，則每次發出訊號或逾時間隔時，都會重設定時器。

重要

Mutex使用的 waitObject 不提供回呼的相互排除，因為基礎 Windows API 會使用預設WT_EXECUTEDEFAULT旗標，因此每個回呼都會分派在不同的線程集區線程上。 而不是 Mutex，請使用 Semaphore 計數上限為 1 的 。

若要取消等候作業，請呼叫 RegisteredWaitHandle.Unregister 方法。

等候線程會使用 Win32 WaitForMultipleObjects 函式來監視已註冊的等候作業。 因此，如果您必須在多次呼叫 RegisterWaitForSingleObject中使用相同的原生操作系統句柄，則必須使用 Win32 DuplicateHandle 函式複製句柄。 請注意，您不應該對傳遞至 RegisterWaitForSingleObject的事件對象發出脈衝，因為等候線程可能不會偵測到事件在重設之前發出訊號。

傳回之前，函式會修改某些同步處理物件類型的狀態。 修改只會發生在發出訊號狀態導致滿足等候條件的物件。 例如，旗號的計數會減少一個。

另請參閱

• 受控線程集區

RegisterWaitForSingleObject(WaitHandle, WaitOrTimerCallback, Object, Int64, Boolean)

來源:

ThreadPoolWorkQueue.cs

指定 64 位元帶正負號的整數表示逾時值 (以毫秒為單位)，藉此註冊要等候 WaitHandle 的委派。

public:
 static System::Threading::RegisteredWaitHandle ^ RegisterWaitForSingleObject(System::Threading::WaitHandle ^ waitObject, System::Threading::WaitOrTimerCallback ^ callBack, System::Object ^ state, long millisecondsTimeOutInterval, bool executeOnlyOnce);

[System.Runtime.Versioning.UnsupportedOSPlatform("browser")]
public static System.Threading.RegisteredWaitHandle RegisterWaitForSingleObject (System.Threading.WaitHandle waitObject, System.Threading.WaitOrTimerCallback callBack, object? state, long millisecondsTimeOutInterval, bool executeOnlyOnce);

[<System.Runtime.Versioning.UnsupportedOSPlatform("browser")>]
static member RegisterWaitForSingleObject : System.Threading.WaitHandle * System.Threading.WaitOrTimerCallback * obj * int64 * bool -> System.Threading.RegisteredWaitHandle

Public Shared Function RegisterWaitForSingleObject (waitObject As WaitHandle, callBack As WaitOrTimerCallback, state As Object, millisecondsTimeOutInterval As Long, executeOnlyOnce As Boolean) As RegisteredWaitHandle

參數

waitObject

WaitHandle

要註冊的 WaitHandle。 使用 WaitHandle，而不要使用 Mutex。

callBack

WaitOrTimerCallback

通知 waitObject 參數時要呼叫的 WaitOrTimerCallback 委派。

state

Object

傳送至委派的物件。

millisecondsTimeOutInterval

Int64

逾時以毫秒為單位。 如果 millisecondsTimeOutInterval 參數為 0 (零)，函式會測試物件的狀態並立即傳回。 如果 millisecondsTimeOutInterval 為 -1，則絕對不會耗用函式的逾時間隔。

executeOnlyOnce

Boolean

true 表示在呼叫委派之後，執行緒將不再等候 waitObject 參數；false 表示每當等候作業完成即重設計時器，直到移除註冊等候作業為止。

傳回

RegisteredWaitHandle

封裝原生控制代碼的 RegisteredWaitHandle。

屬性

UnsupportedOSPlatformAttribute

例外狀況

ArgumentOutOfRangeException

millisecondsTimeOutInterval 參數小於 -1。

備註

當您完成使用 RegisteredWaitHandle 這個方法所傳回的 時，請呼叫其 RegisteredWaitHandle.Unregister 方法來釋放等候句柄的參考。 即使您為 executeOnlyOnce指定 true ，也建議您一律呼叫 RegisteredWaitHandle.Unregister 方法。 如果您呼叫 方法， RegisteredWaitHandle.Unregister 而不是根據已註冊的等候句柄完成項而定，垃圾收集更有效率。

方法會將 RegisterWaitForSingleObject 指定的委派排入線程集區。 當發生下列其中一項時，背景工作線程會執行委派：

• 指定的物件處於訊號狀態。
• 逾時間隔經過。

方法 RegisterWaitForSingleObject 會檢查指定之物件的 WaitHandle目前狀態。 如果物件的狀態未簽署，則方法會註冊等候作業。 等候作業是由線程集區中的線程執行。 當物件的狀態變成訊號或逾時間隔經過時，背景工作線程會執行委派。 timeOutInterval如果參數不是 0 (零) 且 executeOnlyOnce 參數為 false，則每次發出訊號或逾時間隔時，都會重設定時器。

重要

Mutex使用的 waitObject 不提供回呼的相互排除，因為基礎 Windows API 會使用預設WT_EXECUTEDEFAULT旗標，因此每個回呼都會分派在不同的線程集區線程上。 而不是 Mutex，請使用 Semaphore 計數上限為 1 的 。

若要取消等候作業，請呼叫 RegisteredWaitHandle.Unregister 方法。

等候線程會使用 Win32 WaitForMultipleObjects 函式來監視已註冊的等候作業。 因此，如果您必須在多次呼叫 RegisterWaitForSingleObject中使用相同的原生操作系統句柄，則必須使用 Win32 DuplicateHandle 函式複製句柄。 請注意，您不應該對傳遞至 RegisterWaitForSingleObject的事件對象發出脈衝，因為等候線程可能不會偵測到事件在重設之前發出訊號。

傳回之前，函式會修改某些同步處理物件類型的狀態。 修改只會發生在發出訊號狀態導致滿足等候條件的物件。 例如，旗號的計數會減少一個。

另請參閱

• 受控線程集區