ThreadPool.RegisterWaitForSingleObject 方法

定义

命名空间:

System.Threading

程序集:

netstandard.dll, System.Threading.ThreadPool.dll

注册正在等待的 WaitHandle委托。

重载

名称	说明
RegisterWaitForSingleObject(WaitHandle, WaitOrTimerCallback, Object, UInt32, Boolean)	注册一个委托以等待 a WaitHandle，为超时指定 32 位无符号整数（以毫秒为单位）。
RegisterWaitForSingleObject(WaitHandle, WaitOrTimerCallback, Object, TimeSpan, Boolean)	注册一个委托以等待 a WaitHandle，并 TimeSpan 指定超时值。
RegisterWaitForSingleObject(WaitHandle, WaitOrTimerCallback, Object, Int32, Boolean)	注册一个委托以等待 a WaitHandle，为超时指定 32 位有符号整数（以毫秒为单位）。
RegisterWaitForSingleObject(WaitHandle, WaitOrTimerCallback, Object, Int64, Boolean)	注册一个委托以等待 a WaitHandle，为超时指定 64 位有符号整数（以毫秒为单位）。

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

Source:

ThreadPoolWorkQueue.cs

重要

此 API 不符合 CLS。

注册一个委托以等待 a WaitHandle，为超时指定 32 位无符号整数（以毫秒为单位）。

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

发出 WaitOrTimerCallback 参数信号时要调用的 waitObject 委托。

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 对象并为其分配一些字符串数据。 RegisteredWaitHandle方法返回RegisterWaitForSingleObject的函数将分配给Handle对象的字段TaskInfo，以便回调方法有权访问该RegisteredWaitHandle对象。

除了指定TaskInfo为传递给回调方法的对象外，对方法的调用RegisterWaitForSingleObject还指定AutoResetEvent任务将等待、表示回调方法的WaitOrTimerCallback委托、WaitProc一秒钟超时间隔和多个回调。

当主线程通过调用其AutoResetEvent方法发出信号Set时，WaitOrTimerCallback将调用委托。 该方法 WaitProc 测试 RegisteredWaitHandle 以确定是否发生超时。 如果调用回调是因为等待句柄已发出信号，该方法 WaitProc 将取消注册 RegisteredWaitHandle该回调，从而停止其他回调。 如果超时，任务将继续等待。 该方法 WaitProc 通过将消息打印到控制台结束。

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 以释放对等待句柄的引用。 建议始终调用 RegisteredWaitHandle.Unregister 该方法，即使指定 true 了 executeOnlyOnce此方法。 如果调用 RegisteredWaitHandle.Unregister 方法，而不是依赖于已注册的等待句柄的终结器，垃圾回收更高效。

该方法 RegisterWaitForSingleObject 将指定的委托排入线程池的队列。 发生以下任一情况时，辅助线程将执行委托：

• 指定的对象处于信号状态。
• 超时间隔已用。

该方法 RegisterWaitForSingleObject 检查指定对象的 WaitHandle当前状态。 如果对象的状态未对齐，该方法将注册等待操作。 等待操作由线程池中的线程执行。 当对象的状态发出信号或超时间隔过时，该委托由工作线程执行。 timeOutInterval如果参数不是 0（零），executeOnlyOnce并且参数为false，则每次发出事件信号或超时间隔时，都会重置计时器。

Important

对 Mutex 使用 waitObject 不会为回调提供相互排斥，因为基础Windows API 使用默认的 WT_EXECUTEDEFAULT 标志，因此每个回调在单独的线程池线程上调度。 而不是使用 Mutex最大计数为 1 的 A Semaphore 。

若要取消等待操作，请调用 RegisteredWaitHandle.Unregister 该方法。

等待线程使用 Win32 WaitForMultipleObjects 函数监视已注册的等待操作。 因此，如果必须在多个调用 RegisterWaitForSingleObject中使用同一本机操作系统句柄，则必须使用 Win32 DuplicateHandle 函数复制句柄。 请注意，不应对传递给 RegisterWaitForSingleObject的事件对象进行脉冲，因为等待线程可能无法检测到事件在重置之前发出信号。

在返回之前，该函数将修改某些类型的同步对象的状态。 仅针对发出信号状态导致满足等待条件的对象进行修改。 例如，信号灯计数减少一个。

另请参阅

• 托管线程池

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

Source:

ThreadPoolWorkQueue.cs

注册一个委托以等待 a 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

发出 WaitOrTimerCallback 参数信号时要调用的 waitObject 委托。

