ISemaphore Interface

Namespace: Hazelcast.CP

Assembly: Hazelcast.Net.dll

Defines a CP distributed semaphore.

public interface ISemaphore : ICPDistributedObject, IDistributedObject, IAsyncDisposable

Inherited Members

ICPDistributedObject.GroupId

IDistributedObject.ServiceName

IDistributedObject.Name

IDistributedObject.PartitionKey

IDistributedObject.DestroyAsync()

IAsyncDisposable.DisposeAsync()

Remarks

ISemaphore is a fault-tolerant distributed semaphore. Semaphores are often used to restrict the number of threads than can access some physical or logical resource.

ISemaphore is a cluster-wide counting semaphore. Conceptually, it maintains a set of permits. Permits are acquired with the AcquireAsync(int) and TryAcquireAsync(int, long) functions, and released with the ReleaseAsync(int) function. No actual permit objects are used: the semaphore just keeps a count of the number available and acts accordingly.

Correct usage of a semaphore is established by programming convention in the application. A semaphore is obtained via

client.CPSubsystem.GetSemaphoreAsync(name)

and works on top of the Raft consensus algorithm. It offers linearizability during crash failures and network partitions. It is CP with respect to the CAP principle. If a network partition occurs, it remains available on at most one side of the partition.

There are two variations of the ISemaphore interface.

The default implementation is session-aware. When a caller interacts with the semaphore for the first time, it starts a new CP session within the underlying CP group. Liveliness of the session is then tracked via this CP session. Should the caller fails, permits acquired by this client are automatically and safely released.

Note however that a session-aware semaphore cannot release permits that have not been acquired beforehand; in other words it can only release previously acquired permits. It is possible to acquire a permit on one lock context, and release it on another lock context from the same client, but not from different clients.

The second impl offered by { @link CPSubsystem} is session-less. This implementation does not perform auto-cleanup of acquired permits on failures. Acquired permits are not bound to a client and permits can be released without being acquired first. This would be more compatible with Java's semaphore release mode. It can be enabled by enabling JDK compatibility when configuring the semaphore.

Note however that the user needs to handle failed permit owners on their own. If a server or a client fails while holding some permits, they will not be automatically released.

There is a subtle difference between the lock and semaphore abstractions.

A lock can be assigned to at most one endpoint at a time, so we have a total order among its holders. On the other hand, permits of a semaphore can be assigned to multiple endpoints at a time, which implies that we may not have a total order among permit holders. In fact, permit holders are partially ordered.

Methods

Name	Description
AcquireAsync(int)	Acquires permits immediately, if enough are available, and returns immediately.
DrainPermitsAsync()	Acquires and returns all permits that are available.
GetAvailablePermitsAsync()	Gets the number of available permits.
IncreasePermitsAsync(int)	Increases the number of available permits.
InitializeAsync(int)	Tries to initialize this semaphore instance with the specified number of permits.
ReducePermitsAsync(int)	Reduces the number of available permits.
ReleaseAsync(int)	Releases previously acquired permits.
TryAcquireAsync(int, long)	Tries to acquire permits, if enough are available, within the specified timeout duration.