From dd1606607e4612d3949764a0c5fb213a4593b56b Mon Sep 17 00:00:00 2001 From: Martin Braun Date: Thu, 22 Aug 2019 14:49:15 -0700 Subject: docs: Improve language on threading for recv() and send() --- host/docs/general.dox | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) (limited to 'host/docs') 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. -Note: "O" and "U" message are generally harmless, and just mean the host machine can't keep up with the requested rates. +Note: "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: Fast-path thread requirements: 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. Slow-path thread requirements: It is safe to change multiple settings simultaneously. However, this could leave the settings for a -- cgit v1.2.3