usb.core: add raise_on_timeout=False option to Device.read - #11137
Open
lynt-smitka wants to merge 1 commit into
Open
usb.core: add raise_on_timeout=False option to Device.read#11137lynt-smitka wants to merge 1 commit into
lynt-smitka wants to merge 1 commit into
Conversation
Polling an interrupt IN endpoint every frame (a HID gamepad in a game loop) treats "no new report yet" as a normal outcome, but read() can only express it by raising USBTimeoutError. Each raise allocates an exception instance, which adds up to measurable GC pressure on small heaps: a 30 fps game polling one gamepad measured ~1-1.5 KB/s of transient garbage from these exceptions alone (RP2350 Fruit Jam). With raise_on_timeout=False (keyword-only, default True keeps the pyusb-compatible behavior), an elapsed timeout returns 0 instead of raising, so a per-frame poll allocates nothing. A timeout can be detected either by TinyUSB or by CircuitPython's own deadline; with the flag set, both paths return 0 after the usual transfer abort and buffer cleanup, instead of raising.
lynt-smitka
force-pushed
the
usb-read-no-raise
branch
from
July 24, 2026 16:17
edbe19f to
ce508f4
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Polling an interrupt IN endpoint every frame, a USB HID gamepad in a game loop on a USB-host board like the Fruit Jam, treats "no new report yet" as a completely normal outcome. Today
Device.read()can only express that outcome by raisingusb.core.USBTimeoutError, and every raise allocates an exception instance.The cost is measurable: in a 30 fps game polling one gamepad, these exceptions alone produced ~1-1.5 KB/s of transient garbage (RP2350 Fruit Jam) - more than everything else in the game loop combined. That churn eventually surfaces as GC pauses, visible as dropped frames mid-game.
This PR adds a keyword-only
raise_on_timeout: bool = TruetoDevice.read(). The default keeps the pyusb-compatible raising behavior; withraise_on_timeout=Falsean elapsed timeout returns0, so a per-frame poll allocates nothing. Both timeout paths (TinyUSB-reported and the CircuitPython-side deadline) behave the same; transfer abort and buffer cleanup are unchanged, as arewrite()andctrl_transfer().Tested: compiled for
adafruit_fruit_jam; exercised on hardware by a game polling a "USB Game Controller with SNES-like Layout" per frame (0 bytes returned on empty polls, reports parsed normally, unplug still releases all buttons).Possible follow-up: a persistent interrupt transfer - submit once, harvest completions across calls - so per-frame polling doesn't have to submit-and-abort a transfer each time.