asyncio.tasks._enter_task(loop, task)   # sets current_task() → task
asyncio.tasks._leave_task(loop, task)   # sets current_task() → None

Conflict: If task A is entered and __step for task B tries to enter:

RuntimeError: Cannot enter into task <B> while another task <A> is being executed

Anti-pattern A5: entertask held across GIL release

Holding entertask while executing Python bytecode that may release the GIL is the root cause of cross-thread I1 collisions. CPython's GIL switch interval (default 5ms, sys.getswitchinterval()) triggers evalbreaker checks periodically during PyIterSend. When the GIL switches to the asyncio thread, any __step callback in runonce will call entertask and collide with the task still "entered" on the other thread.

Thread A (GIL, running coro.send()):
  _enter_task(loop, task_A)          ← current = task_A
  PyIter_Send → Python bytecode...
    → eval_breaker fires → GIL released

Thread B (asyncio, acquires GIL):
  _run_once → _ready.popleft():
    task_B.__step → _enter_task(loop, task_B)
    → RuntimeError: task_A is being executed!

Dominant collision source: sentinel __step

The collision window from per-step entertask (~1us) is astronomically unlikely to hit. The real A5 problem is the sentinel __step callback from SchedulerTask.init. Each per-request SchedulerTask calls Task.init(sentinel(), loop=loop), which schedules a step callback. Under 50 connections, ~50 sentinel step callbacks pile up in runonce, each calling enter_task — making collisions near-certain.

Fix: eliminate sentinel __step from runonce.

• Python 3.11: Per-request SchedulerTask with ready.pop() immediately after super().init(sentinel()). This physically removes the sentinel __step handle from ready. Handle.cancel() is insufficient under high concurrency — cancelled handles set cancelled=True but remain in the deque; under load they still cause collisions (confirmed: cancel() reduced 60K collisions to 220, pop() reduced to 13). Guard with getattr(loop, "ready", None) for uvloop compatibility. See [src/apx/task.py](src/apx/_task.py).
• Python 3.12+: Per-request SchedulerTask with eagerstart=True. The sentinel completes inline during init (via swapcurrenttask, not enter_task). No __step callback reaches _ready.

With no sentinel __step in runonce, per-step entertask on the tokio thread has near-zero collision targets for the initial drive. For continuations (drain task resumptions), driving on the asyncio thread eliminates the A5 risk entirely — runonce processes callbacks sequentially.

Per-step entertask granularity

