System.SyncObjs.TSemaphore.Create

From RAD Studio API Documentation
Jump to: navigation, search

Delphi

constructor Create(UseCOMWait: Boolean = False); overload;
constructor Create(SemaphoreAttributes: PSecurityAttributes; AInitialCount, AMaximumCount: Integer; const Name: string; UseCOMWait: Boolean = False); overload;
constructor Create(DesiredAccess: Cardinal; InheritHandle: Boolean; const Name: string; UseCOMWait: Boolean = False); overload;

C++

__fastcall TSemaphore(bool UseCOMWait)/* overload */;
__fastcall TSemaphore(Winapi::Windows::PSecurityAttributes SemaphoreAttributes, int AInitialCount, int AMaximumCount, const System::UnicodeString Name, bool UseCOMWait)/* overload */;
__fastcall TSemaphore(unsigned DesiredAccess, bool InheritHandle, const System::UnicodeString Name, bool UseCOMWait)/* overload */;

Properties

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

Description

Instantiates a TSemaphore object.

Call Create to create a TSemaphore object.

System.SyncObjs.TSemaphore.Create constructor has three versions

  • The first version of the constructor creates an unnamed binary semaphore with an initial counter value of one, which is created with the default security descriptor.
This means that the child processes of the current process cannot inherit the handle to this semaphore. This is basically equivalent to creating an unnamed TMutex object.
Tip: Set the UseCOMWait parameter 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 version of the constructor creates a named semaphore with several attributes, given through the following list of parameters:

Parameter

Meaning

SemaphoreAttributes

The security attributes of the semaphore. SemaphoreAttributes is of a pointer type to a _SECURITY_ATTRIBUTES record, with the following fields: nLength, lpSecurityDescriptor, InheritHandle.

The nLength field should always be equal to the size, in bytes, of the _SECURITY_ATTRIBUTES record. lpSecurityDescriptor is a pointer to the security descriptor of the semaphore. Finally, InheritHandle is True if the handle to the semaphore is to be inherited by child processes.

AInitialCount

The initial value of the semaphore counter variable, giving the initial number of free units of the shared resource.

AMaximumCount

The maximum value of the semaphore counter variable, giving the number of available units of the shared resource.

Name

The name of the semaphore. Names are case-sensitive.

UseCOMWait

Set this parameter in order to ensure that when a thread is blocked and waiting for the object, any STA COM calls can still be made back into this thread.

  • The third version of the constructor allows opening an existing semaphore, identified by its name. The parameters have the following meaning:

Parameter

Meaning

DesiredAccess

The type of access to the semaphore. The constructor fails if the requested type of access is not permitted. It can be any combination of the following constants: SEMAPHORE_ALL_ACCESS, SEMAPHORE_MODIFY_STATE, SYNCHRONIZE, _DELETE, READ_CONTROL, WRITE_DAC, WRITE_OWNER.

InheritHandle

Set this parameter for the child processes to inherit the handle.

Name

The name of the semaphore to open. Names are case-sensitive.

UseCOMWait

Set this parameter in order to ensure that when a thread is blocked and waiting for the object, any STA COM calls can still be made back into this thread.

See Also