Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# `gevent.lock` – Locking primitives

Locking primitives.

These include semaphores with arbitrary bounds (`Semaphore` and its safer subclass `BoundedSemaphore`) and a semaphore with infinite bounds (`DummySemaphore`), along with a reentrant lock (`RLock`) with the same API as `threading.RLock`.

class BoundedSemaphore(value=1)

  Bases: `_AtomicSemaphoreMixin`, `BoundedSemaphore`

  A bounded semaphore checks to make sure its current value doesn’t exceed its initial value. If it does, `ValueError` is raised. In most situations semaphores are used to guard resources with limited capacity. If the semaphore is released too many times it’s a sign of a bug.

  If not given, value defaults to 1.

  acquire(blocking=True, timeout=None) → bool

    Acquire the semaphore.

    Note

    If this semaphore was initialized with a value of 0, this method will block forever (unless a timeout is given or blocking is set to false).

    Parameters:

      - blocking (bool) – If True (the default), this function will block until the semaphore is acquired.

      - timeout (float) – If given, and blocking is true, specifies the maximum amount of seconds this method will block.

    Returns:

      A `bool` indicating whether the semaphore was acquired. If `blocking` is True and `timeout` is None (the default), then (so long as this semaphore was initialized with a size greater than 0) this will always return True. If a timeout was given, and it expired before the semaphore was acquired, False will be returned. (Note that this can still raise a `Timeout` exception, if some other caller had already started a timer.)

  locked()

    Return a boolean indicating whether the semaphore can be acquired (`False` if the semaphore can be acquired). Most useful with binary semaphores (those with an initial value of 1).

    Return type:

      bool

  rawlink(callback)

    Register a callback to call when this object is ready.

    callback will be called in the `Hub`, so it must not use blocking gevent API. callback will be passed one argument: this instance.

  ready()

    Return a boolean indicating whether the semaphore can be acquired (`True` if the semaphore can be acquired).

    Return type:

      bool

  release()

    Like `Semaphore.release()`, but raises `ValueError` if the semaphore is being over-released.

  unlink(callback)

    Remove the callback set by `rawlink()`

  wait(timeout=None)

    Wait until it is possible to acquire this semaphore, or until the optional timeout elapses.

    Note

    If this semaphore was initialized with a value of 0, this method will block forever if no timeout is given.

    Parameters:

      timeout (float) – If given, specifies the maximum amount of seconds this method will block.

    Returns:

      A number indicating how many times the semaphore can be acquired before blocking. This could be 0, if other waiters acquired the semaphore.

    Return type:

      int

class DummySemaphore(value=None)

  Bases: `object`

  An object with the same API as `Semaphore`, initialized with “infinite” initial value. None of its methods ever block.

  This can be used to parameterize on whether or not to actually guard access to a potentially limited resource. If the resource is actually limited, such as a fixed-size thread pool, use a real `Semaphore`, but if the resource is unbounded, use an instance of this class. In that way none of the supporting code needs to change.

  Similarly, it can be used to parameterize on whether or not to enforce mutual exclusion to some underlying object. If the underlying object is known to be thread-safe itself mutual exclusion is not needed and a `DummySemaphore` can be used, but if that’s not true, use a real `Semaphore`.

  Changed in version 1.1rc3: Accept and ignore a value argument for compatibility with Semaphore.

  acquire(blocking=True, timeout=None)

    A DummySemaphore can always be acquired immediately so this always returns True and ignores its arguments.

    Changed in version 1.1a1: Always return true.

  locked()

    A DummySemaphore is never locked so this always returns False.

  ready()

    A DummySemaphore is never locked so this always returns True.

  release()

    Releasing a dummy semaphore does nothing.

  wait(timeout=None)

    Waiting for a DummySemaphore returns immediately.

