aiologic 0.16.0

GIL-powered* locking library for Python

aiologic is a locking library for tasks synchronization and their communication. It provides primitives that are both async-aware and thread-aware, and can be used for interaction between:

• async codes (async <-> async) in one thread as regular async primitives

• async codes (async <-> async) in multiple threads (!)

• async code and sync one (async <-> sync) in one thread (!)

• async code and sync one (async <-> sync) in multiple threads (!)

• sync codes (sync <-> sync) in one thread as regular sync primitives

• sync codes (sync <-> sync) in multiple threads as regular sync primitives

Let’s take a look at the example:

import asyncio

from threading import Thread

import aiologic

lock = aiologic.Lock()


async def func(i: int, j: int) -> None:
    print(f"thread={i} task={j} start")

    async with lock:
        await asyncio.sleep(1)

    print(f"thread={i} task={j} end")


async def main(i: int) -> None:
    await asyncio.gather(func(i, 0), func(i, 1))


Thread(target=asyncio.run, args=[main(0)]).start()
Thread(target=asyncio.run, args=[main(1)]).start()

It prints something like this:

thread=0 task=0 start
thread=1 task=0 start
thread=0 task=1 start
thread=1 task=1 start
thread=0 task=0 end
thread=1 task=0 end
thread=0 task=1 end
thread=1 task=1 end

As you can see, tasks from different event loops are all able to acquire aiologic.Lock. In the same case if you use asyncio.Lock, it will raise a RuntimeError. And threading.Lock will cause a deadlock.

Features

• Python 3.8+ support

• CPython and PyPy support

• Experimental Nuitka support

• Pickling and weakrefing support

• Cancellation and timeouts support

• Optional Trio-style checkpoints:

  • enabled by default for Trio itself

  • disabled by default for all others

• Only one checkpoint per asynchronous call:

  • exactly one context switch if checkpoints are enabled

  • zero or one context switch if checkpoints are disabled

• Fairness wherever possible (with some caveats)

• Thread-safety wherever possible

• Lock-free implementation (with some exceptions)

• Bundled stub files

Synchronization primitives:

• Events: one-time, reusable, and countdown

• Barriers: single-use, cyclic, and reusable

• Semaphores: counting, bounded, and binary

• Capacity limiters: borrowable, and reentrant

• Locks: ownable, and reentrant

• Readers-writer locks (external)

• Condition variables

Communication primitives:

• Queues: FIFO, LIFO, and priority

Non-blocking primitives:

• Flags

• Resource guards

Supported concurrency libraries:

• asyncio, curio, trio, and anyio (coroutine-based)

• eventlet, and gevent (greenlet-based)

• threading (thread-based)

All synchronization, communication, and non-blocking primitives are implemented entirely on effectively atomic operations, which gives an incredible speedup on PyPy compared to alternatives from the threading module. All this works because of GIL, but per-object locks also ensure that the same operations are still atomic, so aiologic also works when running in a free-threaded mode.

Installation

Install from PyPI (stable):

pip install aiologic

Or from GitHub (latest):

pip install git+https://github.com/x42005e1f/aiologic.git

You can also use other package managers, such as uv.

Documentation

Read the Docs: https://aiologic.readthedocs.io (official)

DeepWiki: https://deepwiki.com/x42005e1f/aiologic (AI generated)

Communication channels

GitHub Discussions: https://github.com/x42005e1f/aiologic/discussions (ideas, questions)

GitHub Issues: https://github.com/x42005e1f/aiologic/issues (bug tracker)

You can also send an email to [e-mail] with any feedback.

Dependents

See x42005e1f/aiologic#11.

Support

If you like aiologic and want to support its development, please star its repository on GitHub.

License

The aiologic library is REUSE-compliant and is offered under multiple licenses:

• All original source code is licensed under ISC.

• All original test code is licensed under 0BSD.

• All documentation is licensed under CC-BY-4.0.

• All configuration is licensed under CC0-1.0.

For more accurate information, check the individual files.