EventWaitHandle 類別

定義

命名空間:

System.Threading

組件:

netstandard.dll, System.Threading.dll

來源:

EventWaitHandle.cs

代表執行緒同步事件。

public ref class EventWaitHandle : System::Threading::WaitHandle

public class EventWaitHandle : System.Threading.WaitHandle

type EventWaitHandle = class
    inherit WaitHandle

Public Class EventWaitHandle
Inherits WaitHandle

繼承

Object

MarshalByRefObject

WaitHandle

EventWaitHandle

衍生

System.Threading.AutoResetEvent

System.Threading.ManualResetEvent

範例

以下程式碼範例使用 SignalAndWait(WaitHandle, WaitHandle) 方法過載，讓主執行緒能向阻塞的執行緒發出訊號，然後等待執行緒完成任務。

範例中會啟動五個執行緒，並允許它們在用EventWaitHandle旗標建立的執行EventResetMode.AutoReset緒上封鎖，然後每當使用者按下 Enter 鍵時，就會釋放一個執行緒。 範例接著排隊另外五個執行緒，並用 EventWaitHandle Created with the EventResetMode.ManualReset flag 釋放它們。

using System;
using System.Threading;

public class Example
{
    // The EventWaitHandle used to demonstrate the difference
    // between AutoReset and ManualReset synchronization events.
    //
    private static EventWaitHandle ewh;

    // A counter to make sure all threads are started and
    // blocked before any are released. A Long is used to show
    // the use of the 64-bit Interlocked methods.
    //
    private static long threadCount = 0;

    // An AutoReset event that allows the main thread to block
    // until an exiting thread has decremented the count.
    //
    private static EventWaitHandle clearCount = 
        new EventWaitHandle(false, EventResetMode.AutoReset);

    [MTAThread]
    public static void Main()
    {
        // Create an AutoReset EventWaitHandle.
        //
        ewh = new EventWaitHandle(false, EventResetMode.AutoReset);

        // Create and start five numbered threads. Use the
        // ParameterizedThreadStart delegate, so the thread
        // number can be passed as an argument to the Start 
        // method.
        for (int i = 0; i <= 4; i++)
        {
            Thread t = new Thread(
                new ParameterizedThreadStart(ThreadProc)
            );
            t.Start(i);
        }

        // Wait until all the threads have started and blocked.
        // When multiple threads use a 64-bit value on a 32-bit
        // system, you must access the value through the
        // Interlocked class to guarantee thread safety.
        //
        while (Interlocked.Read(ref threadCount) < 5)
        {
            Thread.Sleep(500);
        }

        // Release one thread each time the user presses ENTER,
        // until all threads have been released.
        //
        while (Interlocked.Read(ref threadCount) > 0)
        {
            Console.WriteLine("Press ENTER to release a waiting thread.");
            Console.ReadLine();

            // SignalAndWait signals the EventWaitHandle, which
            // releases exactly one thread before resetting, 
            // because it was created with AutoReset mode. 
            // SignalAndWait then blocks on clearCount, to 
            // allow the signaled thread to decrement the count
            // before looping again.
            //
            WaitHandle.SignalAndWait(ewh, clearCount);
        }
        Console.WriteLine();

        // Create a ManualReset EventWaitHandle.
        //
        ewh = new EventWaitHandle(false, EventResetMode.ManualReset);

        // Create and start five more numbered threads.
        //
        for(int i=0; i<=4; i++)
        {
            Thread t = new Thread(
                new ParameterizedThreadStart(ThreadProc)
            );
            t.Start(i);
        }

        // Wait until all the threads have started and blocked.
        //
        while (Interlocked.Read(ref threadCount) < 5)
        {
            Thread.Sleep(500);
        }

        // Because the EventWaitHandle was created with
        // ManualReset mode, signaling it releases all the
        // waiting threads.
        //
        Console.WriteLine("Press ENTER to release the waiting threads.");
        Console.ReadLine();
        ewh.Set();
    }

