hotplug docs: align the header contract and the NetBSD stub with the backends #835

Open

Youw wants to merge 2 commits from hotplug-docs-consistency into connection-callback

Youw commented

2026-09-09 03:56:19 -05:00

(Migrated from github.com)

Documentation-only follow-up to the async HID_API_HOTPLUG_ENUMERATE work (#822, #823, #824, #825, #826). A fresh two-family review of the hotplug feature (Claude Fable 5.1 and gpt-6-astra, reviewing the header against all four backend implementations) found the hidapi.h contract and the NetBSD stub out of step with what the backends actually do. This PR brings the documentation back in line; no backend behavior changes.

`hidapi/hidapi.h`

Global error string. State that the thread-safe hotplug calls are serialized against every call that touches the global error string, that success leaves the string untouched, and that ordinary HIDAPI calls made from the internal event context may not record a diagnostic at all (several backends suppress every global-error write there), so callers on that context must rely on return values.
Initialization and shutdown ordering. List hid_hotplug_register_callback() as an implicit initializer, document the macOS thread-ownership consequence of implicit initialization, require serialized hid_open*() after explicit initialization, and spell out the hid_exit() ordering relative to registered callbacks and in-flight deliveries.
Delivery guarantees. Qualify the "exactly once" and pass-before-live guarantees against monitoring recovery, describe how multiple usage entries of one physical device correlate across events, and state that a stale handle may still be deregistered while its wind-down completes.
Platform notes. Document the Windows and libusb runtime requirements, macOS device-access failures and permission prompts, and the deadlock hazard of synchronous hand-off from a callback back to the registering thread.
Terminology. Use "internal event context" consistently instead of promising a dedicated thread (the Windows backend delivers from threadpool / CM notification threads), and separate the per-device thread-safety statements from the hotplug ones.

`netbsd/hid.c`

The stub returns -1 and zeroes *callback_handle for hid_hotplug_register_callback() as documented, but no longer writes the global error string through the unsynchronized helper, since the hotplug calls are documented thread-safe. The header now says that backends without hotplug support leave the error string untouched.

Review

Findings were merged from both review families and cross-filed: items that concern backend code were fixed on the backend PRs; the ones that concern the contract text landed here. CI (Builds) is green on this branch, and the branch is part of the CI aggregate on #830 together with the five feature branches.

Assisted-by: claude-code:claude-fable-5-1
Assisted-by: codex-cli:gpt-6-astra

Documentation-only follow-up to the async `HID_API_HOTPLUG_ENUMERATE` work (#822, #823, #824, #825, #826). A fresh two-family review of the hotplug feature (Claude Fable 5.1 and gpt-6-astra, reviewing the header against all four backend implementations) found the `hidapi.h` contract and the NetBSD stub out of step with what the backends actually do. This PR brings the documentation back in line; no backend behavior changes. ## `hidapi/hidapi.h` - **Global error string.** State that the thread-safe hotplug calls are serialized against *every* call that touches the global error string, that success leaves the string untouched, and that ordinary HIDAPI calls made from the internal event context may not record a diagnostic at all (several backends suppress every global-error write there), so callers on that context must rely on return values. - **Initialization and shutdown ordering.** List `hid_hotplug_register_callback()` as an implicit initializer, document the macOS thread-ownership consequence of implicit initialization, require serialized `hid_open*()` after explicit initialization, and spell out the `hid_exit()` ordering relative to registered callbacks and in-flight deliveries. - **Delivery guarantees.** Qualify the "exactly once" and pass-before-live guarantees against monitoring recovery, describe how multiple usage entries of one physical device correlate across events, and state that a stale handle may still be deregistered while its wind-down completes. - **Platform notes.** Document the Windows and libusb runtime requirements, macOS device-access failures and permission prompts, and the deadlock hazard of synchronous hand-off from a callback back to the registering thread. - **Terminology.** Use "internal event context" consistently instead of promising a dedicated thread (the Windows backend delivers from threadpool / CM notification threads), and separate the per-device thread-safety statements from the hotplug ones. ## `netbsd/hid.c` The stub returns -1 and zeroes `*callback_handle` for `hid_hotplug_register_callback()` as documented, but no longer writes the global error string through the unsynchronized helper, since the hotplug calls are documented thread-safe. The header now says that backends without hotplug support leave the error string untouched. ## Review Findings were merged from both review families and cross-filed: items that concern backend code were fixed on the backend PRs; the ones that concern the contract text landed here. CI (Builds) is green on this branch, and the branch is part of the CI aggregate on #830 together with the five feature branches. Assisted-by: claude-code:claude-fable-5-1 Assisted-by: codex-cli:gpt-6-astra

This pull request can be merged automatically.

You are not authorized to merge this pull request.

View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.

git fetch -u origin 'hotplug-docs-consistency:hotplug-docs-consistency'

git switch 'hotplug-docs-consistency'

Merge

Merge the changes and update on Forgejo.

Warning: The "Autodetect manual merge" setting is not enabled for this repository, you will have to mark this pull request as manually merged afterwards.

git switch 'connection-callback'

git merge --no-ff 'hotplug-docs-consistency'

git switch 'hotplug-docs-consistency'

git rebase 'connection-callback'

git switch 'connection-callback'

git merge --ff-only 'hotplug-docs-consistency'

git switch 'hotplug-docs-consistency'

git rebase 'connection-callback'

git switch 'connection-callback'

git merge --no-ff 'hotplug-docs-consistency'

git switch 'connection-callback'

git merge --squash 'hotplug-docs-consistency'