hbutils.concurrent.readwrite

Read-write lock utilities for coordinating concurrent access to shared resources.

This module provides a ReadWriteLock implementation that allows multiple concurrent readers or a single exclusive writer. It is useful for scenarios where read operations are frequent and write operations are occasional, improving overall throughput by permitting concurrent reads while preserving consistency for writes.

The module contains the following main component:

• ReadWriteLock - Reader-writer lock with convenience context managers

Example:

>>> from hbutils.concurrent.readwrite import ReadWriteLock
>>> lock = ReadWriteLock()
>>> # Concurrent readers
>>> with lock.read_lock():
...     # read shared state
...     pass
>>> # Exclusive writer
>>> with lock.write_lock():
...     # modify shared state
...     pass

Note

The lock factory must return a lock object supporting acquire and release and acting as a context manager (e.g., threading.Lock()).

__all__

hbutils.concurrent.readwrite.__all__ = ['ReadWriteLock']

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

ReadWriteLock

class hbutils.concurrent.readwrite.ReadWriteLock(lock_factory: ~typing.Callable[[], ~_thread.allocate_lock] = <built-in function allocate_lock>)

A read-write lock implementation for controlling concurrent access to shared resources.

This class implements a reader-writer lock that allows multiple concurrent readers or a single exclusive writer. The lock follows these exclusion rules:

• Read-Read: Non-exclusive, multiple readers can access concurrently

• Read-Write: Exclusive, write operations must wait for all read operations to complete

• Write-Write: Exclusive, write operations execute serially

• Write-Read: Exclusive, read operations must wait for write operations to complete

The lock is designed to optimize scenarios with frequent read operations and occasional write operations, providing better performance through concurrent reads while maintaining data consistency during writes.

Parameters:

lock_factory (Callable[[], threading.Lock]) – Factory function to create lock objects, defaults to threading.Lock()

Example:

>>> lock = ReadWriteLock()
>>> lock.acquire_read()
>>> try:
...     # perform read operations
...     pass
... finally:
...     lock.release_read()

__init__(lock_factory: ~typing.Callable[[], ~_thread.allocate_lock] = <built-in function allocate_lock>) → None

Initialize the ReadWriteLock.

Parameters:

lock_factory (Callable[[], threading.Lock]) – Factory function to create lock objects, defaults to threading.Lock()

acquire_read() → None

Acquire a read lock.

This method allows multiple threads to acquire read locks concurrently. The first reader will block any potential writers by acquiring the write lock. Subsequent readers can proceed without blocking as long as no writer is waiting.

Returns:

None

Return type:

None

acquire_write() → None

Acquire a write lock.

This method provides exclusive access for write operations. It will block until all current readers have finished and no other writers are active. Once acquired, no new readers or writers can proceed until the write lock is released.

Returns:

None

Return type:

None

read_lock() → Generator[None, None, None]

Context manager for read lock operations.

This method provides a convenient way to acquire and automatically release a read lock using the with statement. The lock is guaranteed to be released even if an exception occurs within the context.

Returns:

Generator for context management

Return type:

Generator[None, None, None]

Example:

>>> rwlock = ReadWriteLock()
>>> with rwlock.read_lock():
...     # Perform read operations
...     pass

release_read() → None

Release a read lock.

This method decrements the reader count and releases the write lock when the last reader finishes, allowing pending write operations to proceed.

Returns:

None

Return type:

None

Raises:

RuntimeError – If there are no active readers to release

release_write() → None

Release a write lock.

This method releases the exclusive write lock, allowing pending readers and writers to proceed according to the lock’s scheduling policy.

Returns:

None

Return type:

None

write_lock() → Generator[None, None, None]

Context manager for write lock operations.

This method provides a convenient way to acquire and automatically release a write lock using the with statement. The lock is guaranteed to be released even if an exception occurs within the context.

Returns:

Generator for context management

Return type:

Generator[None, None, None]

Example:

>>> rwlock = ReadWriteLock()
>>> with rwlock.write_lock():
...     # Perform write operations
...     pass