A linearizable, distributed semaphore.
ISemaphore 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.
ISemaphore is a cluster-wide counting semaphore. Conceptually, it maintains
a set of permits. Each
acquire() waits if necessary until a permit
is available, and then takes it. Dually, each
release() adds a
permit, potentially releasing a waiting acquirer. However, no actual permit
objects are used; the semaphore just keeps a count of the number available
and acts accordingly.
This data structure also provides convenience methods to work with multiple permits at once. Beware of the increased risk of indefinite postponement when using the multiple-permit acquire. If permits are released one by one, a caller waiting for one permit will acquire it before a caller waiting for multiple permits regardless of the call order.
Correct usage of a semaphore is established by programming convention in the application.
ISemaphore has two variations:
Acquires the given number of permits if they are available, and returns immediately, reducing the number of available permits by the given amount.
If insufficient permits are available then the returned promise is not resolved until there are sufficient number of available permits or this ISemaphore is destroyed.
optional number of permits to acquire; defaults to
when not specified
Returns the current number of permits currently available in this semaphore.
This method is typically used for debugging and testing purposes.
the number of permits available in this semaphore
Destroys this object cluster-wide. Clears all resources taken for this object.
Acquires and returns all permits that are available at invocation time.
the number of permits drained
Returns the unique name of this object.
Returns the key of the partition that this DistributedObject is assigned to.
For a partitioned data structure, the returned value will not be
Returns the service name for this object.
Increases the number of available permits by the indicated amount. If there are some callers waiting for permits to become available, they will be notified. Moreover, if the caller has acquired some permits, they are not released with this call.
the number of permits to increase
Tries to initialize this ISemaphore instance with the given permit count.
the given permit count
true if initialization success;
false if already initialized
Reduces the number of available permits by the indicated amount. This
method differs from
acquire() as it does not block until permits
become available. Similarly, if the caller has acquired some permits,
they are not released with this call.
the number of permits to reduce
Releases the given number of permits and increases the number of available permits by that amount. If some callers in the cluster are waiting for acquiring permits, they will be notified.
If the underlying ISemaphore implementation is non-JDK-compatible
jdk-compatible server-side setting), then a client can
only release a permit which it has acquired before. In other words, a client
cannot release a permit without acquiring it first.
Otherwise, which means the default implementation, there is no such requirement for clients. A client can freely release a permit without acquiring it first. In this case, correct usage of a semaphore is established by programming convention in the application.
the number of permits to release
Acquires the given number of permits and returns
true, if they
become available during the given timeout. If permits are acquired,
the number of available permits in the ISemaphore instance is also
reduced by the given amount.
the number of permits to acquire; defaults to
when not specified
optional timeout in milliseconds to wait for the permits; when it's not specified the operation will return immediately after the acquire attempt
true if all permits were acquired,
false if the waiting
time elapsed before all permits could be acquired
Generated using TypeDoc