kazoo.recipe.lock

Zookeeper Locking Implementations

Maintainer:

Ben Bangert <ben@groovie.org>

Status:

Production

Error Handling

It’s highly recommended to add a state listener with add_listener() and watch for LOST and SUSPENDED state changes and re-act appropriately. In the event that a LOST state occurs, its certain that the lock and/or the lease has been lost.

Public API

class kazoo.recipe.lock.Lock(client, path, identifier=None, extra_lock_patterns=())[source]

Kazoo Lock

Example usage with a KazooClient instance:

zk = KazooClient()
zk.start()
lock = zk.Lock("/lockpath", "my-identifier")
with lock:  # blocks waiting for lock acquisition
    # do something with the lock

Note: This lock is not re-entrant. Repeated calls after already acquired will block.

This is an exclusive lock. For a read/write lock, see WriteLock and ReadLock.

__init__(client, path, identifier=None, extra_lock_patterns=())[source]

Create a Kazoo lock.

Parameters:
  • client – A KazooClient instance.

  • path – The lock path to use.

  • identifier – Name to use for this lock contender. This can be useful for querying to see who the current lock contenders are.

  • extra_lock_patterns – Strings that will be used to identify other znode in the path that should be considered contenders for this lock. Use this for cross-implementation compatibility.

New in version 2.7.1: The extra_lock_patterns option.

acquire(blocking=True, timeout=None, ephemeral=True)[source]

Acquire the lock. By defaults blocks and waits forever.

Parameters:
  • blocking (bool) – Block until lock is obtained or return immediately.

  • timeout (float or None) – Don’t wait forever to acquire the lock.

  • ephemeral (bool) – Don’t use ephemeral znode for the lock.

Returns:

Was the lock acquired?

Return type:

bool

Raises:

LockTimeout if the lock wasn’t acquired within timeout seconds.

Warning

When ephemeral is set to False session expiration will not release the lock and must be handled separately.

New in version 1.1: The timeout option.

New in version 2.4.1: The ephemeral option.

cancel()[source]

Cancel a pending lock acquire.

contenders()[source]

Return an ordered list of the current contenders for the lock.

Note

If the contenders did not set an identifier, it will appear as a blank string.

release()[source]

Release the lock immediately.

class kazoo.recipe.lock.ReadLock(client, path, identifier=None, extra_lock_patterns=())[source]

Kazoo Read Lock

Example usage with a KazooClient instance:

zk = KazooClient()
zk.start()
lock = zk.ReadLock("/lockpath", "my-identifier")
with lock:  # blocks waiting for outstanding writers
    # do something with the lock

The lock path passed to WriteLock and ReadLock must match for them to communicate. The read lock blocks if it is held by any writers, but multiple readers may hold the lock.

Note: This lock is not re-entrant. Repeated calls after already acquired will block.

This is the read-side of a shared lock. See Lock for a standard exclusive lock and WriteLock for the write-side of a shared lock.

__init__(client, path, identifier=None, extra_lock_patterns=())

Create a Kazoo lock.

Parameters:
  • client – A KazooClient instance.

  • path – The lock path to use.

  • identifier – Name to use for this lock contender. This can be useful for querying to see who the current lock contenders are.

  • extra_lock_patterns – Strings that will be used to identify other znode in the path that should be considered contenders for this lock. Use this for cross-implementation compatibility.

New in version 2.7.1: The extra_lock_patterns option.

acquire(blocking=True, timeout=None, ephemeral=True)

Acquire the lock. By defaults blocks and waits forever.

Parameters:
  • blocking (bool) – Block until lock is obtained or return immediately.

  • timeout (float or None) – Don’t wait forever to acquire the lock.

  • ephemeral (bool) – Don’t use ephemeral znode for the lock.

Returns:

Was the lock acquired?

Return type:

bool

Raises:

LockTimeout if the lock wasn’t acquired within timeout seconds.

Warning

When ephemeral is set to False session expiration will not release the lock and must be handled separately.

New in version 1.1: The timeout option.

New in version 2.4.1: The ephemeral option.

cancel()

Cancel a pending lock acquire.

