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) метода , чтобы разрешить основному потоку сигнализировать о заблокированном потоке, а затем ждать, пока поток завершит задачу.

В примере запускается пять потоков и они могут блокировать EventWaitHandle созданный с помощью флага EventResetMode.AutoReset , а затем освобождает один поток каждый раз, когда пользователь нажимает клавишу ВВОД . Затем этот пример помещает в очередь еще пять потоков и освобождает их все с помощью созданного 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 в при создании именованного события. Избегайте использования именованных событий без ограничений доступа в системах, в которых могут выполняться ненадежные пользователи, выполняющие код.

Важно!

При использовании этого конструктора для именованных системных событий укажите false для initialStateпараметра . Этот конструктор не позволяет определить, было ли создано именованное системное событие, поэтому вы не можете делать никаких предположений о состоянии именованного события. Чтобы определить, было ли создано именованное событие, используйте 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

Когда данный метод возвращает значение, он содержит true, если было создано локальное событие (то есть, если name имеет значение 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 параметр игнорируется. После вызова этого конструктора используйте значение в переменной, указанное для ref параметра (ByRef параметр в Visual Basic),createdNew чтобы определить, существует ли именованное системное событие или было создано.

Если начальное состояние события не является подписанным, потоки, ожидающие события, будут блокироваться. Если исходное состояние сигнализируется, а ManualReset для задан modeфлаг , потоки, ожидающие события, не будут блокироваться. Если начальное состояние сигнализирует, а mode — AutoReset, первый поток, ожидающий события, будет немедленно освобожден, после чего событие сбрасывается, а последующие потоки блокируются.

Внимание!

По умолчанию именованное событие не ограничивается пользователем, который его создал. Другие пользователи могут открывать и использовать событие, в том числе вмешиваться в событие, устанавливая или сбрасывая его ненадлежащим образом. Чтобы ограничить доступ для определенных пользователей, можно использовать перегрузку конструктора или EventWaitHandleAcl и передать EventWaitHandleSecurity в при создании именованного события. Избегайте использования именованных событий без ограничений доступа в системах, в которых могут выполняться ненадежные пользователи, выполняющие код.

См. также раздел

• Обзор примитивов синхронизации