Class LinearizableSemaphore

java.lang.Object
com.loomcache.server.cp.LinearizableSemaphore
public final class LinearizableSemaphore extends Object
Distributed semaphore for controlling access to a limited resource pool.

Purpose: A semaphore maintains a number of permits. Threads/processes can acquire permits (blocking if unavailable) and release them when done. This class supports both session-aware and sessionless modes.

Modes:

  • Session-aware: Resources are automatically released when the client session expires.
  • Sessionless: Client must manually release acquired permits.

Thread Safety: This class is thread-safe. Multiple threads can safely acquire/release permits concurrently.

Session-aware usage: callers must acquire and release permits with an active SessionManager.ManagedSession. Direct fixed-session ownership is not supported.

Example (Sessionless): 

LinearizableSemaphore sem = subsystem.getSemaphore("rate-limit", 10, false);
sem.acquire(1); // Get 1 permit
try {
    // Do work
} finally {
    sem.release(1); // Return permit
}
Since:
1.0

  • Constructor Summary

    Constructors
    Constructor
    Description
    LinearizableSemaphore(String semaphoreName, int permitCount, boolean sessionAware, @Nullable ConsistencySession session)
    Creates a new LinearizableSemaphore with the given permit count.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    acquire(int permits)
    Acquires the given number of permits, blocking until available.
    void
    acquire(int permits, @Nullable SessionManager.ManagedSession managedSession)
    Acquires the given number of permits on behalf of the provided managed session.
    int
    availablePermits()
    Gets the number of currently available permits.
    void
    forceRelease(int permits)
    Releases permits during session cleanup without mutating session bookkeeping again.
    boolean
    isValid()
    Checks if the session is still active (for session-aware semaphores).
    void
    release(int permits)
    Releases the given number of permits.
    void
    release(int permits, @Nullable SessionManager.ManagedSession managedSession)
    Releases the given number of permits on behalf of the provided managed session.
    String
    toString()
     
    boolean
    tryAcquire(int permits, long timeout, TimeUnit unit)
    Attempts to acquire permits within the given timeout.
    boolean
    tryAcquire(int permits, long timeout, TimeUnit unit, @Nullable SessionManager.ManagedSession managedSession)
    Attempts to acquire permits within the given timeout on behalf of the provided managed session.

    Methods inherited from class Object

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

  • Constructor Details

    • LinearizableSemaphore

      public LinearizableSemaphore(String semaphoreName, int permitCount, boolean sessionAware, @Nullable ConsistencySession session)
      Creates a new LinearizableSemaphore with the given permit count.
      Parameters:
      semaphoreName - the name of this semaphore (must not be null or empty)
      permitCount - the initial number of permits (must be non-negative)
      sessionAware - true for session-aware mode, false for sessionless
      session - must be null; fixed-session ownership is not supported
      Throws:
      NullPointerException - if semaphoreName is null
      IllegalArgumentException - if semaphoreName is empty, permitCount invalid input: '<' 0, or session is non-null

  • Method Details

    • acquire

      public void acquire(int permits) throws InterruptedException
      Acquires the given number of permits, blocking until available.
      Parameters:
      permits - the number of permits to acquire (must be positive)
      Throws:
      InterruptedException - if interrupted while waiting
      IllegalArgumentException - if permits invalid input: '<'= 0

    • acquire

      public void acquire(int permits, @Nullable SessionManager.ManagedSession managedSession) throws InterruptedException
      Acquires the given number of permits on behalf of the provided managed session.
      Parameters:
      permits - the number of permits to acquire (must be positive)
      managedSession - the managed session that will own the acquired permits, or null for sessionless/local use
      Throws:
      InterruptedException - if interrupted while waiting

    • tryAcquire

      public boolean tryAcquire(int permits, long timeout, TimeUnit unit) throws InterruptedException
      Attempts to acquire permits within the given timeout.
      Parameters:
      permits - the number of permits to acquire (must be positive)
      timeout - the maximum time to wait
      unit - the time unit of the timeout
      Returns:
      true if permits were acquired, false if timeout expired
      Throws:
      InterruptedException - if interrupted while waiting
      NullPointerException - if unit is null
      IllegalArgumentException - if permits invalid input: '<'= 0 or timeout invalid input: '<' 0

    • tryAcquire

      public boolean tryAcquire(int permits, long timeout, TimeUnit unit, @Nullable SessionManager.ManagedSession managedSession) throws InterruptedException
      Attempts to acquire permits within the given timeout on behalf of the provided managed session.
      Parameters:
      permits - the number of permits to acquire (must be positive)
      timeout - the maximum time to wait
      unit - the time unit of the timeout
      managedSession - the managed session that will own the acquired permits, or null for sessionless/local use
      Returns:
      true if permits were acquired, false if timeout expired
      Throws:
      InterruptedException - if interrupted while waiting

    • release

      public void release(int permits)
      Releases the given number of permits.

      In session-aware mode, permits are also tracked against the session.

      Parameters:
      permits - the number of permits to release (must be positive)
      Throws:
      IllegalArgumentException - if permits invalid input: '<'= 0 or more permits are released than acquired

    • release

      public void release(int permits, @Nullable SessionManager.ManagedSession managedSession)
      Releases the given number of permits on behalf of the provided managed session.
      Parameters:
      permits - the number of permits to release (must be positive)
      managedSession - the managed session releasing the permits, or null for sessionless/local use

    • forceRelease

      public void forceRelease(int permits)
      Releases permits during session cleanup without mutating session bookkeeping again.
      Parameters:
      permits - the number of permits to release

    • availablePermits

      public int availablePermits()
      Gets the number of currently available permits.
      Returns:
      the available permit count

    • isValid

      public boolean isValid()
      Checks if the session is still active (for session-aware semaphores).
      Returns:
      true if the session is active and the semaphore is valid

    • toString

      public String toString()
      Overrides:
      toString in class Object