Package io.pravega.common.concurrent

Class AsyncSemaphore

  • All Implemented Interfaces:
    java.lang.AutoCloseable
    @ThreadSafe
public class AsyncSemaphore
extends java.lang.Object
implements java.lang.AutoCloseable
    A synchronization primitive that allows executing arbitrary (concurrent) tasks, where each task requires a well-known number of credits, subject to a total number of credits being available. Each task's successful execution will "borrow" its share of credits, and a task cannot execute if the number of credits available is insufficient. Credits may be restored externally using the release(long) method. This is similar to Semaphore, except that this class allows for asynchronous processing and each task can request an arbitrary number of credits. It can be useful in solving problems making use of the Leaky Bucket Algorithm (https://en.wikipedia.org/wiki/Leaky_bucket).

    • Constructor Summary

      Constructors 
      Constructor Description
      AsyncSemaphore​(long totalCredits, long usedCredits, java.lang.String logId)
      Creates a new instance of the AsyncSemaphore class.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      void close()  
      long getUsedCredits()
      Gets the current number of used credits.
      void release​(long credits)
      Releases a number of credits back into the pool and initiates the execution of any pending tasks that are now eligible to run.
      <T> java.util.concurrent.CompletableFuture<T> run​(@NonNull java.util.function.Supplier<java.util.concurrent.CompletableFuture<T>> task, long credits, boolean force)
      Executes the given task which requires the given number of credits.
      java.lang.String toString()  

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

    • Constructor Detail

      • AsyncSemaphore

        public AsyncSemaphore​(long totalCredits,
                      long usedCredits,
                      java.lang.String logId)
        Creates a new instance of the AsyncSemaphore class.
        Parameters:
        totalCredits - Total number of available credits.
        usedCredits - Initial number of used credits.
        logId - A log-friendly identifier for this AsyncSemaphore.

    • Method Detail

      • close

        public void close()
        Specified by:
        close in interface java.lang.AutoCloseable

      • run

        public <T> java.util.concurrent.CompletableFuture<T> run​(@NonNull
                                                         @NonNull java.util.function.Supplier<java.util.concurrent.CompletableFuture<T>> task,
                                                         long credits,
                                                         boolean force)
        Executes the given task which requires the given number of credits. If there are sufficient credits available for this task to run, it will be invoked synchronously and the returned result is directly provided by the given task. If there are insufficient credits available for this task to run, it will be queued up and executed when credits become available. There is no prioritization of queued tasks - they are triggered in the order in which they are queued up. If the force flag is set, then the task will be invoked synchronously, even if there are insufficient credits. In this case, the getUsedCredits() will exceed the max allowed credits and no other (non-forced) task will be allowed to execute until getUsedCredits() falls below the max allowed. A task will allocate the requested credits when it is triggered. If the task fails (synchronously or asynchronously), then the requested credits are automatically released back into the pool. If the task succeeds, the credits will remain.
        Type Parameters:
        T - Return type.
        Parameters:
        task - A Supplier that, when invoked, will execute the task.
        credits - The number of credits this task requires.
        force - If true, the task will be executed synchronously regardless of how many credits are available. The task's credits are still recorded in this case.
        Returns:
        A CompletableFuture that, when completed, will contain the result of the executed task. If the task failed or was rejected (i.e., due to AsyncSemaphore closing), it will be failed with the appropriate exception.

      • release

        public void release​(long credits)
        Releases a number of credits back into the pool and initiates the execution of any pending tasks that are now eligible to run.
        Parameters:
        credits - The number of credits to release. This number will be capped at the number of currently used credits (getUsedCredits()).

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object

      • getUsedCredits

        public long getUsedCredits()
        Gets the current number of used credits.
        Returns:
        The current number of used credits.