# gevent

# `gevent.lock` – Locking primitives

class `Semaphore`(value=1) → Semaphore

  Bases: `object`

  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.

  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.

  See also

  `BoundedSemaphore` for a safer version that prevents some classes of bugs.

  `locked`()

    Return a boolean indicating whether the semaphore can be acquired. Most useful with binary semaphores.

  `release`()

    Release the semaphore, notifying any waiters if needed.

  `rawlink`(callback) → None

    Register a callback to call when a counter is more than zero.

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

    This method is normally called automatically by `acquire()` and `wait()`; most code will not need to use it.

  `unlink`(callback) → None

    Remove the callback set by `rawlink()`.

    This method is normally called automatically by `acquire()` and `wait()`; most code will not need to use it.

  `wait`(timeout=None) → int

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

    Caution

    If this semaphore was initialized with a size 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.

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

    Acquire the semaphore.

    Caution

    If this semaphore was initialized with a size 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, specifies the maximum amount of seconds this method will block.

    Returns:

    A boolean 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.)

class `DummySemaphore`(value=None) → DummySemaphore

  Bases: `object`

  A 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.

  `locked`()

    A DummySemaphore is never locked so this always returns False.

  `release`()

    Releasing a dummy semaphore does nothing.

  `wait`(timeout=None)

    Waiting for a DummySemaphore returns immediately.

  `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.

class `BoundedSemaphore`(value=1) → BoundedSemaphore

  Bases: `gevent._semaphore.Semaphore`

  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.

Next page: Implementing servers