cyndilib.locks#

Thread synchronization primitives implemented at the C level

This module is heavily inspired by the FastRLock library with a few adjustments and additions.

Lock#

class cyndilib.locks.Lock#

Bases: object

Implementation of threading.Lock. A Primitive non-reentrant lock (or mutex)

This class supports use as a context manager and can be acquired and released using the with statement.

acquire(self, bool block=True, double timeout=-1) → bool#

Acquire the lock, blocking or non-blocking

Parameters:

  • block (bool, optional) – If True (the default), block until the lock is unlocked. If False, acquire the lock if it it isn’t already locked and return immediately.

  • timeout (float, optional) – Maximum time (in seconds) to block waiting to acquire the lock. A value of -1 specifies an unbounded wait.

Note

The arguments in this method vary slightly from that of threading.Lock.acquire() where it is considered an error to specify a timeout with blocking set to False.

In this implementation, the block argument is ignored if timeout is given.

Returns:

True if the lock was acquired, otherwise False.

Return type:

bool

locked#

True if the lock is acquired

name#

unicode

Type:

name

release(self) → bool#

Release the lock

Raises:

RuntimeError – If the lock is not locked

RLock#

class cyndilib.locks.RLock#

Bases: Lock

Implementation of threading.RLock. A reentrant lock that can be acquired multiple times by the same thread

Each call to acquire() must be followed by corresponding a call to release() before the lock is unlocked.

This class supports use as a context manager and can be acquired and released using the with statement.

Condition#

class cyndilib.locks.Condition#

Bases: object

Implementation of threading.Condition. Allows one or more thread to wait until they are notified by another thread.

Parameters:

init_lock (RLock, optional) – If provided, a RLock instance to be used as the underlying lock. If not provided or None a new RLock will be created.

This class supports use as a context manager and can be acquired and released using the with statement.

acquire(self, bool block=True, double timeout=-1) → bool#

Acquire the underlying lock

Arguments and return values match those of Lock.acquire()

notify(self, Py_ssize_t n=1)#

Wake up at least n threads waiting for this condition variable

The lock must be acquired before this method is called. Since waiting threads must reacquire the lock before returning from the wait() method, the caller must release it.

Parameters:

n (int) – Maximum number of threads to notify. Defaults to 1

Raises:

RuntimeError – If the lock was not acquired before this method was called

notify_all(self)#

Like notify(), but wakes all waiting threads

Raises:

RuntimeError – If the lock was not acquired before this method was called

release(self) → bool#

Release the underlying lock

Arguments and return values match those of Lock.release()

wait(self, timeout=None) → bool#

Wait until notified or until a timeout occurs

The underlying lock must be held before a call to this method. Once called, releases lock then blocks until awakened by a call to notify() or notify_all() by another thread, or until the timeout (if given) has been reached.

Parameters:

timeout (float, optional) – If provided, the maximum amount of time (in seconds) to block. If -1 is given (or None), the blocking duration is unbounded.

Returns:

True if notified before the timeout (if any), False

if a timeout was given and was reached.

Return type:

bool

Raises:

RuntimeError – If the lock was not acquired before this method was called

wait_for(self, predicate, timeout=None) → bool#

Wait until a condition evaluates to True

Repeatedly calls wait() until the given predicate is satisfied or the timeout has been reached.

Parameters:

  • predicate (Callable) – A callable whose return value will be evaluated as a boolean value. Any returned value that can be evaluated as True (bool(predicate())) will satisfy the condition.

  • timeout (float, optional) – If provided, the maximum amount of time (in seconds) to wait for the condition to be satisfied. If -1 is given (or None), waits indefinitely.

Returns:

True if the condition was satisfied before the timeout (if given), False otherwise.

Return type:

bool

Raises:

RuntimeError – If the lock was not acquired before this method was called

Event#

class cyndilib.locks.Event#

Bases: object

Implementation of threading.Event. A simple flag-based thread communication primitive where one thread signals an event and other threads wait for it.

clear(self)#

Reset the internal flag to False. After this, any threads making a call to wait() will block until the event is set() again

is_set(self) → bool#

Returns True if the event has been set

set(self)#

Set the internal flag to True, awakening any threads waiting for it

wait(self, timeout=None) → bool#

Block until the internal flag is True by a call to set() by another thread. If the flag is already True, return immediately.

Parameters:

timeout (float, optional) – If given, the maximum time in seconds to block waiting for the flag. If -1 (or None), blocks indefinitely.

Returns:

True if the flag was set before a timeout, False otherwise

Return type:

bool