WaitHandle 類別

定義

命名空間:

System.Threading

組件:

netstandard.dll, System.Runtime.dll

來源:

WaitHandle.cs

封裝操作系統特定物件，以等候共用資源的獨佔存取權。

public ref class WaitHandle abstract : MarshalByRefObject, IDisposable

public abstract class WaitHandle : MarshalByRefObject, IDisposable

type WaitHandle = class
    inherit MarshalByRefObject
    interface IDisposable

Public MustInherit Class WaitHandle
Inherits MarshalByRefObject
Implements IDisposable

繼承

Object

MarshalByRefObject

WaitHandle

衍生

System.Threading.EventWaitHandle

System.Threading.Mutex

System.Threading.Semaphore

實作

IDisposable

範例

以下程式碼範例說明兩個執行緒如何執行背景任務，而主執行緒則利用類別的WaitHandle靜態WaitAny與WaitAll方法等待任務完成。

using System;
using System.Threading;

public sealed class App
{
    // Define an array with two AutoResetEvent WaitHandles.
    static WaitHandle[] waitHandles = new WaitHandle[]
    {
        new AutoResetEvent(false),
        new AutoResetEvent(false)
    };

    // Define a random number generator for testing.
    static Random r = new Random();

    static void Main()
    {
        // Queue up two tasks on two different threads;
        // wait until all tasks are completed.
        DateTime dt = DateTime.Now;
        Console.WriteLine("Main thread is waiting for BOTH tasks to complete.");
        ThreadPool.QueueUserWorkItem(new WaitCallback(DoTask), waitHandles[0]);
        ThreadPool.QueueUserWorkItem(new WaitCallback(DoTask), waitHandles[1]);
        WaitHandle.WaitAll(waitHandles);
        // The time shown below should match the longest task.
        Console.WriteLine("Both tasks are completed (time waited={0})",
            (DateTime.Now - dt).TotalMilliseconds);

        // Queue up two tasks on two different threads;
        // wait until any task is completed.
        dt = DateTime.Now;
        Console.WriteLine();
        Console.WriteLine("The main thread is waiting for either task to complete.");
        ThreadPool.QueueUserWorkItem(new WaitCallback(DoTask), waitHandles[0]);
        ThreadPool.QueueUserWorkItem(new WaitCallback(DoTask), waitHandles[1]);
        int index = WaitHandle.WaitAny(waitHandles);
        // The time shown below should match the shortest task.
        Console.WriteLine("Task {0} finished first (time waited={1}).",
            index + 1, (DateTime.Now - dt).TotalMilliseconds);
    }

    static void DoTask(Object state)
    {
        AutoResetEvent are = (AutoResetEvent) state;
        int time = 1000 * r.Next(2, 10);
        Console.WriteLine("Performing a task for {0} milliseconds.", time);
        Thread.Sleep(time);
        are.Set();
    }
}

// This code produces output similar to the following:
//
//  Main thread is waiting for BOTH tasks to complete.
//  Performing a task for 7000 milliseconds.
//  Performing a task for 4000 milliseconds.
//  Both tasks are completed (time waited=7064.8052)
//
//  The main thread is waiting for either task to complete.
//  Performing a task for 2000 milliseconds.
//  Performing a task for 2000 milliseconds.
//  Task 1 finished first (time waited=2000.6528).

Imports System.Threading

NotInheritable Public Class App
    ' Define an array with two AutoResetEvent WaitHandles.
    Private Shared waitHandles() As WaitHandle = _
        {New AutoResetEvent(False), New AutoResetEvent(False)}
    
    ' Define a random number generator for testing.
    Private Shared r As New Random()
    
    <MTAThreadAttribute> _
    Public Shared Sub Main() 
        ' Queue two tasks on two different threads; 
        ' wait until all tasks are completed.
        Dim dt As DateTime = DateTime.Now
        Console.WriteLine("Main thread is waiting for BOTH tasks to complete.")
        ThreadPool.QueueUserWorkItem(AddressOf DoTask, waitHandles(0))
        ThreadPool.QueueUserWorkItem(AddressOf DoTask, waitHandles(1))
        WaitHandle.WaitAll(waitHandles)
        ' The time shown below should match the longest task.
        Console.WriteLine("Both tasks are completed (time waited={0})", _
            (DateTime.Now - dt).TotalMilliseconds)
        
        ' Queue up two tasks on two different threads; 
        ' wait until any tasks are completed.
        dt = DateTime.Now
        Console.WriteLine()
        Console.WriteLine("The main thread is waiting for either task to complete.")
        ThreadPool.QueueUserWorkItem(AddressOf DoTask, waitHandles(0))
        ThreadPool.QueueUserWorkItem(AddressOf DoTask, waitHandles(1))
        Dim index As Integer = WaitHandle.WaitAny(waitHandles)
        ' The time shown below should match the shortest task.
        Console.WriteLine("Task {0} finished first (time waited={1}).", _
            index + 1,(DateTime.Now - dt).TotalMilliseconds)
    
    End Sub
    
    Shared Sub DoTask(ByVal state As [Object]) 
        Dim are As AutoResetEvent = CType(state, AutoResetEvent)
        Dim time As Integer = 1000 * r.Next(2, 10)
        Console.WriteLine("Performing a task for {0} milliseconds.", time)
        Thread.Sleep(time)
        are.Set()
    
    End Sub
