Package com.atlassian.bamboo.beehive

Interface BambooClusterLockService

All Superinterfaces:
com.atlassian.beehive.ClusterLockService, com.atlassian.beehive.core.ManagedClusterLockService
All Known Implementing Classes:
BambooClusterLockServiceImpl
@Internal public interface BambooClusterLockService extends com.atlassian.beehive.core.ManagedClusterLockService
Supports mutual exclusion operations in a cluster environment.
Since:
9.5

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    lockForReading(String lockName, long lockTimeoutSeconds)
    Locks for READING the lock identified by the given name.
    void
    lockForWriting(String lockName, long lockTimeoutSeconds)
    Locks for READING the lock identified by the given name.
    void
    releaseLock(@NotNull String lockName)
    Release ownership of a named lock by current cluster node.
    void
    releaseLocksHeldByNode()
    Releases any locks held by the this node.
    void
    releaseReadLock(@NotNull String lockName)
    Release READ ownership of a named lock by current cluster node.
    void
    releaseWriteLock(@NotNull String lockName)
    Release READ ownership of a named lock by current cluster node.
    void
    resetDatabaseState()
    Reset internal state of the locks to adjust to external changes in tables used by DAO at runtime.
    void
    shutdown()
    Shuts the service down, stopping all accessory jobs (e..g: lock renewer) for all locks.
    boolean
    tryAcquireLock(@NotNull String lockName, long lockTimeoutSeconds)
    Attempts to acquire ownership of a named lock by current cluster node.
    boolean
    tryAcquireReadLock(@NotNull String lockName, long lockTimeoutSeconds)
    Attempts to acquire READ ownership of a named lock by current cluster node.
    boolean
    tryAcquireWriteLock(@NotNull String lockName, long lockTimeoutSeconds)
    AttemptS to acquire WRITE ownership of a named lock by current cluster node.
    void
    unlockForReading(String lockName)
    Unlocks the READING part of the lock identified by the given name.
    void
    unlockForWriting(String lockName)
    Unlocks the WRITING part of the lock identified by the given name.

    Methods inherited from interface com.atlassian.beehive.ClusterLockService

    getLockForName

    Methods inherited from interface com.atlassian.beehive.core.ManagedClusterLockService

    getAllKnownClusterLocks, getStatusesOfAllHeldClusterLocks

  • Method Details

    • releaseLocksHeldByNode

      void releaseLocksHeldByNode()
      Releases any locks held by the this node.
      Since:
      9.5

    • resetDatabaseState

      void resetDatabaseState()
      Reset internal state of the locks to adjust to external changes in tables used by DAO at runtime.
      Since:
      9.5

    • tryAcquireLock

      boolean tryAcquireLock(@NotNull @NotNull String lockName, long lockTimeoutSeconds)
      Attempts to acquire ownership of a named lock by current cluster node. A lock should be treated as eligible to be acquired when one of the following is true:
      • It has no node set as an owner
      • It has the current node set as an owner
      • It has an other node set as an owner, but its last update time is older than the specified timeout
      Parameters:
      lockName - the globally unique id of the lock
      lockTimeoutSeconds - time (in seconds) after which the lock can be taken over
      Returns:
      true if we acquired the lock, false if the locks already has a valid owner.
      Since:
      9.5

    • releaseLock

      void releaseLock(@NotNull @NotNull String lockName)
      Release ownership of a named lock by current cluster node.
      Parameters:
      lockName - the globally unique id of the lock
      Since:
      9.5

    • lockForReading

      void lockForReading(@Nonnull String lockName, long lockTimeoutSeconds)
      Locks for READING the lock identified by the given name. A READ lock should be treated as eligible to be acquired when one of the following is true:
      • It has no node set as an owner of correspondent WRITE lock
      • It has an node set as an owner of correspondent WRITE lock, but its last update time is older than the specified time
      This method waits (Thread.sleep()) for the WRITE lock to be released in case it is taken. For an implementation with immediate success/failure, take a look at tryAcquireReadLock(String, long).

      Important: this is a NON-REENTRANT implementation, i.e., if the node tries to acquire a lock that it already owns, then it will not be granted. Rationale: reentrant implementation requires mechanism to track re-entrancies in order to prevent releasing the lock before all operations are completed. It can be considered in the future.

      There is no limit for the number of nodes that can acquire READ lock simultaneously, but only one can acquire the correspondent WRITE (see lockForWriting(String, long).

      Make sure that unlockForReading(String) is called in a try...finally block.

      *

      Parameters:
      lockName - the globally unique id of the lock
      lockTimeoutSeconds - time (in seconds) after which an existing WRITE lock doesn't block the READ ones anymore
      Since:
      9.5

    • unlockForReading

      void unlockForReading(@Nonnull String lockName)
      Unlocks the READING part of the lock identified by the given name.
      Parameters:
      lockName - the globally unique id of the lock
      Since:
      9.5

    • lockForWriting

      void lockForWriting(@Nonnull String lockName, long lockTimeoutSeconds)
      Locks for READING the lock identified by the given name. A WRITE lock should be treated as eligible to be acquired when one of the following is true:
      • It has no node set as an owner of correspondent WRITE lock
      • It has no node set as an owner of any correspondent READ locks
      • It has nodes set as owners of correspondent READ/WRITE locks, but their last update times are older than the specified time
      This method waits (Thread.sleep()) for the READ/WRITE locks to be released in case they are taken. For an implementation with immediate success/failure, take a look at tryAcquireWriteLock(String, long).

      Important: this is a NON-REENTRANT implementation, i.e., if the node tries to acquire a lock that it already owns, then it will not be granted. Rationale: reentrant implementation requires mechanism to track re-entrancies in order to prevent releasing the lock before all operations are completed. It can be considered in the future.

      There is no limit for the number of nodes that can acquire READ lock simultaneously, but only one can acquire the correspondent WRITE.

      Make sure that unlockForWriting(String) is called in a try...finally block.

      *

      Parameters:
      lockName - the globally unique id of the lock
      lockTimeoutSeconds - time (in seconds) after which an existing WRITE lock doesn't block the READ ones anymore
      Since:
      9.5

    • unlockForWriting

      void unlockForWriting(@Nonnull String lockName)
      Unlocks the WRITING part of the lock identified by the given name.
      Parameters:
      lockName - the globally unique id of the lock
      Since:
      9.5

    • tryAcquireReadLock

      boolean tryAcquireReadLock(@NotNull @NotNull String lockName, long lockTimeoutSeconds)
      Attempts to acquire READ ownership of a named lock by current cluster node. A READ lock should be treated as eligible to be acquired when one of the following is true:
      • It has no node set as an owner of correspondent WRITE lock
      • It has an node set as an owner of correspondent WRITE lock, but its last update time is older than the specified time
      Important: this is a NON-REENTRANT implementation, i.e., if the node tries to acquire a lock that it already owns, then it will not be granted. Rationale: reentrant implementation requires mechanism to track reentrancies in order to prevent releasing the lock before all operations are completed. It can be considered in the future.

      There is no limit for the number of nodes that can acquire READ lock simultaneously, but only one can acquire the correspondent WRITE (see tryAcquireWriteLock(String,long).

      Make sure that releaseReadLock(String) is called properly.

      There is no central entity managing a waiting list and granting permissions based on some criterion. Therefore, clients will be granted or denied immediately and it's up to them to try again.

      Parameters:
      lockName - the globally unique id of the lock
      lockTimeoutSeconds - time (in seconds) after which an existing WRITE lock doesn't block the READ ones
      Returns:
      true if we acquired the READ lock, false otherwise.
      Since:
      9.5

    • releaseReadLock

      void releaseReadLock(@NotNull @NotNull String lockName)
      Release READ ownership of a named lock by current cluster node.
      Parameters:
      lockName - the globally unique id of the lock
      Since:
      9.5

    • tryAcquireWriteLock

      boolean tryAcquireWriteLock(@NotNull @NotNull String lockName, long lockTimeoutSeconds)
      AttemptS to acquire WRITE ownership of a named lock by current cluster node. A WRITE lock should be treated as eligible to be acquired when one of the following is true:
      • It has no node set as an owner of correspondent WRITE lock
      • It has no node set as an owner of correspondent READ locks
      • It has nodes set as owners of correspondent READ/WRITE locks, but their last update times are older than the specified time
      Important: this is a NON-REENTRANT implementation, i.e., if the node tries to acquire a lock that it already owns, then it will not be granted. Rationale: reentrant implementation requires mechanism to track reentrancies in order to prevent releasing the lock before all operations are completed. It can be considered in the future.

      There is no limit for the number of nodes that can acquire READ lock simultaneously, but only one can acquire the correspondent WRITE.

      Make sure that releaseReadLock(String) is called properly.

      There is no central entity managing a waiting list and granting permissions based on some criterion. Therefore, clients will be granted or denied immediately and it's up to them to try again.

      Parameters:
      lockName - the globally unique id of the lock
      lockTimeoutSeconds - time (in seconds) after which the WRITE lock can be taken over
      Returns:
      true if we acquired the WRITE lock, false otherwise.
      Since:
      9.5

    • releaseWriteLock

      void releaseWriteLock(@NotNull @NotNull String lockName)
      Release READ ownership of a named lock by current cluster node.
      Parameters:
      lockName - the globally unique id of the lock
      Since:
      9.5

    • shutdown

      void shutdown()
      Shuts the service down, stopping all accessory jobs (e..g: lock renewer) for all locks.
      Since:
      9.4.0