EventWaitHandle 建構函式

定義

命名空間:

System.Threading

組件:

System.Threading.dll

初始化 EventWaitHandle 類別的新執行個體。

多載

EventWaitHandle(Boolean, EventResetMode)	初始化 EventWaitHandle 類別的新執行個體、指定等候控制代碼是否一開始就會收到信號，以及是以自動還是手動方式來重設。
EventWaitHandle(Boolean, EventResetMode, String)	初始化 EventWaitHandle 類別的新執行個體、指定等候控制代碼是否一開始就會收到信號 (如果它是因這個呼叫而建立)、是以自動還是手動方式進行重設，以及系統同步處理事件的名稱。
EventWaitHandle(Boolean, EventResetMode, String, Boolean)	初始化 EventWaitHandle 類別的新執行個體，指定如果等候控制代碼是因此呼叫而建立，一開始是否會發出信號；它是否會自動或手動重設；系統同步處理事件的名稱；以及布林值變數，其值會在呼叫之後指出是否已建立具名系統事件。

EventWaitHandle(Boolean, EventResetMode)

來源:

EventWaitHandle.cs

初始化 EventWaitHandle 類別的新執行個體、指定等候控制代碼是否一開始就會收到信號，以及是以自動還是手動方式來重設。

public:
 EventWaitHandle(bool initialState, System::Threading::EventResetMode mode);

public EventWaitHandle (bool initialState, System.Threading.EventResetMode mode);

new System.Threading.EventWaitHandle : bool * System.Threading.EventResetMode -> System.Threading.EventWaitHandle

Public Sub New (initialState As Boolean, mode As EventResetMode)

參數

initialState

Boolean

true 表示初始狀態設定為已收到信號，false 表示初始狀態設定為未收到信號。

mode

EventResetMode

其中一個 EventResetMode 值，決定事件是否要自動或手動重設。

例外狀況

ArgumentException

mode 列舉值不在合法範圍內。

範例

下列程式代碼範例會 SignalAndWait(WaitHandle, WaitHandle) 使用 方法多載來允許主線程發出封鎖線程的訊號，然後等候線程完成工作。

此範例會啟動五個線程，並允許他們在使用 EventResetMode.AutoReset 旗標建立的 EventWaitHandle 上封鎖，然後每次使用者按下 Enter 鍵時釋放一個線程。 接著，此範例會排入其他五個線程，並使用搭配 EventWaitHandle 旗標建立的 EventResetMode.ManualReset 釋放它們。

using namespace System;
using namespace System::Threading;