state

Object

传递给委托的对象。

timeout

TimeSpan

由 a TimeSpan. 表示的超时值。 如果 timeout 为 0（零），则函数将测试对象的状态并立即返回。 如果 timeout 为 -1，则函数的超时间隔永远不会过。

executeOnlyOnce

Boolean

true 如果指示线程在调用委托后不再等待 waitObject 参数， false 则指示每次等待操作完成时都会重置计时器，直到取消注册等待。

返回

RegisteredWaitHandle

封装 RegisteredWaitHandle 本机句柄的函数。

属性

UnsupportedOSPlatformAttribute

例外

ArgumentOutOfRangeException

参数 timeout 小于 -1。

NotSupportedException

参数 timeout 大于 Int32.MaxValue。

注解

使用 RegisteredWaitHandle 此方法返回的函数完成后，调用该方法 RegisteredWaitHandle.Unregister 以释放对等待句柄的引用。 建议始终调用 RegisteredWaitHandle.Unregister 该方法，即使指定 true 了 executeOnlyOnce此方法。 如果调用 RegisteredWaitHandle.Unregister 方法，而不是依赖于已注册的等待句柄的终结器，垃圾回收更高效。

该方法 RegisterWaitForSingleObject 将指定的委托排入线程池的队列。 发生以下任一情况时，辅助线程将执行委托：

• 指定的对象处于信号状态。
• 超时间隔已用。

该方法 RegisterWaitForSingleObject 检查指定对象的 WaitHandle当前状态。 如果对象的状态未对齐，该方法将注册等待操作。 等待操作由线程池中的线程执行。 当对象的状态发出信号或超时间隔过时，该委托由工作线程执行。 timeOutInterval如果参数不是 0（零），executeOnlyOnce并且参数为false，则每次发出事件信号或超时间隔时，都会重置计时器。

Important

对 Mutex 使用 waitObject 不会为回调提供相互排斥，因为基础Windows API 使用默认的 WT_EXECUTEDEFAULT 标志，因此每个回调在单独的线程池线程上调度。 而不是使用 Mutex最大计数为 1 的 A Semaphore 。

若要取消等待操作，请调用 RegisteredWaitHandle.Unregister 该方法。

等待线程使用 Win32 WaitForMultipleObjects 函数监视已注册的等待操作。 因此，如果必须在多个调用 RegisterWaitForSingleObject中使用同一本机操作系统句柄，则必须使用 Win32 DuplicateHandle 函数复制句柄。 请注意，不应对传递给 RegisterWaitForSingleObject的事件对象进行脉冲，因为等待线程可能无法检测到事件在重置之前发出信号。

在返回之前，该函数将修改某些类型的同步对象的状态。 仅针对发出信号状态导致满足等待条件的对象进行修改。 例如，信号灯计数减少一个。

另请参阅

• 托管线程池

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

Source:

ThreadPoolWorkQueue.cs

注册一个委托以等待 a WaitHandle，为超时指定 32 位有符号整数（以毫秒为单位）。

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

发出 WaitOrTimerCallback 参数信号时要调用的 waitObject 委托。

state

Object

传递给委托的对象。

millisecondsTimeOutInterval

Int32

超时（以毫秒为单位）。 millisecondsTimeOutInterval如果参数为 0（零），则函数将测试对象的状态并立即返回。 如果 millisecondsTimeOutInterval 为 -1，则函数的超时间隔永远不会过。

executeOnlyOnce

Boolean

true 如果指示线程在调用委托后不再等待 waitObject 参数， false 则指示每次等待操作完成时都会重置计时器，直到取消注册等待。

返回

RegisteredWaitHandle

封装 RegisteredWaitHandle 本机句柄的函数。

属性

UnsupportedOSPlatformAttribute

例外

ArgumentOutOfRangeException

参数 millisecondsTimeOutInterval 小于 -1。

注解

使用 RegisteredWaitHandle 此方法返回的函数完成后，调用该方法 RegisteredWaitHandle.Unregister 以释放对等待句柄的引用。 建议始终调用 RegisteredWaitHandle.Unregister 该方法，即使指定 true 了 executeOnlyOnce此方法。 如果调用 RegisteredWaitHandle.Unregister 方法，而不是依赖于已注册的等待句柄的终结器，垃圾回收更高效。

该方法 RegisterWaitForSingleObject 将指定的委托排入线程池的队列。 发生以下任一情况时，辅助线程将执行委托：

• 指定的对象处于信号状态。
• 超时间隔已用。

