System.SyncObjs.TEvent.Create

From RAD Studio API Documentation
Jump to: navigation, search

Delphi

constructor Create(EventAttributes: PSecurityAttributes; ManualReset,  InitialState: Boolean; const Name: string; UseCOMWait: Boolean = False); overload;
constructor Create(UseCOMWait: Boolean = False); overload;

C++

__fastcall TEvent(Winapi::Windows::PSecurityAttributes EventAttributes, bool ManualReset, bool InitialState, const System::UnicodeString Name, bool UseCOMWait)/* overload */;
__fastcall TEvent(bool UseCOMWait)/* overload */;

Properties

Type Visibility Source Unit Parent
constructor public
System.SyncObjs.pas
System.SyncObjs.hpp
System.SyncObjs TEvent

Description

Instantiates a TEvent object to represent an event object.

Call Create to create a TEvent object. Create can generate a new event object or can provide access to an existing named event object.

The first overloaded constructor sets the following parameters:

  • Set the EventAttributes parameter to specify the access rights and inheritance capabilities of the new event object. Calling Create with EventAttributes set to nil (Delphi) or NULL (C++) creates an event object with a default set of security attributes. If the TEvent object is created to access an existing named event object, only the bInheritHandle field of EventAttributes is used, as the access rights were determined when the event object was created.
  • Set ManualReset to specify whether the signal of the TEvent object can only be turned off by a call to the ResetEvent method, or whether it is automatically reset when a single waiting thread is released. When ManualReset is true, the TEvent signal stays set until the ResetEvent method turns it off. When ManualReset is false, the signal is automatically turned off when only a single thread waits on the signal and that thread is released. If the TEvent object is created to access an existing named event object, the ManualReset parameter is ignored.
  • Set InitialState to indicate whether the TEvent object should be created with the signal set, or turned off. When InitialState is true, the TEvent object is created with the signal set. If the TEvent object is created to access an existing named event object, the InitialState parameter is ignored.
  • Set Name to provide a name for a new event object or to specify an existing named event object. If no other thread or process will need to access the event object to wait for its signal, Name can be left blank. Name can be a string of up to 260 characters, not including the backslash character (\). If Name is used to specify an existing event object, the value must match the name of the existing event in a case-sensitive comparison. If Name matches the name of an existing semaphore, mutex, or file-mapping object, the TEvent object will be created with Handle set to 0 and all method calls will fail.
  • Set UseCOMWait to True to ensure that when a thread is blocked and waiting for the object, any STA COM calls can be made back into this thread.

The second overloaded constructor only accepts the UseCOMWait parameter. This constructor creates an event with null event attributes, manual reset, not initially signaled, and an empty name.

See Also