linux: deliver hotplug ENUMERATE pass asynchronously on the event context

[Youw]

Implements the hotplug contract documented in hidapi/hidapi.h (#790) for the linux/hidraw backend.

What changed

Asynchronous ENUMERATE pass. hid_hotplug_register_callback() no longer runs the HID_API_HOTPLUG_ENUMERATE initial pass synchronously on the calling thread. Instead it takes a deep-copied, registration-time snapshot of the matching entries of the internal device cache (only when HID_API_HOTPLUG_EVENT_DEVICE_ARRIVED is requested), stores it on the callback record (replay), and the udev monitor thread delivers it as synthetic "arrived" events:

• never on an application thread and never from within the register call itself;
• before any live events for that callback — hid_internal_invoke_callbacks() flushes a callback's pending snapshot before handing it a live event, and the monitor thread also flushes pending snapshots at the top of its loop (the existing 5 ms poll timeout caps the latency, no extra wakeup fd needed);
• exactly once per device connection: the snapshot is taken under the hotplug mutex, so a device arrival is reported either by the pass or as a live event, never both;
• a non-zero callback return stops the remainder of the pass and deregisters the callback (undelivered snapshot entries are freed), same as for live events.

This also covers registrations made while the monitor thread is already running, including registrations made from within another hotplug callback.

device->next is now NULL for every invocation. The udev arrival path used to pass the chained multi-usage list to callbacks (the old TODO); each entry is now delivered on its own, keeping the internal cache intact for later "left" matching.

Error strings and out-parameter. Every failure path of register/deregister (NULL callback, empty/unknown events bits, unknown flags bits, allocation/udev/thread-start failures, unknown or stale deregister handle) now sets the global error string retrievable via hid_error(NULL), and register sets *callback_handle to 0 on failure before any error return.

Monitor-thread lifecycle fixes. Previously, when the last callback removed itself on the monitor thread (non-zero return or in-callback deregister), the thread exited on its own, was never joined, and freed the shared device list / udev monitor unlocked — racing a subsequent first registration that re-creates them. Now the exiting thread releases nothing; joining and monitoring-context teardown are centralized in hid_internal_hotplug_cleanup() and a new first registration reaps the previous thread before re-creating the context.

Design decisions / deviations

• hid_enumerate(0, 0) inside the first registration may set the "No HID devices found" global error on an empty system; register clears it, since an empty system is not a registration failure. A genuine enumeration failure does fail the registration.
• The initial pass is all-or-nothing: if the snapshot cannot be copied in full, the registration is unwound and fails, rather than delivering a partial device list (each connection must be reported exactly once — never "neither").

Verification

• gcc -fsyntax-only -Wall -Wextra -pedantic -Werror -Wformat-signedness and g++ -fsyntax-only -Wall -Wextra -Werror clean; full CMake builds (C and HIDAPI_BUILD_AS_CXX=ON with -Werror) pass.
• The WSL2 kernel used for testing has no uhid/hidraw support (CONFIG_UHID not set), so the tests: virtual HID device test harness for all four backends (hidraw, libusb, winapi, darwin) #815 virtual-device harness could not drive real udev events. Instead a throwaway whitebox harness (including linux/hid.c directly, injecting fake entries into the hotplug device cache and driving the internal arrival/removal handlers) exercised 119 checks: async delivery on the monitor thread (never the registering thread), VID/PID filtering of the snapshot, next == NULL on every invocation, exactly-once vs. later-connected devices and vs. a pre-queued add, non-zero return stopping the pass, self-deregistration and nested registration from within a callback, registration from within an in-flight dispatch (both event types, multi-usage devices), tombstoned/stale-handle deregister, handle exhaustion, last-callback self-removal followed by re-registration (thread reaping), hid_exit() with an undelivered snapshot, re-initialization after hid_exit(), concurrent first registrations, concurrent stale deregistrations, and all argument-validation error strings.
• 10/10 runs clean under ASan+UBSan+LSan (no leaks) and 10/10 clean under TSan.
• Live udev arrival/removal delivery was not exercised against real hardware and still deserves a check on a real machine.

Addresses #792 and #793 for the linux/hidraw backend.

Review round 1

All findings from the first review round are addressed in linux: address the hotplug review findings:

• Global error-string race. Register/deregister wrote last_global_error_str with no lock (on the validation paths, before the hotplug mutex exists, and on the post-unlock paths), and the monitor thread wrote it too (via create_device_info_for_device()); two concurrent, documented-thread-safe calls could double-free it. Every mutation now goes through a file-static mutex in the lowest-level writer (register_error_str()), which all the register_global_error*() / register_device_error*() helpers funnel into. Reading via hid_error() remains subject to the documented thread-safety rules.
• First-initialization race. Two concurrent first registrations could both observe mutex_ready == 0 and both pthread_mutex_init() the hotplug mutex (undefined behaviour) while resetting the context fields under each other. A static bootstrap mutex now guards the machinery init/teardown block.
• hid_init() race (found while making TSan clean). A registration implicitly initializes the library twice — directly, and again inside the initial enumeration — and setlocale() is not thread-safe against itself, so two concurrent registrations raced in hid_init(). hid_init() now serializes itself.
• Liveness / publication. The monitor loop no longer reads any decision state unlocked: it trylocks every iteration and checks the callback list (and the pending initial passes) only under the acquired mutex, so a stale read cannot keep it alive or make it exit early. The thread announces its exit under the mutex, and hid_internal_hotplug_cleanup() unlocks before pthread_join() — nothing is ever joined while holding the mutex. This removed the previously "excused" races, and TSan is now fully clean.
• Duplicate arrival. A device showing up between udev_monitor_enable_receiving() and the initial hid_enumerate() was in both the snapshot and the queued netlink event, producing a duplicate "arrived", a duplicate cache entry and later a duplicate "left". Arrivals whose path is already cached are now skipped.
• Dispatch bounding and cache order. The device cache is updated before an event is dispatched, and every dispatch (both event types) is bounded to the callbacks registered when the event started. A callback registered from within a callback therefore observes the device exactly once, through its own snapshot, instead of also receiving the in-flight event — and, for a multi-usage device, all of its usage entries are added to (or removed from) the cache before any of them is dispatched, so such a callback can neither miss a device nor see a "left" with no matching "arrived".
• All-or-nothing snapshot. A failed snapshot copy now frees the partial snapshot, unwinds the registration completely (leaving *callback_handle at 0), sets the error string and returns -1. A partial hid_internal_copy_device_info() result is likewise rejected instead of reaching a callback. A genuine hid_enumerate() failure now fails the registration, and is distinguished from an empty system.
• libudev setup and fd 0. Every libudev call in the registration path is checked and fails the registration with an error string. 0 is a valid file descriptor: -1 is now the sentinel, and the checks test for < 0.
• Handle exhaustion. next_handle++ at INT_MAX was signed-overflow undefined behaviour, and wrapping back to 1 could collide with a live handle. Registration now fails with an error instead of wrapping.
• Tombstoned handle. Deregistering a handle that was already deregistered from within a callback (and is only awaiting its postponed removal) now reports "not found" (-1) instead of 0.
• Early return in deregister. Deregistration now reaps a previously self-exited monitor thread before returning early on an empty callback list, instead of leaving the monitoring context behind until the next registration or hid_exit().
• Robustness. The udev action and devnode are checked for NULL, and poll() replaces select() for the monitor file descriptor (no FD_SETSIZE undefined behaviour).

Assisted-by: claude-code:claude-fable-5
Assisted-by: claude-code:claude-opus-4-8