信息
您所需的主题如下所示。但此主题未包含在此库中。

ThreadPool.RegisterWaitForSingleObject 方法 (WaitHandle, WaitOrTimerCallback, Object, UInt32, Boolean)

2013/12/13

指定表示超时(以毫秒为单位)的 32 位无符号整数,注册一个委托等待 WaitHandle

此 API 不符合 CLS。 

Namespace:  System.Threading
程序集:  mscorlib(位于 mscorlib.dll 中)

[CLSCompliantAttribute(false)]
public static RegisteredWaitHandle RegisterWaitForSingleObject(
	WaitHandle waitObject,
	WaitOrTimerCallback callBack,
	Object state,
	uint millisecondsTimeOutInterval,
	bool executeOnlyOnce
)

参数

waitObject
类型: System.Threading.WaitHandle
要注册的等待句柄。
callBack
类型: System.Threading.WaitOrTimerCallback
waitObject 参数终止时调用的委托。
state
类型: System.Object
传递给委托的对象。
millisecondsTimeOutInterval
类型: System.UInt32
以毫秒为单位的超时。如果 millisecondsTimeOutInterval 参数为 0(零),函数将测试对象的状态并立即返回。如果 millisecondsTimeOutInterval 为 -1,则函数的超时间隔永远不过期。
executeOnlyOnce
类型: System.Boolean
如果为 true,表示在调用了委托后,线程将不再在 waitObject 参数上等待;如果为 false,表示每次完成等待操作后都重置计时器,直到注销等待。

返回值

类型: System.Threading.RegisteredWaitHandle
已注册的等待句柄。

异常条件
ArgumentOutOfRangeException

millisecondsTimeOutInterval 参数小于 -1。

此方法返回的 RegisteredWaitHandle 使用完毕后,请调用其 RegisteredWaitHandle.Unregister 方法来释放对等待句柄的引用。建议始终调用 RegisteredWaitHandle.Unregister 方法,即使将 executeOnlyOnce 指定为 true 也是如此。如果调用 RegisteredWaitHandle.Unregister 方法而不是取决于注册的等待句柄的终结器,则垃圾回收的工作效率更高。

RegisterWaitForSingleObject 方法将指定的委托排队到线程池。当发生以下情况之一时,辅助线程将执行委托:

  • 指定对象处于终止状态。

  • 超时间隔已过期。

RegisterWaitForSingleObject 方法检查指定对象的 WaitHandle 的当前状态。如果对象状态为非终止状态,则此方法将注册一个等待操作。此等待操作由线程池中的一个线程来执行。当对象状态变为终止或超时间隔已过期时,委托由辅助线程执行。如果 timeOutInterval 参数不为 0(零),并且 executeOnlyOnce 参数为 false,则每当事件收到信号或超时间隔过期时都会重置计时器。

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

返回前,方法将修改某些类型的同步对象的状态。修改仅发生在其终止状态满足等待条件的对象上。

版本说明

Windows Phone

当用户导航离开 Windows Phone 应用程序时,该应用程序通常会置于休眠状态。当用户返回到休眠的应用程序时,该应用程序将自动恢复运行。如果在使用 API 时将应用程序置于休眠状态,API 无法按预期完成。应该将应用程序设计为处理这种可能性。有关 Windows Phone 执行模型的详细信息,请参见“Windows Phone 的执行模型”

下面的示例演示如何使用 RegisterWaitForSingleObject 方法在指定的等待句柄收到信号时执行指定的回调方法。在此示例中,回调方法为 WaitProc,且等待句柄为 AutoResetEvent

此示例定义了一个 TaskInfo 类以保存执行回调时传递给回调的信息。此示例创建了一个 TaskInfo 对象并为其分配了一些字符串数据。由 RegisterWaitForSingleObject 方法返回的 RegisteredWaitHandle 将分配给 TaskInfo 对象的 Handle 字段,以便回调方法可以访问 RegisteredWaitHandle

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

当主线程通过调用其 Set 方法向 AutoResetEvent 发出信号时,将调用 WaitOrTimerCallback 委托。WaitProc 方法测试 RegisteredWaitHandle 以确定是否发生超时。如果由于等待句柄收到信号而调用回调,则 WaitProc 方法将注销 RegisteredWaitHandle,从而停止其他回调。在超时的情况下,任务会继续等待。WaitProc 方法在结束时将显示消息。

该示例在 UI 线程上的 TextBlock 中显示其输出。为了从回调线程访问 TextBlock,该示例使用 Dispatcher 属性来获取 TextBlockDispatcher 对象,然后使用 Dispatcher.BeginInvoke 方法进行跨线程调用。

说明注意:

要运行此示例,请参见生成具有静态 Windows Phone TextBlock 控件的示例


using System;
using System.Threading;

// TaskInfo contains data that will be passed to the callback 
// method.
public class TaskInfo
{
   public RegisteredWaitHandle Handle = null;
   public System.Windows.Controls.TextBlock OutputBlock = null;
}

public class Example
{
    // The Demo method runs the example. It sets up an event handler to 
    // signal the wait handle, saves the TextBlock that is  used for 
    // output, and finally registers the wait handle.
    public static void Demo(System.Windows.Controls.TextBlock outputBlock)
    {
        outputBlock.Text = "Click here signal the wait handle.\r\n";

        // Create the wait handle that the example waits on.
        AutoResetEvent ev = new AutoResetEvent(false);

        // Set up an event handler to signal the wait handle when the 
        // TextBlock is clicked.
        outputBlock.MouseLeftButtonUp += (object sender, 
            System.Windows.Input.MouseButtonEventArgs e) => ev.Set();

        // Create a TaskInfo and save the TextBlock that the example uses
        // for output.
        TaskInfo ti = new TaskInfo();
        ti.OutputBlock = outputBlock;

        // Set the Handle property of the TaskInfo to the registered wait
        // handle that is returned by RegisterWaitForSingleObject. This 
        // enables the wait to be terminated when the handle has been 
        // signaled once (see WaitProc).
        ti.Handle = ThreadPool.RegisterWaitForSingleObject(
            ev,
            new WaitOrTimerCallback(WaitProc),
            ti,
            1000,
            false
        );
    }

    // 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)
    {
        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.
            ti.Handle.Unregister(null);
        }

        ti.OutputBlock.Dispatcher.BeginInvoke(delegate () {
            ti.OutputBlock.Text += 
                String.Format("WaitProc is running; cause = {0}.\n", cause);
        });
    }
}

/* This example produces output similar to the following:

Click here to signal the wait handle.
WaitProc is running; cause = TIMED OUT.
WaitProc is running; cause = TIMED OUT.
WaitProc is running; cause = TIMED OUT.
WaitProc is running; cause = SIGNALED.
 */


Windows Phone OS

受以下版本支持: 8.0, 7.1, 7.0

Windows Phone

显示: