Package dev.getelements.elements.sdk.util

Interface Monitor

All Superinterfaces:
AutoCloseable
public interface Monitor extends AutoCloseable
Convenience wrapper to automatically manage the state of an underlying lock, series of locks, or semaphores. This can be used to ensure that multiple locks or semaphores are acquired in consistent order (avoiding deadlock) and are automatically released when the critical section of code executes. Note, per the AutoCloseable.close() documentation Monitor instances are not idempotent unless explicitly stated, such as in the return of idempotent().

  • Method Details

    • close

      void close()
      Releases the underlying Lock or Semaphore
      Specified by:
      close in interface AutoCloseable

    • then

      default Monitor then(Lock lock)
      Acquires a monitor which will release the lock after this monitor closes. enter(Lock)
      Parameters:
      lock - the lock
      Returns:
      a new Monitor

    • then

      default Monitor then(Semaphore semaphore)
      Acquires a monitor which will release the semaphore after this monitor closes. enter(Semaphore)
      Parameters:
      semaphore - the semaphore
      Returns:
      a new Monitor

    • then

      default Monitor then(Semaphore semaphore, int permits)
      Acquires a monitor which will release the lock after this monitor closes. enter(Semaphore,int)
      Parameters:
      semaphore - the semaphore
      permits - the permits to acquire
      Returns:
      a new Monitor

    • then

      default Monitor then(Monitor other)
      Acquires a monitor which will release the lock after this monitor closes. This ensures that when multiple monitors are chained together then they are released in the reverse order. enter(Semaphore,int)
      Parameters:
      other - the other monitor
      Returns:
      a new Monitor

    • empty

      static Monitor empty()
      Returns an empty monitor. The rationale is that this can be the start of a chain of monitors within a critical section of code ensuring that all get unwound properly as the chain is built.
      Returns:
      an empty monitor

    • idempotent

      default Monitor idempotent()
      Per the definition of AutoCloseable.close(), Monitor instances are not idempotent. This method returns a Monitor which is idempotent. Calling close() multiple times will ensure that all previously chained calls are only performed once. More complicated Monitor instances may be naturally idempotent which means that this may not be necessary.
      Returns:
      a Monitor which makes this and all previously chained Monitor instances idempotent

    • enter

      static Monitor enter(Lock lock)
      Generates a Monitor from the supplied Lock instance.
      Parameters:
      lock - the Lock instance
      Returns:
      a new Monitor

    • enter

      static Monitor enter(Semaphore semaphore)
      Generates a Monitor from the supplied Semaphore instance.
      Parameters:
      semaphore - the Semaphore instance
      Returns:
      a new Monitor

    • enter

      static Monitor enter(Semaphore semaphore, int permits)
      Generates a Monitor from the supplied Semaphore instance.
      Parameters:
      semaphore - the Semaphore instance
      permits - the number of permits to acquire and subsequently release
      Returns:
      a Monitor which will immediately unlock