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