Wrap entertask/leavetask around each individual coro.send() + result classification, not the entire drive loop. The bracket must cover all code that can execute Python bytecode (see [PyObject_GetAttr executes Python](#pyobjectgetattr-can-execute-python-bytecode) below), leaving only pure-native budget checks outside.

Per-step pattern (safe):                     Per-drive pattern (unsafe):
for step in budget:                          _enter_task(loop, task)
    _enter_task(loop, task)                  for step in budget:
    result = coro.send(None)  # ~1us             result = coro.send(None)
    classify(result)          # may run Python    classify(result)
    _leave_task(loop, task)                  _leave_task(loop, task)
    # budget check — pure native, safe       # A5 window: entire loop (~5ms)

Cost: 2 Python FFI calls per step (~1us). For a 4-step handler: +4us. For a 1-step handler: +1us. <1% of total request time.

Between steps: asyncio.currenttask() returns None during budget checks. This is safe because only native (non-Python) code runs during these phases — no GIL switch trigger, no Python library code observing currenttask().

Where entertask is safe

Rule: Initial drives on the tokio thread are safe (sentinel removal eliminates collision targets). All continuations (drain task) must drive on the asyncio thread via callsoonthreadsafe(DrainOnLoop) to stay safe.

Cross-thread A5 mitigation: tokio_driving flag

Even with sentinel __step removed, a residual A5 window remains: the tokio thread's per-step entertask during spawnanddrive can collide with the asyncio thread's per-step entertask during driveonloop (inline resume from ResumeCallback) or ReadyQueue::drain, when the GIL switches during coro.send().

Tokio thread:   _enter_task(A) → coro.send() → eval_breaker → GIL released
Asyncio thread: acquires GIL → _run_once → ResumeCallback.__call__
                → drive_on_loop → _enter_task(B) → COLLISION (A still entered)

Mitigation: An AtomicBool flag (tokio_driving) on ReadyQueue guards the window:

1. spawnanddrive sets the flag before drive_task, clears it after.
2. ResumeCallback::call checks the flag. If set, enqueues to ReadyQueue instead of calling driveonloop — the task is driven later when the flag is cleared.
3. ReadyQueue::drain checks the flag. If set, returns 0 — tasks stay queued.
4. After clearing the flag, spawnanddrive pokes unconditionally if the queue has deferred tasks (!readyqueue.isempty()).

Ordering: Release on store, Acquire on load. The GIL acquire/release provides the memory barrier between threads.

TOCTOU residual (~0.1% under heavy load): The flag check and entertask are not atomic. A ResumeCallback may check the flag (false), then the tokio thread sets it and enters drivetask, then the asyncio thread proceeds to enter_task — colliding. Under 100 concurrent connections / 10s load test, this produced 26 out of ~30K requests (0.087%). The per-step bracket (~1µs window) makes this near-negligible.

Implementation: See crates/framework/src/io/bridge/queue.rs (tokiodriving field) and crates/framework/src/io/bridge/mod.rs (spawnand_drive, ResumeCallback::call).

entertask in free-threaded Python (3.13t+)

In free-threaded builds, entertask/leavetask share state->currenttasks with borrowed references — they are not thread-safe (CPython #120974). Python 3.14 fixes this with per-thread circular doubly-linked lists. Until 3.14+, the GIL must be held continuously from entertask through leave_task.

Quick test

uv run python -c "
import asyncio
loop = asyncio.new_event_loop()
asyncio.events._set_running_loop(loop)
async def s(): pass
t1 = asyncio.Task(s(), loop=loop)
t2 = asyncio.Task(s(), loop=loop)
asyncio.tasks._enter_task(loop, t1)
print('current_task:', asyncio.current_task())
try:
    asyncio.tasks._enter_task(loop, t2)
except RuntimeError as e:
    print(f'conflict: {e}')
asyncio.tasks._leave_task(loop, t1)
asyncio.events._set_running_loop(None)
loop.close()
"

Quick test — GIL switch interval

uv run python -c "
import sys
print(f'default switch interval: {sys.getswitchinterval()}s')
sys.setswitchinterval(0.001)  # 1ms — useful for stress-testing A5
print(f'stress interval: {sys.getswitchinterval()}s')
"

contextvars and Drive Cycles

asyncio.Task.step calls Context.run(self.steprunandhandleresult) on every step, entering the task's context. External drivers must do the same: PyContextEnter(ctx) before each drive, PyContextExit(ctx) after.

A task that suspends and resumes must re-enter its context because another task (or the reactor) may have entered a different context in between. Copy the context once at task creation (contextvars.copy_context()), then re-enter it on each drive.

Pitfalls:

• contextvars.copy_context() has measurable overhead even for empty contexts (CPython #136157) — copy once, re-enter many
• CPython 3.13/3.14 has a bug where context variables can leak across tasks during I/O pauses (CPython #140947) — explicit enter/exit per drive protects against this
• In free-threaded builds, ContextVar itself is not fully thread-safe (CPython #121546)

setrunning_loop — Thread-Local State

asyncio.events.setrunningloop(loop) sets a thread-local variable. asyncio.getrunning_loop() reads it.

Source: Lib/asyncio/events.py:setrunning_loop

• loop.runforever() calls setrunningloop(self) at start, setrunning_loop(None) at end
• Each OS thread has its own running loop
• seteventloop() is process-global (different from setrunning_loop)

Multi-thread implication: If a driver thread calls setrunningloop(loop) at init, code executing during drive cycles on that thread sees the loop. The asyncio thread also sees it (via runforever()). But a third thread (e.g., a thread pool executor callback) calling getrunningloop() gets RuntimeError: no running event loop. Libraries that call getrunningloop() from thread pool callbacks will break.

Quick test

uv run python -c "
import asyncio, threading
loop = asyncio.new_event_loop()
asyncio.events._set_running_loop(loop)
print('main thread:', asyncio.get_running_loop())
def check():
    try: asyncio.get_running_loop()
    except RuntimeError as e: print(f'other thread: {e}')
t = threading.Thread(target=check)
t.start(); t.join()
asyncio.events._set_running_loop(None)
loop.close()
"

PyObject_GetAttr Can Execute Python Bytecode

Attribute access via PyObject_GetAttr (used by getattr(), . notation, and PyO3's getattr) can trigger getattribute or getattr descriptors on custom types. This means C/Rust code classifying yielded values by probing attributes is executing Python bytecode and is subject to GIL switch.

Concrete cases in coroutine drivers:

• Probing asynciofuture_blocking to detect asyncio.Future — safe on builtin Future (C slot), but custom Future subclasses may have Python-level descriptors
• Probing await to detect custom awaitables — always a Python attribute lookup
• Calling .call_method0("await") — full Python method dispatch

Rule: Any code path that calls PyObjectGetAttr on user-controlled types must be inside the entertask bracket. Leaving it outside creates an A5 window identical to PyIterSend.

Done Callback Thread Identity

Where a done callback fires determines what scheduling APIs are safe to call from it:

Key insight: asyncio.Future done callbacks fire during runonce step 3 (processing ready). Code in these callbacks is on the asyncio thread. callsoon (not threadsafe) is correct and ~200ns cheaper than callsoonthreadsafe (avoids self-pipe write).

This distinction matters when resuming suspended coroutines from done callbacks. If the callback is known to fire on the asyncio thread (e.g., from asyncio.Future), the coroutine can be driven inline — serialized with runonce, no cross-thread scheduling needed. If the callback may fire on another thread, cross-thread mechanisms (callsoonthreadsafe, ReadyQueue) are required.

Inline driving from done callbacks

When a done callback fires on the asyncio thread, driving the coroutine directly avoids the cost of enqueuing → waking a drain task → GIL acquisition:

Standard path (cross-thread):                Inline path (on asyncio thread):
done_callback fires                           done_callback fires (during _run_once)
  → push to ReadyQueue                          → extract future result
  → Notify drain task                            → drive_task() directly
  → drain acquires GIL                           → (budget exhausted? call_soon to yield)
  → resume_task()

When driving inline and the step budget is exhausted, use callsoon(resumecallback) to yield back to the event loop. This keeps the task on the asyncio thread but lets runonce process I/O events and other callbacks between drive batches. Do NOT use callsoonthreadsafe here — it would write to the self-pipe unnecessarily since you're already on the loop thread.

GIL Relay Bottleneck

When multiple threads each need the GIL sequentially for a single request, GIL contention serializes them into a latency queue:

Request lifecycle requiring 3 GIL hops:
  Thread 1 (tokio): GIL → drive coro → release
  Thread 2 (asyncio): GIL → process _run_once → fire callback → release
  Thread 3 (drain): GIL → resume_task → drive continuation → release

Under N concurrent connections:
  Each hop waits for up to N-1 other threads' GIL holds
  Latency ≈ N × hops × avg_hold_time

With 50 concurrent connections and 3 hops per request, respwaitp50 can reach ~17ms even for trivial handlers — 96% of total latency is GIL relay, not actual computation.

Fix: Minimize cross-thread GIL hops. Drive continuations on the same thread that receives the done callback (inline driving). This reduces 3 hops to 2 for asyncio Future resumptions, eliminating the drain task from the critical path.

Native Runtime Context on the asyncio Thread

When a drain callback (e.g., DrainOnLoop) runs on the asyncio thread via callsoonthreadsafe, it executes inside runonce step 3 — on the asyncio thread, not on a native async runtime (Tokio, etc.) worker thread. Any code driven from that callback that needs to interact with the native runtime (spawn tasks, send on channels, resolve backpressure) requires the runtime context to be explicitly available.

The enter() guard pitfall

The natural approach is to call runtimehandle.enter() at the top of the callback, which sets the runtime's own thread-local. Downstream code then calls Runtime::trycurrent() to find it:

DrainOnLoop.__call__:
    let _guard = handle.enter();      // sets tokio's thread-local
    drive_task(...)
      → Python coro.send()
        → ASGI send() → try_send() → Full → backpressure
          → with_runtime_handle(|h| h.spawn(...))
            → check custom thread-local: None
            → check Runtime::try_current(): ???

The problem: if the consumer uses a two-tier lookup (custom thread-local first, then trycurrent() as fallback), the enter() guard only populates the runtime's own thread-local — it does not populate the custom one. If the trycurrent() fallback fails for any reason (e.g., called inside a thread_local!().with() closure that interferes with the runtime's own thread-local access, or the guard was dropped prematurely), the lookup returns None.

The reliable fix: explicit thread-local setting

Instead of relying on enter() + try_current(), explicitly set the custom thread-local at the start of every callback invocation:

DrainOnLoop.__call__:
    set_runtime_handle(self.handle.clone());  // sets custom thread-local directly
    drive_task(...)
      → with_runtime_handle(|h| h.spawn(...))
        → check custom thread-local: Some(handle) ✓

This is idempotent, costs one thread-local write (~10ns), and eliminates all ambiguity about which thread-local is populated.

When this matters

Symptom when missing: RuntimeError: no runtime for backpressure send or RuntimeError: no tokio runtime found — the driven Python code hits a path that needs the native runtime, but the asyncio thread has no runtime context.

Streaming Backpressure and GIL Deadlock

ASGI streaming responses produce body chunks through a bounded channel. When the producer (Python coroutine under GIL) fills the channel faster than the HTTP layer drains it, backpressure engages. The interaction between backpressure resolution and the GIL creates a specific deadlock pattern.

The deadlock pattern

Thread A (asyncio, GIL held via DrainOnLoop):
  1. Drive Python coroutine: coro.send(None)
  2. Coroutine calls ASGI send({type: "http.response.body", more_body: True})
  3. Rust handler: try_send(chunk) → channel full → BACKPRESSURE
  4. Need to spawn native async task to await channel space
  5. Task spawned → task needs to resolve a Python Future when space available
  6. Resolving the Future requires GIL → Python::attach() blocks
  7. DEADLOCK: step 1 holds GIL, step 6 waits for GIL

Thread B (tokio, HTTP layer):
  - Draining the channel by sending bytes to the client
  - Making space, but the spawned task can't signal completion (GIL blocked)

Why it manifests under load

At low concurrency or with small payloads, the HTTP layer drains the channel between drive cycles, so try_send() rarely fails. Under load:

• Drive budget amplification: A single drive cycle may produce 128+ chunks without yielding. With a channel capacity of 8, backpressure is guaranteed after 8 chunks.
• CPU starvation: On constrained CPU (e.g., 0.5 cores), the HTTP layer can't drain fast enough between chunks produced within a single drive's GIL hold.
• Cascading: Once one request deadlocks, the GIL is stuck. All other requests waiting for the GIL also stall, creating a total server freeze.

Channel sizing as a mitigation

Size the channel so that a single drive cycle cannot fill it:

channel_capacity > drive_budget

If the drive budget is 128 steps, a channel capacity of 256 means a single drive cycle can produce up to 128 chunks without hitting backpressure. The HTTP layer then drains the buffer between drive cycles (when the GIL is released).

Trade-off: Larger channels use more memory per stream. For 1000 concurrent streams with 1KB chunks and capacity 256, that's ~250MB of buffered data. Size according to expected concurrency and chunk size.

The fundamental tension

The deadlock arises from a circular dependency:

1. Producer (Python, GIL-holding) wants to write to the channel
2. Channel is full, resolution requires native async task
3. Native task needs GIL to signal Python Future completion
4. GIL is held by the producer → cycle

Breaking any link in this chain fixes the deadlock:

• Larger channel → step 2 doesn't occur within a single GIL hold (mitigation, not elimination)
• GIL-free signaling → step 3 doesn't need the GIL (requires custom Future with synchronous dispatch; see [Synchronous vs deferred callback dispatch](#synchronous-vs-deferred-callback-dispatch))
• Yield on backpressure → step 1 releases GIL before retrying (adds latency, requires coroutine cooperation)
• Flow control at the ASGI layer → limit how many chunks the coroutine can produce per drive cycle (application-level, not always possible)

Diagnostic pattern

TRACE asgi::scope: stream chunk BACKPRESSURE (channel full) body_len=N more_body=true
TRACE io::driver: drive: error steps=0 error=RuntimeError: no runtime for backpressure send

The steps=0 indicates the very first step of a continuation drive hit backpressure — the channel was still full from the previous drive. Combined with "no runtime" (missing native runtime context on the asyncio thread, see section above), this produces an immediate drive error.

If the runtime context IS available but the spawned task still deadlocks (no error, just a hang), the symptom is a stream that stops mid-way through. The HTTP client receives partial data, then the connection times out. Server-side, the drive trace shows the last successful chunk followed by silence.

asyncio.Future.done() Fast Path

When handling a yielded asyncio.Future, check fut.done() before attaching a done callback. If the future is already resolved, extract the result and continue driving — no suspension, no callback overhead, no GIL relay.

# Pseudo-code for the optimization:
if fut.done():
    result = fut.result()       # immediate
    task.set_send_value(result)
    continue                    # re-enter drive loop
else:
    fut.add_done_callback(resume_cb)  # standard suspend path

This is especially relevant on Python 3.12+ with eager task factory, where futures from eagerly-started tasks may already be resolved by the time the parent coroutine inspects them.

Avoid recursion. If the re-drive after an already-done future yields another already-done future, naive recursive calls grow the stack. Use a loop instead: handledriveresult returns a "continue driving" signal, and the caller loops back into drive_task.

Cancellation Semantics

Edge-triggered, not level-triggered

task.cancel() delivers CancelledError once at the next await point. If the coroutine catches it and awaits again, cancellation is forgotten:

async def sticky():
    try:
        await asyncio.sleep(10)
    except asyncio.CancelledError:
        print("caught cancel")
        await asyncio.sleep(1)     # succeeds! cancellation is gone
        print("continued normally")

This differs from Trio's level-triggered model. Task.uncancel() (3.11+) and Task.cancelling() manage nesting depth but add their own edge cases.

Known cancellation bugs

• asyncio.wait_for() can raise CancelledError instead of TimeoutError in race conditions (CPython #114496)
• asyncio.timeout(0) catches and processes a prior unrelated cancellation of the enclosing task (CPython #134471)
• Task.uncancel() interacts poorly with TaskGroup: the internal cancellation counter can become corrupted (CPython #95289)
• TaskGroup._abort() runs once — tasks created after abort are never cancelled (CPython #94398)
• Bare except: silently swallows CancelledError since Python 3.8 changed it from Exception to BaseException (CPython #76709)

Tasks Are Weakly Referenced

asyncio.alltasks is a WeakSet. Tasks without external strong references can be garbage-collected while pending:

async def fire_and_forget():
    await asyncio.sleep(10)

asyncio.create_task(fire_and_forget())  # no strong ref saved!
# GC may collect → "Task was destroyed but it is pending!" warning

Implication for drivers: Between suspension and resumption, the only strong reference to a driven task may be inside the done callback object. If the future holding the callback is GC'd without resolution, the task silently disappears. Ensure at least one strong reference exists for the entire driven lifecycle (e.g., inside the callback struct or a dedicated pending-tasks collection).

Quick test

uv run python -c "
import asyncio, gc
loop = asyncio.new_event_loop()
async def never_finishes(): await asyncio.sleep(999)
t = asyncio.Task(never_finishes(), loop=loop)
print(f'all_tasks: {len(asyncio.all_tasks(loop))}')   # 1
del t
gc.collect()
print(f'all_tasks after del: {len(asyncio.all_tasks(loop))}')  # 0 — collected!
loop.close()
"

Signal Handling Requires Main Thread

loop.addsignalhandler() only works on the main thread. When the asyncio loop runs on a non-main thread (common in Rust-embedded architectures):

asyncio thread: loop.add_signal_handler(SIGINT, handler)
  → RuntimeError: "set_wakeup_fd only works in main thread"

Python's signal module requires handlers to run on the main thread. Ctrl-C sets a CPython flag checked only when control returns to the Python interpreter — not during Rust execution (PyO3 #3795). uvloop also has hangs after KeyboardInterrupt (uvloop #335).

Workaround: Handle signals in the native runtime (e.g., tokio::signal::ctrlc()) and broadcast shutdown to the asyncio loop via callsoonthreadsafe. Libraries like Uvicorn that call addsignal_handler will fail on non-main-thread loops.

uvloop Differences

uvloop is a C/Cython event loop using libuv. Key incompatibilities with CPython asyncio internals:

Source: uvloop architecture docs

Quick test — verify _ready absence

uv run python -c "
import uvloop
loop = uvloop.new_event_loop()
print('has _ready:', hasattr(loop, '_ready'))   # False
loop.close()
"

Implication for Task.init

Removing the auto-scheduled __step via loop.ready does not work on uvloop — ready does not exist. The handle is in libuv's C callback queue. Use getattr(loop, '_ready', None) to detect this.

Use pop(), not cancel(): Handle.cancel() only sets cancelled=True; the handle remains in the deque and still causes A5 collisions under high concurrency (cancelled handles pile up in runonce, each consuming a popleft() + cancelled check cycle, and under extreme load the timing still allows collisions). deque.pop() physically removes the handle.

ready = getattr(loop, "_ready", None)
n_before = len(ready) if ready is not None else 0
super().__init__(sentinel, loop=loop)
if not _PY312 and ready is not None and len(ready) > n_before:
    ready.pop()  # physically remove — cancel() is insufficient
# On uvloop: _ready is None, so __step stays in libuv's C queue.
# Use an immediately-completing sentinel so __step enters/completes/
# leaves atomically (~1us, no collision window).

sniffio — Async Library Detection

anyio uses sniffio to detect which async library is running.

Detection order (from sniffio/impl.py:currentasynclibrary):

1. sniffio.thread_local.name          (thread-local override)
2. sniffio.current_async_library_cvar  (contextvar override)
3. asyncio.current_task() is not None  → "asyncio"
4. raise AsyncLibraryNotFoundError

uv run python -c "
import asyncio, sniffio
loop = asyncio.new_event_loop()
asyncio.events._set_running_loop(loop)
# Without current_task:
try: print(sniffio.current_async_library())
except Exception as e: print(f'no task: {e}')
# With current_task:
async def s(): pass
t = asyncio.Task(s(), loop=loop)
asyncio.tasks._enter_task(loop, t)
print(f'with task: {sniffio.current_async_library()}')  # asyncio
asyncio.tasks._leave_task(loop, t)
asyncio.events._set_running_loop(None)
loop.close()
"

anyio.create_task_group()
  → get_async_backend()
    → sniffio.current_async_library()   # must detect "asyncio"
    → import anyio._backends._asyncio
  → TaskGroup()

while self._tasks:
    self._on_completed_fut = loop.create_future()
    await self._on_completed_fut          # yields asyncio.Future

self._tasks.remove(task)
if self._on_completed_fut is not None and not self._tasks:
    self._on_completed_fut.set_result(None)

def __enter__(self):
    self._host_task = current_task()           # must be non-None
    self._tasks.add(host_task)
    _task_states[host_task] = TaskState(...)   # WeakKeyDictionary

def __exit__(self, ...):
    if current_task() is not self._host_task:  # MUST match
        raise RuntimeError("Attempted to exit cancel scope in a different task")

Tokio thread (GIL):
  1. Drive coroutine via coro.send(None)
  2. Coroutine calls loop.create_task() → call_soon → _ready grows
  3. Coroutine suspends on a non-asyncio awaitable (e.g. Rust Future)
  4. Driver returns, releases GIL

Asyncio thread:
  _run_once → select(timeout=None) → BLOCKED forever
  (_ready has items, but select doesn't know)

CPython:  loop._ready is accessible  → measure len() delta → poke only if delta > 0
uvloop:   loop._ready does not exist → coalesced poke via dedicated tokio task + Notify
Both:     skip poke entirely when DriveResult is Completed or Error

# n_before MUST be captured AFTER create_scheduler_task, so the
# sentinel __step (3.11, popped) or eager completion (3.12+) is
# already reflected. Only user-code additions matter.
n_before = len(loop._ready)          # snapshot after scheduler task creation
# ... drive cycle ...
n_after = len(loop._ready)
if n_after > n_before:               # handler created asyncio tasks
    loop.call_soon_threadsafe(noop)