aiologic

aiologic is a Python locking library for task synchronization and communication whose primitives are both async-aware and thread-aware at the same time. Where asyncio.Lock raises errors when shared across event loops and threading.Lock deadlocks async code, aiologic’s Lock, Semaphore, Event, Condition, Barrier, and queue primitives work correctly across all of these boundaries.

It supports interaction between async and sync code, within a single thread or across many threads, and integrates with asyncio, Trio, AnyIO, gevent, and eventlet. This makes it a bridge for mixed concurrency models where you need one synchronization primitive to coordinate greenlets, threads, and coroutines running on different event loops.

What You Get

• Locks, semaphores, events, conditions, barriers, and capacity limiters that work across threads and event loops
• Async-aware and thread-aware queues for cross-context communication
• Support for asyncio, Trio, AnyIO, gevent, and eventlet concurrency backends
• CPython and PyPy support (Python 3.8+) with experimental Nuitka support
• Pickling support and full type hints (py.typed) with .pyi stubs

Common Use Cases

• Sharing a single lock between async tasks running in multiple threads/event loops
• Coordinating between synchronous and asynchronous code without deadlocks
• Bridging gevent/eventlet greenlets and asyncio/Trio coroutines with common primitives

Under The Hood

Architecture - The source is organized by primitive under src/aiologic (_locks, _semaphores, _events, _conditions, _barriers, _limiters, _flags, _queues, _guards), each with a matching .pyi stub. A lowlevel package provides the checkpoint and event abstractions that let primitives suspend correctly on whichever backend (asyncio, Trio, gevent, etc.) is running, and a _monkey package handles optional patching. Primitives are built to be thread-safe and event-loop-agnostic simultaneously rather than assuming a single loop.

Tech Stack - Pure Python (3.8+), packaged with pyproject.toml and uv.lock, targeting both CPython and PyPy with experimental Nuitka support. It interoperates with asyncio, Trio, AnyIO, gevent, and eventlet without hard-depending on them.

Code Quality - The project ships an extensive tests directory, complete type stubs and py.typed, a maintained CHANGELOG, and REUSE-compliant per-file license headers. Frequent commits (600+) and 20 releases indicate active, disciplined maintenance despite a small contributor base.

API Design - The public API deliberately mirrors the standard library’s threading and asyncio primitives (Lock, Semaphore, Event, Condition, Barrier), so the primitives are familiar to use; the innovation is that the same object works across contexts. The learning curve comes from understanding the concurrency semantics, not the surface API, which is well documented on Read the Docs.