A bit of documentation details on callback API #784

2026-03-30T16:34:26-05:00

Youw commented

2026-03-30 16:34:26 -05:00

(Migrated from github.com)

No description provided.

k1-801 (Migrated from github.com) reviewed

2026-03-31 06:31:27 -05:00

hidapi/hidapi.h

					
				@ -306,0 +306,4 @@

							It is NOT safe to call hid_open/hid_open_path or any other global/non-device

							functions from within this callback. If you need to open

							or close a device in response to a hotplug event, queue the

							device path and handle it on your own application thread.

I personally don't see any reason why opening or closing a device would be unsafe in a callback. There aren't any intersections between the hotplug subsystem and the code responsible for opening the devices, so there should be no race conditions.

Youw (Migrated from github.com) reviewed

2026-03-31 06:46:04 -05:00

hidapi/hidapi.h

					
				@ -306,0 +306,4 @@

							It is NOT safe to call hid_open/hid_open_path or any other global/non-device

							functions from within this callback. If you need to open

							or close a device in response to a hotplug event, queue the

							device path and handle it on your own application thread.

What can I say...
For starters, check: https://github.com/libusb/hidapi/wiki/Multi%E2%80%90threading-Notes

HIDAPI is not, and never been a thread-safe API. New register/deregister functions are not thread-safe as well.

It may be safe, only in case of all calls to hid_open_path (and others), including the ones called from within a callback function - are all correctly serialized. But for that:

It needs to be explicilty documented (it is not - not right now)
It needs to be verified/checked against implementation (I already found multiple issues with libusb implementation (#783), even with regard to functionality that is documented to be working fine)

What can I say... For starters, check: https://github.com/libusb/hidapi/wiki/Multi%E2%80%90threading-Notes HIDAPI is not, and never been a thread-safe API. New `register`/`deregister` functions are not thread-safe as well. It *may* be safe, only in case of all calls to `hid_open_path` (and others), including the ones called from within a callback function - are all correctly serialized. But for that: 1) It needs to be explicilty documented (it is not - not right now) 2) It needs to be verified/checked against implementation (I already found multiple issues with libusb implementation (#783), even with regard to functionality that is documented to be working fine)

k1-801 (Migrated from github.com) reviewed

2026-03-31 06:52:23 -05:00

hidapi/hidapi.h

					
				@ -306,0 +306,4 @@

							It is NOT safe to call hid_open/hid_open_path or any other global/non-device

							functions from within this callback. If you need to open

							or close a device in response to a hotplug event, queue the

							device path and handle it on your own application thread.

It may be safe, only in case of all calls to hid_open_path (and others), including the ones called from within a callback function - are all correctly serialized. But for that:

So, so long as no other thread opens any device, there is nothing wrong with opening a device from a callback, right?
If so, this limitation is not any different from restricting using this call from any other 2 threads, and should be then worded accordingly :)

As in "It is NOT safe to call hid_open/hid_open_path from within a callback IF any other thread may be calling those functions at the same time (concurrently). It may be safe to do so if it is known that no other thread will be calling hid_open/hid_open_path, otherwise opening the device should be queued, and the device path should be copied by the application to be used and opened later in the queue."

> It _may_ be safe, only in case of all calls to `hid_open_path` (and others), including the ones called from within a callback function - are all correctly serialized. But for that: So, so long as no other thread opens any device, there is nothing wrong with opening a device from a callback, right? If so, this limitation is not any different from restricting using this call from any other 2 threads, and should be then worded accordingly :) As in "It is NOT safe to call hid_open/hid_open_path from within a callback IF any other thread may be calling those functions at the same time (concurrently). It may be safe to do so if it is known that no other thread will be calling hid_open/hid_open_path, otherwise opening the device should be queued, and the device path should be copied by the application to be used and opened later in the queue."

Youw (Migrated from github.com) reviewed

2026-03-31 12:49:49 -05:00

hidapi/hidapi.h

					
				@ -306,0 +306,4 @@

							It is NOT safe to call hid_open/hid_open_path or any other global/non-device

							functions from within this callback. If you need to open

							or close a device in response to a hotplug event, queue the

							device path and handle it on your own application thread.

There are well-known approaches to how the wording for multithreading safety should look like.
I'll get back to this later, one I re-check that it is really safe, and in which cases.

There are well-known approaches to how the wording for multithreading safety should look like. I'll get back to this later, one I re-check that it is really safe, and in which cases.

Youw (Migrated from github.com) reviewed

2026-03-31 14:24:17 -05:00

hidapi/hidapi.h

Apparently, not really, here is one unresolved issue: https://github.com/libusb/hidapi/pull/674#discussion_r3015415035

Youw commented

2026-04-24 09:19:15 -05:00

(Migrated from github.com)

Opened #790 to expand this doc patch — keeps the intent (document the callback contract) but reworks the wording to match the Multi-threading Notes wiki style, enumerates what is safe to call, fixes the device->next / return-value wording, and spins off implementation follow-ups into #792, #793, #794, #795. Suggest closing this one in favour of #790.

Drafted with Claude Code.

Opened #790 to expand this doc patch — keeps the intent (document the callback contract) but reworks the wording to match the Multi-threading Notes wiki style, enumerates what is safe to call, fixes the `device->next` / return-value wording, and spins off implementation follow-ups into #792, #793, #794, #795. Suggest closing this one in favour of #790. --- _Drafted with Claude Code._

Youw commented

2026-04-24 15:06:22 -05:00

(Migrated from github.com)