该方法 RegisterWaitForSingleObject 检查指定对象的 WaitHandle当前状态。 如果对象的状态未对齐，该方法将注册等待操作。 等待操作由线程池中的线程执行。 当对象的状态发出信号或超时间隔过时，该委托由工作线程执行。 timeOutInterval如果参数不是 0（零），executeOnlyOnce并且参数为false，则每次发出事件信号或超时间隔时，都会重置计时器。

Important

对 Mutex 使用 waitObject 不会为回调提供相互排斥，因为基础Windows API 使用默认的 WT_EXECUTEDEFAULT 标志，因此每个回调在单独的线程池线程上调度。 而不是使用 Mutex最大计数为 1 的 A Semaphore 。

若要取消等待操作，请调用 RegisteredWaitHandle.Unregister 该方法。

等待线程使用 Win32 WaitForMultipleObjects 函数监视已注册的等待操作。 因此，如果必须在多个调用 RegisterWaitForSingleObject中使用同一本机操作系统句柄，则必须使用 Win32 DuplicateHandle 函数复制句柄。 请注意，不应对传递给 RegisterWaitForSingleObject的事件对象进行脉冲，因为等待线程可能无法检测到事件在重置之前发出信号。

在返回之前，该函数将修改某些类型的同步对象的状态。 仅针对发出信号状态导致满足等待条件的对象进行修改。 例如，信号灯计数减少一个。

另请参阅

• 托管线程池

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

Source:

ThreadPoolWorkQueue.cs

注册一个委托以等待 a WaitHandle，为超时指定 64 位有符号整数（以毫秒为单位）。

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

发出 WaitOrTimerCallback 参数信号时要调用的 waitObject 委托。

state

Object

传递给委托的对象。

millisecondsTimeOutInterval

Int64

超时（以毫秒为单位）。 millisecondsTimeOutInterval如果参数为 0（零），则函数将测试对象的状态并立即返回。 如果 millisecondsTimeOutInterval 为 -1，则函数的超时间隔永远不会过。

executeOnlyOnce

Boolean

true 如果指示线程在调用委托后不再等待 waitObject 参数， false 则指示每次等待操作完成时都会重置计时器，直到取消注册等待。

返回

RegisteredWaitHandle

封装 RegisteredWaitHandle 本机句柄的函数。

属性

UnsupportedOSPlatformAttribute

例外

ArgumentOutOfRangeException

参数 millisecondsTimeOutInterval 小于 -1。

注解

使用 RegisteredWaitHandle 此方法返回的函数完成后，调用该方法 RegisteredWaitHandle.Unregister 以释放对等待句柄的引用。 建议始终调用 RegisteredWaitHandle.Unregister 该方法，即使指定 true 了 executeOnlyOnce此方法。 如果调用 RegisteredWaitHandle.Unregister 方法，而不是依赖于已注册的等待句柄的终结器，垃圾回收更高效。

该方法 RegisterWaitForSingleObject 将指定的委托排入线程池的队列。 发生以下任一情况时，辅助线程将执行委托：

• 指定的对象处于信号状态。
• 超时间隔已用。

该方法 RegisterWaitForSingleObject 检查指定对象的 WaitHandle当前状态。 如果对象的状态未对齐，该方法将注册等待操作。 等待操作由线程池中的线程执行。 当对象的状态发出信号或超时间隔过时，该委托由工作线程执行。 timeOutInterval如果参数不是 0（零），executeOnlyOnce并且参数为false，则每次发出事件信号或超时间隔时，都会重置计时器。

Important

对 Mutex 使用 waitObject 不会为回调提供相互排斥，因为基础Windows API 使用默认的 WT_EXECUTEDEFAULT 标志，因此每个回调在单独的线程池线程上调度。 而不是使用 Mutex最大计数为 1 的 A Semaphore 。

若要取消等待操作，请调用 RegisteredWaitHandle.Unregister 该方法。

等待线程使用 Win32 WaitForMultipleObjects 函数监视已注册的等待操作。 因此，如果必须在多个调用 RegisterWaitForSingleObject中使用同一本机操作系统句柄，则必须使用 Win32 DuplicateHandle 函数复制句柄。 请注意，不应对传递给 RegisterWaitForSingleObject的事件对象进行脉冲，因为等待线程可能无法检测到事件在重置之前发出信号。

在返回之前，该函数将修改某些类型的同步对象的状态。 仅针对发出信号状态导致满足等待条件的对象进行修改。 例如，信号灯计数减少一个。

另请参阅

• 托管线程池