class RLock(hub=None)

  Bases: `object`

  A mutex that can be acquired more than once by the same greenlet.

  A mutex can only be locked by one greenlet at a time. A single greenlet can `acquire` the mutex as many times as desired, though. Each call to `acquire` must be paired with a matching call to `release`.

  It is an error for a greenlet that has not acquired the mutex to release it.

  Instances are context managers.

  Changed in version 20.5.1: Add the `hub` argument.

  acquire(blocking=True, timeout=None)

    Acquire the mutex, blocking if blocking is true, for up to timeout seconds.

    Changed in version 1.5a4: Added the timeout parameter.

    Returns:

      A boolean indicating whether the mutex was acquired.

  release()

    Release the mutex.

    Only the greenlet that originally acquired the mutex can release it.

class Semaphore(value=1)

  Bases: `_AtomicSemaphoreMixin`, `Semaphore`

  See also

  `BoundedSemaphore` for a safer version that prevents some classes of bugs. If unsure, most users should opt for `BoundedSemaphore`.

  A semaphore manages a counter representing the number of `release` calls minus the number of `acquire` calls, plus an initial value. The `acquire` method blocks if necessary until it can return without making the counter negative. A semaphore does not track ownership by greenlets; any greenlet can call `release`, whether or not it has previously called `acquire`.

  If not given, `value` defaults to 1.

  The semaphore is a context manager and can be used in `with` statements.

  This Semaphore’s `__exit__` method does not call the trace function on CPython, but does under PyPy.

  Changed in version 1.4.0: Document that the order in which waiters are awakened is not specified. It was not specified previously, but due to CPython implementation quirks usually went in FIFO order.

  Changed in version 1.5a3: Waiting greenlets are now awakened in the order in which they waited.

  Changed in version 1.5a3: The low-level `rawlink` method (most users won’t use this) now automatically unlinks waiters before calling them.

  Changed in version 20.12.0: Improved support for multi-threaded usage. When multi-threaded usage is detected, instances will no longer create the thread’s hub if it’s not present.

  Changed in version 24.2.1: Uses Python 3 native lock timeouts for cross-thread operations instead of spinning.

  acquire(blocking=True, timeout=None) → bool

    Acquire the semaphore.

    Note

    If this semaphore was initialized with a value of 0, this method will block forever (unless a timeout is given or blocking is set to false).

    Parameters:

      - blocking (bool) – If True (the default), this function will block until the semaphore is acquired.

      - timeout (float) – If given, and blocking is true, specifies the maximum amount of seconds this method will block.

    Returns:

      A `bool` indicating whether the semaphore was acquired. If `blocking` is True and `timeout` is None (the default), then (so long as this semaphore was initialized with a size greater than 0) this will always return True. If a timeout was given, and it expired before the semaphore was acquired, False will be returned. (Note that this can still raise a `Timeout` exception, if some other caller had already started a timer.)

  locked()

    Return a boolean indicating whether the semaphore can be acquired (`False` if the semaphore can be acquired). Most useful with binary semaphores (those with an initial value of 1).

    Return type:

      bool

  rawlink(callback)

    Register a callback to call when this object is ready.

    callback will be called in the `Hub`, so it must not use blocking gevent API. callback will be passed one argument: this instance.

  ready()

    Return a boolean indicating whether the semaphore can be acquired (`True` if the semaphore can be acquired).

    Return type:

      bool

  release()

    Release the semaphore, notifying any waiters if needed. There is no return value.

    Note

    This can be used to over-release the semaphore. (Release more times than it has been acquired or was initially created with.)

    This is usually a sign of a bug, but under some circumstances it can be used deliberately, for example, to model the arrival of additional resources.

    Return type:

      None

  unlink(callback)

    Remove the callback set by `rawlink()`

  wait(timeout=None)

    Wait until it is possible to acquire this semaphore, or until the optional timeout elapses.

    Note

    If this semaphore was initialized with a value of 0, this method will block forever if no timeout is given.

    Parameters:

      timeout (float) – If given, specifies the maximum amount of seconds this method will block.

    Returns:

      A number indicating how many times the semaphore can be acquired before blocking. This could be 0, if other waiters acquired the semaphore.

    Return type:

      int