Module cursor 

Out-of-band X11 cursor delivery, the X11 counterpart of the Wayland compositor’s cursor callback: one process-wide monitor thread (the X pointer is global, however many captures run) parks in wait_for_event on its own connection for XFixes DisplayCursorNotify and hands each new cursor to the Python callback as (msg_type, png_bytes, hot_x, hot_y) — the same payload the Wayland backend sends, so a consumer needs one handler for both. Keeping the cursor out of the framebuffer means pointer motion over static content never dirties the damage hash or re-encodes video; capture_cursor compositing stays available as the opt-in alternative.

The thread blocks — no polling. Stop and replay requests wake it by sending a ClientMessage to a private InputOnly window from a short-lived connection, which also keeps every request on the monitor’s own connection single-threaded. The SeqCst pairs on stop/wake_win close the startup race where a stop lands before the wake window exists: whichever side loses the ordering still observes the other’s store.

Functions

acquire

An X11 capture started: the first one in spawns the monitor.

release

An X11 capture stopped: the last one out stops and joins the monitor. Runs detached from the GIL — the thread may be blocked attaching to deliver a cursor — and the join is bounded: a thread that misses the wake (X server wedged mid-shutdown) is abandoned with a warning rather than hanging the caller; it exits on its own next event. A stop issued from inside the cursor callback runs on the monitor thread itself, where a join can only time out: it signals and detaches instead, and the loop observes the stop flag once the callback unwinds.

set_callback

Register/replace the callback and re-deliver the current cursor to it.

set_size_cap

shutdown

Interpreter teardown: drop the Python callback (the caller holds the GIL, so the decref is immediate) and signal the thread without joining — PY_SHUTDOWN already gates it off Python, and a normal capture stop reaps it via release.