    public static void ThreadProc(object data)
    {
        int index = (int) data;

        Console.WriteLine("Thread {0} blocks.", data);
        // Increment the count of blocked threads.
        Interlocked.Increment(ref threadCount);

        // Wait on the EventWaitHandle.
        ewh.WaitOne();

        Console.WriteLine("Thread {0} exits.", data);
        // Decrement the count of blocked threads.
        Interlocked.Decrement(ref threadCount);

        // After signaling ewh, the main thread blocks on
        // clearCount until the signaled thread has 
        // decremented the count. Signal it now.
        //
        clearCount.Set();
    }
}

Imports System.Threading

Public Class Example

    ' The EventWaitHandle used to demonstrate the difference
    ' between AutoReset and ManualReset synchronization events.
    '
    Private Shared ewh As EventWaitHandle

    ' A counter to make sure all threads are started and
    ' blocked before any are released. A Long is used to show
    ' the use of the 64-bit Interlocked methods.
    '
    Private Shared threadCount As Long = 0

    ' An AutoReset event that allows the main thread to block
    ' until an exiting thread has decremented the count.
    '
    Private Shared clearCount As New EventWaitHandle(False, _
        EventResetMode.AutoReset)

    <MTAThread> _
    Public Shared Sub Main()

        ' Create an AutoReset EventWaitHandle.
        '
        ewh = New EventWaitHandle(False, EventResetMode.AutoReset)

        ' Create and start five numbered threads. Use the
        ' ParameterizedThreadStart delegate, so the thread
        ' number can be passed as an argument to the Start 
        ' method.
        For i As Integer = 0 To 4
            Dim t As New Thread(AddressOf ThreadProc)
            t.Start(i)
        Next i

        ' Wait until all the threads have started and blocked.
        ' When multiple threads use a 64-bit value on a 32-bit
        ' system, you must access the value through the
        ' Interlocked class to guarantee thread safety.
        '
        While Interlocked.Read(threadCount) < 5
            Thread.Sleep(500)
        End While

        ' Release one thread each time the user presses ENTER,
        ' until all threads have been released.
        '
        While Interlocked.Read(threadCount) > 0
            Console.WriteLine("Press ENTER to release a waiting thread.")
            Console.ReadLine()

            ' SignalAndWait signals the EventWaitHandle, which
            ' releases exactly one thread before resetting, 
            ' because it was created with AutoReset mode. 
            ' SignalAndWait then blocks on clearCount, to 
            ' allow the signaled thread to decrement the count
            ' before looping again.
            '
            WaitHandle.SignalAndWait(ewh, clearCount)
        End While
        Console.WriteLine()

        ' Create a ManualReset EventWaitHandle.
        '
        ewh = New EventWaitHandle(False, EventResetMode.ManualReset)

        ' Create and start five more numbered threads.
        '
        For i As Integer = 0 To 4
            Dim t As New Thread(AddressOf ThreadProc)
            t.Start(i)
        Next i

        ' Wait until all the threads have started and blocked.
        '
        While Interlocked.Read(threadCount) < 5
            Thread.Sleep(500)
        End While

        ' Because the EventWaitHandle was created with
        ' ManualReset mode, signaling it releases all the
        ' waiting threads.
        '
        Console.WriteLine("Press ENTER to release the waiting threads.")
        Console.ReadLine()
        ewh.Set()
        
    End Sub

    Public Shared Sub ThreadProc(ByVal data As Object)
        Dim index As Integer = CInt(data)

        Console.WriteLine("Thread {0} blocks.", data)
        ' Increment the count of blocked threads.
        Interlocked.Increment(threadCount)

        ' Wait on the EventWaitHandle.
        ewh.WaitOne()

        Console.WriteLine("Thread {0} exits.", data)
        ' Decrement the count of blocked threads.
        Interlocked.Decrement(threadCount)

        ' After signaling ewh, the main thread blocks on
        ' clearCount until the signaled thread has 
        ' decremented the count. Signal it now.
        '
        clearCount.Set()
    End Sub
