diff options
| -rw-r--r-- | host/docs/general.dox | 18 | ||||
| -rw-r--r-- | host/include/uhd/stream.hpp | 12 |
2 files changed, 23 insertions, 7 deletions
diff --git a/host/docs/general.dox b/host/docs/general.dox index 8088b8ff6..2dab0a9ea 100644 --- a/host/docs/general.dox +++ b/host/docs/general.dox @@ -189,7 +189,8 @@ Underflow occurs when the host does not produce data fast enough. When UHD software detects the underflow, it prints a "U" to stdout, and pushes a message packet into the async message stream. -<b>Note:</b> "O" and "U" message are generally harmless, and just mean the host machine can't keep up with the requested rates. +<b>Note:</b> "O" and "U" message are generally harmless, and just mean the host +machine can't keep up with the requested rates. \section general_threading Threading Notes @@ -199,11 +200,16 @@ For the most part, UHD software is thread-safe. Please observe the following limitations: <b>Fast-path thread requirements:</b> There are three fast-path methods for -a device: uhd::tx_streamer::send(), uhd::rx_streamer::recv(), and uhd::tx_streamer::recv_async_msg(). -All three methods are thread-safe and can be called from different thread -contexts. For performance, the user should call each method from a -separate thread context. These methods can also be used in a -non-blocking fashion by using a timeout of zero. +a device: uhd::tx_streamer::send(), uhd::rx_streamer::recv(), and +uhd::tx_streamer::recv_async_msg(). +It is safe to call all three methods from different threads, and that may even +be advantageous from a performance perspective in the user application. +It is not safe, however, to call `recv()` or `send()` on the same streamer from +different threads (for example, it is not allowed to have a multi-producer +software architecture, and share access to the `send()` call without serializing +its access). +These methods can also be used in a non-blocking fashion by using a timeout of +zero. <b>Slow-path thread requirements:</b> It is safe to change multiple settings simultaneously. However, this could leave the settings for a diff --git a/host/include/uhd/stream.hpp b/host/include/uhd/stream.hpp index 85f7eaa0f..7abab5b3c 100644 --- a/host/include/uhd/stream.hpp +++ b/host/include/uhd/stream.hpp @@ -208,7 +208,10 @@ public: * * Note on threading: recv() is *not* thread-safe, to avoid locking * overhead. The application calling recv() is responsible for making - * sure that not more than one thread can call recv() at the same time. + * sure that not more than one thread can call recv() on the same streamer + * at the same time. If there are multiple streamers, receiving from + * different sources, then those may be called from different threads + * simultaneously. * * \param buffs a vector of writable memory to fill with samples * \param nsamps_per_buff the size of each buffer in number of samples @@ -273,6 +276,13 @@ public: * Under a timeout condition, the number of samples returned * may be less than the number of samples specified. * + * Note on threading: send() is *not* thread-safe, to avoid locking + * overhead. The application calling send() is responsible for making + * sure that not more than one thread can call send() on the same streamer + * at the same time. If there are multiple streamers, transmitting to + * different destinations, then those may be called from different threads + * simultaneously. + * * \param buffs a vector of read-only memory containing samples * \param nsamps_per_buff the number of samples to send, per buffer * \param metadata data describing the buffer's contents |