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

      All Methods Instance Methods Abstract Methods 
      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 Detail

      • 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