End Class

備註

這個 EventWaitHandle 類別允許執行緒透過訊號傳遞彼此溝通。 通常，一個或多個執行緒會阻塞 ， EventWaitHandle 直到一個未被阻塞的執行緒呼叫該 Set 方法，釋放一個或多個被阻塞的執行緒。 執行緒可以呼叫 EventWaitHandle 並透過呼叫 static（在 Visual Basic 中Shared）WaitHandle.SignalAndWait 方法來阻擋該執行緒。

Note

此 EventWaitHandle 類別提供命名系統同步事件的存取權限。

被訊號的 的 EventWaitHandle 行為取決於其重置模式。 EventWaitHandle一個帶有EventResetMode.AutoReset旗標的創建會在發出信號後自動重置，前提是釋放一個等待的執行緒。 使用EventWaitHandle旗標建立的EventResetMode.ManualReset會保持訊號直到呼叫其Reset方法為止。

自動重置事件提供對資源的專屬存取權。 如果在沒有線程等候時，自動重設事件被設定為有訊號，它會保持有訊號狀態，直到有線程嘗試等候為止。 事件會釋放線程並立即重設，並封鎖後續線程。

手動重置事件就像門一樣。 當事件未被通知時，等待該事件的執行緒會阻塞。 當事件被發出訊號時，所有等待的執行緒會被釋放，事件會持續被通知（也就是說，後續的等待不會阻塞），直到 Reset 其方法被呼叫為止。 手動重置事件在一個執行緒必須完成某項活動後，其他執行緒才能繼續時非常有用。

物件可搭配 （ 在 Visual Basic中） 及 方法使用。

欲了解更多資訊，請參閱《同步原語概述》文章中的線程互動或訊號部分。

Caution

預設情況下，命名事件不僅限於創建它的使用者。 其他使用者可能能夠開啟並使用該事件，包括透過不當設定或重置事件來干擾事件。 要限制特定使用者的存取，你可以使用建構器過載，或EventWaitHandleAcl在建立指定事件時傳遞 。EventWaitHandleSecurity 避免在可能有不受信任使用者執行程式碼的系統中使用無存取限制的命名事件。

建構函式

名稱	Description
EventWaitHandle(Boolean, EventResetMode, String, Boolean)	初始化該類別的新實例 EventWaitHandle ，指定若因呼叫建立等待句柄是否會被最初發出訊號，是否自動或手動重置，系統同步事件名稱，以及呼叫後的布林變數值，指示該系統事件是否被建立。
EventWaitHandle(Boolean, EventResetMode, String, NamedWaitHandleOptions, Boolean)	初始化該類別的新實例 EventWaitHandle ，指定若因呼叫建立等待句柄，是否會先發出訊號，是否自動或手動重置，系統同步事件名稱，設定使用者範圍與會話範圍存取選項，以及呼叫後的布林變數，該變數值顯示該系統事件是否被建立。
EventWaitHandle(Boolean, EventResetMode, String, NamedWaitHandleOptions)	初始化該類別的新實例 EventWaitHandle ，指定若因呼叫建立等待句柄，是否會先發出訊號，是否會自動或手動重置，系統同步事件名稱，以及設定使用者範圍與會話範圍存取的選項。
EventWaitHandle(Boolean, EventResetMode, String)	初始化該類別的新實例 EventWaitHandle ，指定若因呼叫而建立等待句柄，是否會先發出訊號，是自動或手動重置，以及系統同步事件名稱。
EventWaitHandle(Boolean, EventResetMode)	初始化該類別的新實例 EventWaitHandle ，指定等待句柄是最初被標記，以及是自動或手動重置。

欄位

名稱	Description
WaitTimeout	表示操作 WaitAny(WaitHandle[], Int32, Boolean) 在任何等待句柄被通知前已逾時。 此欄位是常數。 (繼承來源 WaitHandle)

屬性