End Class

' This code produces output similar to the following:
'
'  Main thread is waiting for BOTH tasks to complete.
'  Performing a task for 7000 milliseconds.
'  Performing a task for 4000 milliseconds.
'  Both tasks are completed (time waited=7064.8052)
' 
'  The main thread is waiting for either task to complete.
'  Performing a task for 2000 milliseconds.
'  Performing a task for 2000 milliseconds.
'  Task 1 finished first (time waited=2000.6528).

備註

此 WaitHandle 類別封裝了作業系統的原生同步處理句柄，用來表示執行時中允許多次等待操作的同步物件。 關於與其他同步物件的等待句柄比較，請參見 同步原語概述。

這 WaitHandle 門課本身是抽象的。 衍生的 WaitHandle 類別定義了一種訊號機制，用來表示存取或釋放共享資源的存取權，但它們使用繼承的方法在等待共享資源存取時進行 WaitHandle 阻擋。 衍生的 WaitHandle 類別包括：

• Mutex 類別。 參見 變異動物。

• 該 EventWaitHandle 類別及其導出類別， AutoResetEvent 且 ManualResetEvent。

• Semaphore 類別。 請參見 Semaphore 和 SemaphoreSlim。

執行緒可以透過呼叫實例方法來阻塞單一等待句柄，該方法 WaitOne由從 WaitHandle衍生的類別繼承。

的 WaitHandle 衍生類別在線程親和力上有所不同。 事件等待的句柄（EventWaitHandle、 AutoResetEvent和 ManualResetEvent）和信號量不具備執行緒親和性;任何執行緒都可以發出事件等待的句柄或信號量。 另一方面，muttexes確實有線的親和力;擁有 mutex 的執行緒必須釋放該執行緒，若執行緒 ReleaseMutex 呼叫該方法，且該方法不屬於它，則會拋出例外。

由於 類別 WaitHandle 源自 MarshalByRefObject，這些類別可用來同步執行緒跨領域邊界的活動。

除了衍生類別外，該 WaitHandle 類別還有多個靜態方法，會阻塞執行緒，直到一個或多個同步物件收到訊號。 這些包括：

• SignalAndWait，允許執行緒發出一個等待句柄的訊號，並立即等待另一個。

• WaitAll，允許執行緒等待陣列中所有等待的句柄都收到訊號。

• WaitAny允許執行緒等待，直到指定一組等待句柄中的任一被發出訊號。

這些方法的過載提供了逾時間隔以放棄等待，並有機會在進入等待前退出同步情境，讓其他執行緒能使用同步情境。

這很重要

此類型會實作 IDisposable 介面。 當你用完該類型或其衍生型後，應該直接或間接處理。 若要直接處置類型，請在 Closetry/ 區塊中呼叫其 catch 方法。 若要間接處置它，請使用語言建構，例如 using （C#） 或 Using （在 Visual Basic 中）。 如需詳細資訊，請參閱介面主題中的 <使用實作 IDisposable 的物件>一節。

WaitHandle 實現了這個 Dispose 模式。 請參見 「實施處置方法」。 當你從 WaitHandle衍生時，使用 屬性 SafeWaitHandle 來儲存你的原生作業系統帳號。 除非使用額外的未管理資源，否則不需要覆寫受保護 Dispose 的方法。

建構函式

名稱	Description
WaitHandle()	初始化 WaitHandle 類別的新執行個體。

欄位

名稱	Description
InvalidHandle	代表無效的原生作業系統代言碼。 此欄位是唯讀的。
WaitTimeout	表示操作 WaitAny(WaitHandle[], Int32, Boolean) 在任何等待句柄被通知前已逾時。 此欄位是常數。

屬性

名稱	Description
Handle	已淘汰. 取得或設定原生作業系統的 handle 。
SafeWaitHandle	取得或設定原生作業系統的 handle 。

方法

