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)[source]

Kazoo Lock

Example usage with a KazooClient instance:

zk = KazooClient()
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.

__init__(client, path, identifier=None)[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.
acquire(blocking=True, timeout=None)[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.
Returns:

Was the lock acquired?

Return type:

bool

Raises:

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

New in version 1.1: The timeout 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.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.