ISemaphore Interface
Namespace: Hazelcast.CP
Assembly: Hazelcast.Net.dll
Defines a CP distributed semaphore.
public interface ISemaphore : ICPDistributedObject, IDistributedObject, IAsyncDisposableInherited Members
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.
<p>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.</p>
<p>There are two variations of the <xref href="Hazelcast.CP.ISemaphore" data-throw-if-not-resolved="false"></xref> interface.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>There is a subtle difference between the lock and semaphore abstractions.</p>
<p>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.</p>
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. |