名稱	Description
Close()	釋放目前 WaitHandle所持有的所有資源。
Dispose()	釋放目前類別實例 WaitHandle 所使用的所有資源。
Dispose(Boolean)	當在衍生類別中被覆寫時，會釋放 所使用的 WaitHandle非管理資源，並可選擇性地釋放受管理資源。
Equals(Object)	判斷指定的物件是否等於目前的物件。 (繼承來源 Object)
GetHashCode()	做為預設哈希函式。 (繼承來源 Object)
GetLifetimeService()	已淘汰. 取得目前控制此實例生命週期政策的終身服務物件。 (繼承來源 MarshalByRefObject)
GetType()	取得目前實例的 Type。 (繼承來源 Object)
InitializeLifetimeService()	已淘汰. 取得一個終身服務物件以控制此實例的終身政策。 (繼承來源 MarshalByRefObject)
MemberwiseClone()	建立目前 Object的淺層複本。 (繼承來源 Object)
MemberwiseClone(Boolean)	建立一個 MarshalByRefObject 目前物件的淺層複製品。 (繼承來源 MarshalByRefObject)
SignalAndWait(WaitHandle, WaitHandle, Int32, Boolean)	向一個 WaitHandle 區域發出訊號並等待另一個，指定一個 32 位元有符號整數的逾時區間，並指定是否在進入等待前退出上下文的同步域。
SignalAndWait(WaitHandle, WaitHandle, TimeSpan, Boolean)	發出一個 WaitHandle 訊號並等待另一個，指定逾時區間為 a TimeSpan ，並指定是否退出上下文的同步域後再進入等待。
SignalAndWait(WaitHandle, WaitHandle)	示意一個 WaitHandle ，另一個則等待。
ToString()	傳回表示目前 物件的字串。 (繼承來源 Object)
WaitAll(WaitHandle[], Int32, Boolean)	等待指定陣列中的所有元素接收訊號，使用 Int32 一個值指定時間區間，並決定是否在等待前退出同步域。
WaitAll(WaitHandle[], Int32)	等待指定陣列中的所有元素接收訊號，並以一個 Int32 值指定時間區間。
WaitAll(WaitHandle[], TimeSpan, Boolean)	等待指定陣列中的所有元素接收訊號，使用 TimeSpan 一個值指定時間區間，並指定是否在等待前退出同步域。
WaitAll(WaitHandle[], TimeSpan)	等待指定陣列中的所有元素接收訊號，並使用一個 TimeSpan 值來指定時間區間。
WaitAll(WaitHandle[])	等待指定陣列中的所有元件接收訊號。
WaitAny(WaitHandle[], Int32, Boolean)	等待指定陣列中的任一元素接收訊號，使用32位元有符號整數指定時間區間，並指定是否在等待前退出同步域。
WaitAny(WaitHandle[], Int32)	等待指定陣列中任一元素接收訊號，並使用 32 位元有符號整數指定時間區間。
WaitAny(WaitHandle[], TimeSpan, Boolean)	等待指定陣列中的任一元素接收訊號，利用 a TimeSpan 指定時間區間，並決定是否在等待前退出同步域。
WaitAny(WaitHandle[], TimeSpan)	等待指定陣列中的任一元素接收訊號，並使用 a TimeSpan 來指定時間區間。
WaitAny(WaitHandle[])	等待指定陣列中的任一元件接收訊號。
WaitOne()	阻擋目前執行緒，直到電流 WaitHandle 接收到訊號。
WaitOne(Int32, Boolean)	在當前執行緒收到訊號前封鎖該執行緒 WaitHandle ，使用32位元有符號整數指定時間區間，並指定是否在等待前退出同步域。
WaitOne(Int32)	在當前執行緒收到訊號前 WaitHandle ，會阻塞該執行緒，並使用 32 位元有號整數來指定以毫秒為單位的時間間隔。
WaitOne(TimeSpan, Boolean)	阻塞目前執行緒直到目前實例收到訊號，並用 a TimeSpan 指定時間區間，並決定是否在等待前退出同步域。
WaitOne(TimeSpan)	阻塞目前執行緒直到目前實例收到訊號，並使用 a TimeSpan 指定時間區間。

擴充方法

名稱	Description
GetSafeWaitHandle(WaitHandle)	取得原生作業系統等待句柄的安全句柄。
SetSafeWaitHandle(WaitHandle, SafeWaitHandle)	為作業系統的原生等待句柄設定安全句柄。

執行緒安全性

此類型是安全線程。

另請參閱

• 線程
• 線程物件和功能
• Mutex
• 事件等待處理、自動重置事件與手動重置事件
• 臂板