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.

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

Next page: gevent.hub - The Event Loop and the Hub