contenders()

Return an ordered list of the current contenders for the lock.

Note

If the contenders did not set an identifier, it will appear as a blank string.

release()

Release the lock immediately.

class kazoo.recipe.lock.WriteLock(client, path, identifier=None, extra_lock_patterns=())[source]

Kazoo Write Lock

Example usage with a KazooClient instance:

zk = KazooClient()
zk.start()
lock = zk.WriteLock("/lockpath", "my-identifier")
with lock:  # blocks waiting for lock acquisition
    # do something with the lock

The lock path passed to WriteLock and ReadLock must match for them to communicate. The write lock can not be acquired if it is held by any readers or writers.

Note: This lock is not re-entrant. Repeated calls after already acquired will block.

This is the write-side of a shared lock. See Lock for a standard exclusive lock and ReadLock for the read-side of a shared lock.

__init__(client, path, identifier=None, extra_lock_patterns=())

Create a Kazoo lock.

Parameters:
  • client – A KazooClient instance.

  • path – The lock path to use.

  • identifier – Name to use for this lock contender. This can be useful for querying to see who the current lock contenders are.

  • extra_lock_patterns – Strings that will be used to identify other znode in the path that should be considered contenders for this lock. Use this for cross-implementation compatibility.

New in version 2.7.1: The extra_lock_patterns option.

acquire(blocking=True, timeout=None, ephemeral=True)

Acquire the lock. By defaults blocks and waits forever.

Parameters:
  • blocking (bool) – Block until lock is obtained or return immediately.

  • timeout (float or None) – Don’t wait forever to acquire the lock.

  • ephemeral (bool) – Don’t use ephemeral znode for the lock.

Returns:

Was the lock acquired?

Return type:

bool

Raises:

LockTimeout if the lock wasn’t acquired within timeout seconds.

Warning

When ephemeral is set to False session expiration will not release the lock and must be handled separately.

New in version 1.1: The timeout option.

New in version 2.4.1: The ephemeral option.

cancel()

Cancel a pending lock acquire.

contenders()

Return an ordered list of the current contenders for the lock.

Note

If the contenders did not set an identifier, it will appear as a blank string.

release()

Release the lock immediately.

class kazoo.recipe.lock.Semaphore(client, path, identifier=None, max_leases=1)[source]

A Zookeeper-based Semaphore

This synchronization primitive operates in the same manner as the Python threading version only uses the concept of leases to indicate how many available leases are available for the lock rather than counting.

Note: This lock is not meant to be re-entrant.

Example:

zk = KazooClient()
semaphore = zk.Semaphore("/leasepath", "my-identifier")
with semaphore:  # blocks waiting for lock acquisition
    # do something with the semaphore

Warning

This class stores the allowed max_leases as the data on the top-level semaphore node. The stored value is checked once against the max_leases of each instance. This check is performed when acquire is called the first time. The semaphore node needs to be deleted to change the allowed leases.

New in version 0.6: The Semaphore class.

New in version 1.1: The max_leases check.

__init__(client, path, identifier=None, max_leases=1)[source]

Create a Kazoo Lock

Parameters:
  • client – A KazooClient instance.

  • path – The semaphore path to use.

  • identifier – Name to use for this lock contender. This can be useful for querying to see who the current lock contenders are.

  • max_leases – The maximum amount of leases available for the semaphore.

acquire(blocking=True, timeout=None)[source]

Acquire the semaphore. By defaults blocks and waits forever.

Parameters:
  • blocking (bool) – Block until semaphore is obtained or return immediately.

  • timeout (float or None) – Don’t wait forever to acquire the semaphore.

Returns:

Was the semaphore acquired?

Return type:

bool

Raises:

ValueError if the max_leases value doesn’t match the stored value.

LockTimeout if the semaphore wasn’t acquired within timeout seconds.

New in version 1.1: The blocking, timeout arguments and the max_leases check.

cancel()[source]

Cancel a pending semaphore acquire.

lease_holders()[source]

Return an unordered list of the current lease holders.

Note

If the lease holder did not set an identifier, it will appear as a blank string.

release()[source]

Release the lease immediately.