Documentation: add multi-threading notes

[Youw]

need add notes to README regarding multithreading, e.g. regarding Windows issues/non-full support
maybe some more

[Youw]

NOTE for everyone: hidapi not thread-safe in general, with a few platform-specific/usage-spacific exceptions.

Damn, I need to get my hands to describe everything in details.

[mcuee]

Reference: Windows: unable to interrupt blocking hid_read call #133

[mcuee]

I see this and #133 are tied to 0.13.0 milestone. Supposedly this one will "help" #133, right?

Any activities on this one?

#146 is supposed to fix #133, but I see no activities there.

[mcuee]

@Youw
Just wondering what is the plan for 0.13.0 release, say as a Christmas gift. :-)

[Youw]

0.13 already includes a lot of good improvements, so I guess making a release (before Christmas) would be a good thing regardless if it is going to include the multithreaded documentation/fixes or not

[mcuee]

0.13 already includes a lot of good improvements, so I guess making a release (before Christmas) would be a good thing regardless if it is going to include the multithreaded documentation/fixes or not

I agree. Thanks.

[mcuee]

@Youw

It is great that you have released hidapi 0.13. Thanks.

[mcuee]

Reference by Youw.

• A selectable interface for waiting on reads being available #202 (comment)

As for multithreaded usage of hidapi - many projects successfully using a separate thread for hid_read/_timeout, and another thread for read/everything else.

[mcuee]

Another reference by Youw.

• Windows: unable to interrupt blocking hid_read call #133 (comment)

client code should first stop any read/write attempts before trying to close the device as hid_close cannot not be thread-safe by design, even it it is sometime, for some implementations.

[mcuee]

Add a stub FAQ entry here.
https://github.com/libusb/hidapi/wiki#faq

[mcuee]

Comments by Youw here.

• Crash when calling enumerate from different threads (not simultaneously) trezor/cython-hidapi#148 (comment)

Oh yes, HIDAPI on macOS has an additional issue regarding thread-safety. I did encountered it in my project(s) but didn't have enough time to gather info/find a root cause. Looks like on macOS hid_init/hid_exit needs to be called in the same thread, which is an additional restriction compared to other platforms.

[mcuee]

Reference from node-hid.
https://github.com/node-hid/node-hid#thread-safety-worker-threads-context-aware-modules

Thread safety, Worker threads, Context-aware modules
In general node-hid is not thread-safe because the underlying C-library it wraps (hidapi) is not thread-safe. However, node-hid is now reporting as minimally Context Aware to allow use in Electron v9+. Until node-hid (or hidapi) is rewritten to be thread-safe, please constrain all accesses to it via a single thread.

[k1-801]

Oh yes, HIDAPI on macOS has an additional issue regarding thread-safety. I did encountered it in my project(s) but didn't have enough time to gather info/find a root cause. Looks like on macOS hid_init/hid_exit needs to be called in the same thread, which is an additional restriction compared to other platforms.

I have a potential solution, described fully in #666

[Masterxilo]

I found this old discussion on multithreading in hidapi maybe it helps in writing the documentation signal11/hidapi#72

[Masterxilo]

In my usecase, I will interact with one device on one thread always, but I want to interact with different devices on different threads simultaneously.

Are all hidapi implementations at least thread-safe enough for this?

I don't need to be able to talk to one device from multiple threads simultaneously and I would think that makes sense only very rarely anyways. I observed that for instance on Windows, multiple threads and programs talking to the same device at the same time are allowed, but the order in which the reports are received in each direction gets garbled up. Even on a conceptual level talking to one device from multiple threads doesn't make much sense.

But talking to different devices on different threads/programs seems natural and should be possible for performance reasons. It should make no difference whether I use program x to talk to device a and program y to talk to device b, or simply two threads 1&2 in a single program to talk to devices a&b.

Do the hidapi implementations guarantee that this works?

[JoergAtGithub]

You can enumerate and open the devices in a main thread, and once opened successful, you can move the device handle into a communication thread per device, where you do all read/write ops and finally close the device.

[Masterxilo]

Thanks for the feedback @JoergAtGithub. I don't even need or want to open the devices on that main thread, but yes i will need to enumerate them once in a main thread to get the vid/pid/usb serials I am interested in.

So do the hidapi implementations guarantee that then opening the devices in the different communication threads is safe, even if, say, I were to do another enumeration again on the main thread simultaneously?

I have the feeling I saw some caching mechanisms in some of the hidapi implementations (having to do with USB characteristics?) that make me doubt this is thread-safe...

So yeah my requirement would be that there can be one main thread doing enumeration (potentially in a loop, forever), while other threads communicate with the existing devices undisturbed, one thread per device. Well maybe some threads will handle more than one device, but no device will be opened by more than one thread.

I currently make sure to do absolutely all hidapi work in a single thread and that obviously works fine, but I am afraid to break things in moving past that for performance reasons...

I would need pretty strong guarantees to be confident this works in all implementations and will continue to do so, i.e. hidapi would have to commit to and document some level of some notion of this kind of "per device" & single-enumeration thread-safety...

Note I don't need that enumeration itself is thread safe - there's no point in enumerating in more than one thread simultaneously.

[Masterxilo]

Short of that guarantee, i would imagine the only other safe option I would have is to enumerate in a main program, then spawn a separate process per device. I would imagine the operating systems guarantee this works fine when each process talks to another device and I don't imagine any hidapi implementation uses some system wide shared memory in some misguided attempt to share some cached data/state...