SemaphoreAcl.Create(Int32, Int32, String, Boolean, SemaphoreSecurity) Method

Definition

Namespace:

System.Threading

Assembly:

System.Threading.AccessControl.dll

Gets or creates an Semaphore instance, allowing a SemaphoreSecurity instance to be optionally specified to set it during the event creation.

public:
 static System::Threading::Semaphore ^ Create(int initialCount, int maximumCount, System::String ^ name, [Runtime::InteropServices::Out] bool % createdNew, System::Security::AccessControl::SemaphoreSecurity ^ semaphoreSecurity);

public static System.Threading.Semaphore Create (int initialCount, int maximumCount, string? name, out bool createdNew, System.Security.AccessControl.SemaphoreSecurity? semaphoreSecurity);

static member Create : int * int * string * bool * System.Security.AccessControl.SemaphoreSecurity -> System.Threading.Semaphore

Public Shared Function Create (initialCount As Integer, maximumCount As Integer, name As String, ByRef createdNew As Boolean, semaphoreSecurity As SemaphoreSecurity) As Semaphore

Parameters

initialCount

Int32

The initial number of requests for the semaphore that can be satisfied concurrently.

maximumCount

Int32

The maximum number of requests for the semaphore that can be satisfied concurrently.

name

String

The name, if the synchronization object is to be shared with other processes; otherwise, null or an empty string. The name is case-sensitive. The backslash character (\) is reserved and may only be used to specify a namespace. For more information on namespaces, see the remarks section. There may be further restrictions on the name depending on the operating system. For example, on Unix-based operating systems, the name after excluding the namespace must be a valid file name.

createdNew

Boolean

When this method returns, this argument is always set to true if a local semaphore is created; that is, when name is null or Empty. If name has a valid, non-empty value, this argument is set to true when the system semaphore is created, or it is set to false if an existing system semaphore is found with that name. This parameter is passed uninitialized.

semaphoreSecurity

SemaphoreSecurity

The optional semaphore access control security to apply.

Returns

Semaphore

An object that represents a system semaphore, if named, or a local semaphore, if nameless.

Exceptions

ArgumentOutOfRangeException

initialCount is a negative number. -or-

maximumCount is not a positive number.

ArgumentException

initialCount is greater than maximumCount.

-or-

.NET Framework only: name is longer than MAX_PATH (260 characters).

IOException

name is invalid. This can be for various reasons, including some restrictions that may be placed by the operating system, such as an unknown prefix or invalid characters. Note that the name and common prefixes "Global\" and "Local\" are case-sensitive.

-or-

There was some other error. The HResult property may provide more information.

DirectoryNotFoundException

Windows only: name specified an unknown namespace. See Object Names for more information.

PathTooLongException

The name is too long. Length restrictions may depend on the operating system or configuration.

WaitHandleCannotBeOpenedException

A synchronization object with the provided name cannot be created. A synchronization object of a different type might have the same name.

Remarks

The name may be prefixed with Global\ or Local\ to specify a namespace. When the Global namespace is specified, the synchronization object may be shared with any processes on the system. When the Local namespace is specified, which is also the default when no namespace is specified, the synchronization object may be shared with processes in the same session. On Windows, a session is a login session, and services typically run in a different non-interactive session. On Unix-like operating systems, each shell has its own session. Session-local synchronization objects may be appropriate for synchronizing between processes with a parent/child relationship where they all run in the same session. For more information about synchronization object names on Windows, see Object Names.

If a name is provided and a synchronization object of the requested type already exists in the namespace, the existing synchronization object is opened. If a synchronization object of a different type already exists in the namespace, a WaitHandleCannotBeOpenedException is thrown. Otherwise, a new synchronization object is created.

Caution

By default, a named semaphore is not restricted to the user that created it. Other users may be able to open and use the semaphore, including interfering with the semaphore by acquiring the semaphore multiple times and not releasing it. To restrict access to specific users, you can pass in a SemaphoreSecurity when creating the named semaphore. Avoid using named semaphores without access restrictions on systems that might have untrusted users running code.