public ref class Example
{
private:
   // The EventWaitHandle used to demonstrate the difference
   // between AutoReset and ManualReset synchronization events.
   //
   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.
   //
   static __int64 threadCount = 0;

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

public:
   [MTAThread]
   static void main()
   {
      // Create an AutoReset EventWaitHandle.
      //
      ewh = gcnew 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 = gcnew Thread(
            gcnew 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( threadCount ) < 5 )
      {
         Thread::Sleep( 500 );
      }

      // Release one thread each time the user presses ENTER,
      // until all threads have been released.
      //
      while ( Interlocked::Read( threadCount ) > 0 )
      {
         Console::WriteLine( L"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 = gcnew EventWaitHandle( false,EventResetMode::ManualReset );
      
      // Create and start five more numbered threads.
      //
      for ( int i = 0; i <= 4; i++ )
      {
         Thread^ t = gcnew Thread(
            gcnew ParameterizedThreadStart( ThreadProc ) );
         t->Start( i );
      }
      
      // Wait until all the threads have started and blocked.
      //
      while ( Interlocked::Read( threadCount ) < 5 )
      {
         Thread::Sleep( 500 );
      }

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

   }

   static void ThreadProc( Object^ data )
   {
      int index = static_cast<Int32>(data);

      Console::WriteLine( L"Thread {0} blocks.", data );
      // Increment the count of blocked threads.
      Interlocked::Increment( threadCount );
      
      // Wait on the EventWaitHandle.
      ewh->WaitOne();

      Console::WriteLine( L"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();
   }
};

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

備註

如果事件的初始狀態為未簽署，則等候事件的線程將會封鎖。 如果初始狀態已發出訊號，且 ManualReset 已為 mode指定旗標，則等候事件的線程將不會封鎖。 如果初始狀態已發出訊號，且 mode 為 AutoReset，則會立即釋放等候事件的第一個線程，之後事件將會重設，而後續的線程將會封鎖。

另請參閱

• 同步處理原始物件概觀

EventWaitHandle(Boolean, EventResetMode, String)

來源:

EventWaitHandle.cs

初始化 EventWaitHandle 類別的新執行個體、指定等候控制代碼是否一開始就會收到信號 (如果它是因這個呼叫而建立)、是以自動還是手動方式進行重設，以及系統同步處理事件的名稱。

public:
 EventWaitHandle(bool initialState, System::Threading::EventResetMode mode, System::String ^ name);

public EventWaitHandle (bool initialState, System.Threading.EventResetMode mode, string? name);

new System.Threading.EventWaitHandle : bool * System.Threading.EventResetMode * string -> System.Threading.EventWaitHandle

Public Sub New (initialState As Boolean, mode As EventResetMode, name As String)

參數

initialState

Boolean

如果已因此呼叫而建立具名事件，則為 true 以將初始狀態設定為收到信號；否則為 false 以將其設定為未收到信號。

mode

EventResetMode

其中一個 EventResetMode 值，決定事件是否要自動或手動重設。

name

String

如果同步物件要與其他處理序共用，則為名稱；否則為 null 或空字串。 名稱區分大小寫。 反斜杠字元 (\) 是保留的，只能用來指定命名空間。 如需命名空間的詳細資訊，請參閱一節。 視操作系統而定，可能會進一步限制名稱。 例如，在 Unix 型作業系統上，排除命名空間之後的名稱必須是有效的檔名。

例外狀況

IOException

name 無效。 這可能基於數種原因，其中包括可能由作業系統設定的一些限制，例如未知前置詞或無效字元。 請注意，名稱和通用前置詞 「Global\」 和 「Local\」 會區分大小寫。

-或-

發生一些其他錯誤。 HResult 屬性可提供詳細資訊。

DirectoryNotFoundException

僅限 Windows：name 已指定未知命名空間。 請參閱物件名稱 \(英文\) 以取得詳細資訊。

PathTooLongException

name 太長。 長度限制可能會取決於作業系統或設定。

UnauthorizedAccessException

具名事件存在，並具有存取控制安全性，但使用者沒有 FullControl。

WaitHandleCannotBeOpenedException

無法建立具有所提供 name 的同步物件。 不同類型的同步物件可能具有相同名稱。

ArgumentException

mode 列舉值不在合法範圍內。

-或-

僅限 .NET Framework：name 的長度超過 MAX_PATH (260 個字元)。

備註

name前面可能會加上 Global\ 或 Local\ ，以指定命名空間。 Global指定命名空間時，同步處理物件可能會與系統上的任何進程共用。 Local指定命名空間時，這也是未指定命名空間時的預設值，同步處理物件可能會與相同會話中的進程共用。 在 Windows 上，會話是登入工作階段，服務通常會在不同的非互動式會話中執行。 在類似 Unix 的作業系統上，每個殼層都有自己的會話。 會話本機同步處理物件可能適用於在進程與父/子關聯性之間同步處理，其中它們全都在相同會話中執行。 如需 Windows 上同步處理物件名稱的詳細資訊，請參閱 物件名稱。

name如果 已提供 ，且要求的型別同步處理物件已存在於命名空間中，則會開啟現有的同步處理物件。 如果命名空間中已經存在不同類型的同步處理物件， WaitHandleCannotBeOpenedException 則會擲回 。 否則，會建立新的同步處理物件。

如果為參數指定 name 名稱的系統事件已經存在，則會 initialState 忽略 參數。

警告

根據預設，具名事件不限於建立它的使用者。 其他使用者可以開啟和使用事件，包括藉由設定或不當重設事件來干擾事件。 若要限制特定使用者的存取權，您可以使用建構函式多載，或在 EventWaitHandleAcl 建立具名事件時傳入 EventWaitHandleSecurity 。 避免在執行程式代碼的系統上使用具名事件，而不受存取限制。

重要

針對具名系統事件使用此建構函式時，請針對 指定 falseinitialState。 這個建構函式無法判斷是否已建立具名系統事件，因此您無法對具名事件的狀態進行任何假設。 若要判斷是否已建立具名事件，請使用 EventWaitHandle(Boolean, EventResetMode, String, Boolean) 建構函式或建 EventWaitHandle(Boolean, EventResetMode, String, Boolean, EventWaitHandleSecurity) 構函式。

如果事件的初始狀態為未簽署，則等候事件的線程將會封鎖。 如果初始狀態已發出訊號，且 ManualReset 已為 mode指定旗標，則等候事件的線程將不會封鎖。 如果初始狀態已發出訊號，且 mode 為 AutoReset，則會立即釋放等候事件的第一個線程，之後事件將會重設，而後續的線程將會封鎖。

另請參閱

• 同步處理原始物件概觀

EventWaitHandle(Boolean, EventResetMode, String, Boolean)

來源:

EventWaitHandle.cs

初始化 EventWaitHandle 類別的新執行個體，指定如果等候控制代碼是因此呼叫而建立，一開始是否會發出信號；它是否會自動或手動重設；系統同步處理事件的名稱；以及布林值變數，其值會在呼叫之後指出是否已建立具名系統事件。

public:
 EventWaitHandle(bool initialState, System::Threading::EventResetMode mode, System::String ^ name, [Runtime::InteropServices::Out] bool % createdNew);

public EventWaitHandle (bool initialState, System.Threading.EventResetMode mode, string? name, out bool createdNew);

new System.Threading.EventWaitHandle : bool * System.Threading.EventResetMode * string * bool -> System.Threading.EventWaitHandle

Public Sub New (initialState As Boolean, mode As EventResetMode, name As String, ByRef createdNew As Boolean)

參數

initialState

Boolean

如果已因此呼叫而建立具名事件，則為 true 以將初始狀態設定為收到信號；否則為 false 以將其設定為未收到信號。

mode

EventResetMode

其中一個 EventResetMode 值，決定事件是否要自動或手動重設。

name

String

如果同步物件要與其他處理序共用，則為名稱；否則為 null 或空字串。 名稱區分大小寫。 反斜杠字元 (\) 是保留的，只能用來指定命名空間。 如需命名空間的詳細資訊，請參閱一節。 視操作系統而定，可能會進一步限制名稱。 例如，在 Unix 型作業系統上，排除命名空間之後的名稱必須是有效的檔名。

createdNew

Boolean

這個方法傳回時，如果已建立本機事件 (也就是說，如果 name 為 true 或空字串)，或是已建立指定的已命名系統事件，則會包含 null；如果指定的已命名系統事件已存在則為 false。 這個參數會以未初始化的狀態傳遞。

例外狀況

IOException

name 無效。 這可能基於數種原因，其中包括可能由作業系統設定的一些限制，例如未知前置詞或無效字元。 請注意，名稱和通用前置詞 「Global\」 和 「Local\」 會區分大小寫。

-或-

發生一些其他錯誤。 HResult 屬性可提供詳細資訊。

DirectoryNotFoundException

僅限 Windows：name 已指定未知命名空間。 請參閱物件名稱 \(英文\) 以取得詳細資訊。

PathTooLongException

name 太長。 長度限制可能會取決於作業系統或設定。

UnauthorizedAccessException

具名事件存在，並具有存取控制安全性，但使用者沒有 FullControl。

WaitHandleCannotBeOpenedException

無法建立具有所提供 name 的同步物件。 不同類型的同步物件可能具有相同名稱。

ArgumentException

mode 列舉值不在合法範圍內。

-或-

僅限 .NET Framework：name 的長度超過 MAX_PATH (260 個字元)。

備註

name前面可能會加上 Global\ 或 Local\ ，以指定命名空間。 Global指定命名空間時，同步處理物件可能會與系統上的任何進程共用。 Local指定命名空間時，這也是未指定命名空間時的預設值，同步處理物件可能會與相同會話中的進程共用。 在 Windows 上，會話是登入工作階段，服務通常會在不同的非互動式會話中執行。 在類似 Unix 的作業系統上，每個殼層都有自己的會話。 會話本機同步處理物件可能適用於在進程與父/子關聯性之間同步處理，其中它們全都在相同會話中執行。 如需 Windows 上同步處理物件名稱的詳細資訊，請參閱 物件名稱。

name如果 已提供 ，且要求的型別同步處理物件已存在於命名空間中，則會開啟現有的同步處理物件。 如果命名空間中已經存在不同類型的同步處理物件， WaitHandleCannotBeOpenedException 則會擲回 。 否則，會建立新的同步處理物件。

如果為參數指定 name 名稱的系統事件已經存在，則會 initialState 忽略 參數。 呼叫這個建構函式之後，請使用 Visual Basic 中為 ref 參數指定之變數中的值 (ByRef 參數) ， createdNew 以判斷具名系統事件是否已存在或已建立。

如果事件的初始狀態為未簽署，則等候事件的線程將會封鎖。 如果初始狀態已發出訊號，且 ManualReset 已為 mode指定旗標，則等候事件的線程將不會封鎖。 如果初始狀態已發出訊號，且 mode 為 AutoReset，則會立即釋放等候事件的第一個線程，之後事件將會重設，而後續的線程將會封鎖。

警告

根據預設，具名事件不限於建立它的使用者。 其他使用者可以開啟和使用事件，包括藉由設定或不當重設事件來干擾事件。 若要限制特定使用者的存取權，您可以使用建構函式多載，或在 EventWaitHandleAcl 建立具名事件時傳入 EventWaitHandleSecurity 。 避免在執行程式代碼的系統上使用具名事件，而不受存取限制。

另請參閱

• 同步處理原始物件概觀