[m-rev.] for review: Document actual behaviour of mvar.try_take and mvar.try_read.

[Peter Wang]

I still need to think more about this one.
---

library/thread.mvar.m:
    Document actual behaviour of mvar.try_take and mvar.try_read:
    both may return `no' even if the mvar was not empty.

    Clarify behaviour of mvar.read.

NEWS:
    Announce change.
---
 NEWS                  |  8 ++++++++
 library/thread.mvar.m | 19 ++++++++++++++-----
 2 files changed, 22 insertions(+), 5 deletions(-)

diff --git a/NEWS b/NEWS
index 7032804be..df5671af7 100644
--- a/NEWS
+++ b/NEWS
@@ -151,6 +151,14 @@ Changes to the Mercury standard library
 
     - pred `untake/4`
 
+### Changes to the `thread.mvar` module
+
+* The documentation of the following predicates has been clarified to match the
+  actual implementation:
+
+    - pred `try_take/4`
+    - pred `try_read/4`
+
 ### Changes to the `tree234` module
 
 * The following predicates have been added:
diff --git a/library/thread.mvar.m b/library/thread.mvar.m
index e4104e57c..d1e82ffb0 100644
--- a/library/thread.mvar.m
+++ b/library/thread.mvar.m
@@ -60,8 +60,12 @@
 :- pred take(mvar(T)::in, T::out, io::di, io::uo) is det.
 
     % Take the contents of the mvar out, leaving the mvar empty.
-    % Returns immediately with no if the mvar was empty, or yes(X) if
-    % the mvar contained X.
+    % Returns with `yes(X)' if the mvar contained X, or `no' if the
+    % operation would block.
+    %
+    % WARNING: a return value of `no' does not necessarily mean the mvar
+    % is or was empty. For example, another thread attempting to read or take
+    % an item out of the mvar may also cause `try_take' to return `no'.
     %
 :- pred try_take(mvar(T)::in, maybe(T)::out, io::di, io::uo) is det.
 
@@ -77,13 +81,18 @@
 
     % Read the contents of mvar without taking it out.
     % If the mvar is empty then block until it is full.
-    % This is similar to mvar.take followed by mvar.put, but atomic.
+    % This is similar to mvar.take followed by mvar.put, but another value
+    % cannot be placed into the mvar between the two operations.
     %
 :- pred read(mvar(T)::in, T::out, io::di, io::uo) is det.
 
     % Try to read the contents of mvar without taking it out.
-    % Returns immediately with no if the mvar was empty, or yes(X) if
-    % the mvar contained X.
+    % Returns with `yes(X)' if the mvar contained X, or `no' if the
+    % operation would block.
+    %
+    % WARNING: a return value of `no' does not necessarily mean the mvar
+    % is or was empty. For example, another thread attempting to read or take
+    % an item out of the mvar may also cause `try_read' to return `no'.
     %
 :- pred try_read(mvar(T)::in, maybe(T)::out, io::di, io::uo) is det.
 
-- 
2.25.0