名稱	Description
Handle	已淘汰. 取得或設定原生作業系統的 handle 。 (繼承來源 WaitHandle)
SafeWaitHandle	取得或設定原生作業系統的 handle 。 (繼承來源 WaitHandle)

方法

名稱	Description
Close()	釋放目前 WaitHandle所持有的所有資源。 (繼承來源 WaitHandle)
Dispose()	釋放目前類別實例 WaitHandle 所使用的所有資源。 (繼承來源 WaitHandle)
Dispose(Boolean)	當在衍生類別中被覆寫時，會釋放 所使用的 WaitHandle非管理資源，並可選擇性地釋放受管理資源。 (繼承來源 WaitHandle)
Equals(Object)	判斷指定的物件是否等於目前的物件。 (繼承來源 Object)
GetHashCode()	做為預設哈希函式。 (繼承來源 Object)
GetLifetimeService()	已淘汰. 擷取控制這個實例存留期原則的目前存留期服務物件。 (繼承來源 MarshalByRefObject)
GetType()	取得目前實例的 Type。 (繼承來源 Object)
InitializeLifetimeService()	已淘汰. 取得存留期服務物件，以控制這個實例的存留期原則。 (繼承來源 MarshalByRefObject)
MemberwiseClone()	建立目前 Object的淺層複本。 (繼承來源 Object)
MemberwiseClone(Boolean)	建立一個 MarshalByRefObject 目前物件的淺層複製品。 (繼承來源 MarshalByRefObject)
OpenExisting(String, NamedWaitHandleOptions)	開啟指定的命名同步事件（如果已存在）。 若選項僅設定為目前使用者，物件的存取控制會被驗證為呼叫使用者。
OpenExisting(String)	開啟指定的命名同步事件（如果已存在）。
Reset()	將事件狀態設為非訊號，導致執行緒阻塞。
Set()	將事件狀態設為已訊號，允許一個或多個等待執行緒繼續。
ToString()	傳回表示目前 物件的字串。 (繼承來源 Object)
TryOpenExisting(String, EventWaitHandle)	若已存在，開啟指定的命名同步事件，並回傳一個表示操作是否成功的值。
TryOpenExisting(String, NamedWaitHandleOptions, EventWaitHandle)	若已存在，開啟指定的命名同步事件，並回傳一個表示操作是否成功的值。 若選項僅設定為目前使用者，物件的存取控制會被驗證為呼叫使用者。
WaitOne()	阻擋目前執行緒，直到電流 WaitHandle 接收到訊號。 (繼承來源 WaitHandle)
WaitOne(Int32, Boolean)	在當前執行緒收到訊號前封鎖該執行緒 WaitHandle ，使用32位元有符號整數指定時間區間，並指定是否在等待前退出同步域。 (繼承來源 WaitHandle)
WaitOne(Int32)	在當前執行緒收到訊號前 WaitHandle ，會阻塞該執行緒，並使用 32 位元有號整數來指定以毫秒為單位的時間間隔。 (繼承來源 WaitHandle)
WaitOne(TimeSpan, Boolean)	阻塞目前執行緒直到目前實例收到訊號，並用 a TimeSpan 指定時間區間，並決定是否在等待前退出同步域。 (繼承來源 WaitHandle)
WaitOne(TimeSpan)	阻塞目前執行緒直到目前實例收到訊號，並使用 a TimeSpan 指定時間區間。 (繼承來源 WaitHandle)

擴充方法

名稱	Description
GetAccessControl(EventWaitHandle)	回傳指定 handle的安全描述符。
GetSafeWaitHandle(WaitHandle)	取得原生作業系統等待句柄的安全句柄。
SetAccessControl(EventWaitHandle, EventWaitHandleSecurity)	設定指定事件等待句柄的安全描述符。
SetSafeWaitHandle(WaitHandle, SafeWaitHandle)	為作業系統的原生等待句柄設定安全句柄。

執行緒安全性

此類型是安全線程。

另請參閱

• WaitHandle
• AutoResetEvent
• ManualResetEvent
• 管理的執行緒
• 同步處理基本概觀