libusbredirparser and libusbredirhost are *not* 100% thread-safe. They allow

usage from multiple threads, but with limitations.

The intended usage of the multi-threading support for libusbredirparser is to

have one reader thread and allow writes / packet sends from multiple threads

(including the reader thread). It is up to the app to deal with flushing

writes by calling do_write itself. do_write may be called from multiple

threads, libusbredirparser will serialize any calls to the write callback.

The intended usage of the multi-threading support for libusbredirhost is to

have one reader thread, one thread calling libusb's handle_events function

and optionally also a separate writer thread.

libusbredirhost offers setting a write flush callback, which it will call

(if set) everytime it has queued some data to write. This can be used to

wakeup a writer thread or it can call usbredirhost_write_guest_data, to

directly write out the queued data from the context of its caller. Note that

the flush callback may be called from both usbredirparser_do_read as well

as from libusb_handle_events, so if those are done in separate threads,

it may get called from multiple threads!!

The above translates to some functions only allowing one caller at a time,

while others allow multiple callers, see below for a detailed overview.

In order to enable the multi-thread support in libusbredir* the app

must provide a number of locking callback functions, for libusbredirparser

this is done by filling in the usbredirparser_*_lock funcs in the

usbredirparser struct before calling usbredirparser_init(). For

libusbredirhost the locking functions (and a write-flush callback) can

be specified by using usbredirhost_open_full() instead of

usbredirhost_open().

Note that the alloc_lock_func may not fail! If it returns NULL no locking

will be done and usage from multiple threads will be unsafe.

Overview of per function multi-thread safeness

----------------------------------------------

usbredirparser:

-Only one caller allowed at a time:

 usbredirparser_create

 usbredirparser_init

 usbredirparser_destroy

 usbredirparser_do_read

-Multiple callers allowed:

 usbredirparser_get_peer_caps (1)

 usbredirparser_peer_has_cap (1)

 usbredirparser_has_data_to_write

 usbredirparser_do_write

 usbredirparser_free_write_buffer

 usbredirparser_free_packet_data

 usbredirparser_send_*

usbredirhost:

-Only one caller allowed at a time:

 usbredirhost_open

 usbredirhost_open_full

 usbredirhost_close

 usbredirhost_read_guest_data

 usbredirhost_set_device

-Multiple callers allowed:

 usbredirhost_has_data_to_write

 usbredirhost_write_guest_data

 usbredirhost_free_write_buffer

 libusb_handle_events (2)

(1) These only return the actual peer caps after the initial hello message

    has been read, as indicated by the hello_func callback.

(2) libusb is thread safe itself, thus allowing multiple callers.