Hotplug docs: clarify thread-safety, safe-to-call list, device->next contract#790
Open
Youw wants to merge 1 commit intoconnection-callbackfrom
Open
Hotplug docs: clarify thread-safety, safe-to-call list, device->next contract#790Youw wants to merge 1 commit intoconnection-callbackfrom
Youw wants to merge 1 commit intoconnection-callbackfrom
Conversation
Expand the doc comments on hid_hotplug_callback_fn, hid_hotplug_register_callback, and hid_hotplug_deregister_callback to make the hotplug API's thread-safety contract explicit: - The hotplug API is thread-safe; this is a documented exception to HIDAPI's general "not thread-safe" rule. - The callback runs on an internal HIDAPI thread that is distinct from the application's threads, and holds an internal mutex for the duration of each call. - Enumerate safe-to-call functions from within the callback (hid_hotplug_register/deregister_callback, hid_error(dev)) and explain why others require application-level serialisation, matching the wording style in the Multi-threading Notes wiki. - Spell out the lifetime of the device pointer, the string ownership rules, and the requirement that device->next is always NULL inside the callback. - Document hid_exit() as UB from within the callback (self-join). - Define the return-value semantics consistently for both live events and the synthetic "arrived" events delivered during HID_API_HOTPLUG_ENUMERATE. Supersedes PR #784. Behaviour changes implied by this doc (device->next=NULL, ENUMERATE honoring return value) are tracked as follow-up issues. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This was referenced Apr 24, 2026
mcuee
added
documentation
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.
Expands the hotplug API documentation to spell out the thread-safety contract and adjacent behaviour in line with the Multi-threading Notes wiki. Supersedes #784.
What changes
Doc-only changes to
hidapi/hidapi.h:hid_hotplug_callback_fn— explicit "Execution context", "What the callback may call", "device parameter", and "Return value" sections.hid_hotplug_register_callback— new "Thread safety" section documenting that the hotplug register/deregister pair is thread-safe (the one deliberate exception to HIDAPI's general "not thread-safe" rule) and describing the lifetime of the internal hotplug thread.hid_hotplug_deregister_callback— strengthened to document full thread-safety and the already-deregistered no-op behaviour.Why not #784's wording
#784's patch reads as a blanket "NOT safe to call hid_open/hid_open_path or any other global/non-device functions from within this callback." As @k1-801 pointed out in the review of that PR, this is overly strict: the issue is concurrency between the hotplug callback thread and any other thread that calls init/enumerate/open/close, not the callback itself. The new text follows the wiki's "may be used under conditions Y" style and enumerates the calls that are always safe from inside the callback.
Implied behaviour changes — tracked as follow-up issues
This PR documents the target semantics. Two minor implementation changes are required to bring the code in line with the docs; they are intentionally out of scope here (per maintainer decision — connection-callback is still WIP and a temporary doc/impl gap is acceptable):
device->next == NULLinside the callback — Hotplug: device->next must be NULL inside callback #792HID_API_HOTPLUG_ENUMERATEhonours the callback return value — Hotplug: HID_API_HOTPLUG_ENUMERATE should honour callback return value #793Also captured as follow-ups — existing implementation bugs that predate this doc work:
hid_internal_hotplug_cleanup— Hotplug (macOS): self-join deadlock in hid_internal_hotplug_cleanup #794hid_exitfrom within a hotplug callback should fail fast rather than deadlock — Hotplug: hid_exit() from inside callback should fail fast, not deadlock #795Not changing
Drafted with Claude Code.