Improve `readChan` documentation:

- Mention that the read end is an `MVar`, so fairness guarantees are
  inherited.

- Mention that it can throw `BlockedIndefinitelyOnMVar` exception.

Reviewers: austin, hvr, bgamari

Reviewed By: bgamari

Subscribers: rwbarton, thomie

GHC Trac Issues: #5466

Differential Revision: https://phabricator.haskell.org/D3439

1 files changed, 7 insertions, 1 deletions

diff --git a/libraries/base/Control/Concurrent/Chan.hs b/libraries/base/Control/Concurrent/Chan.hs
index ed8e02bed4..ebbec7ea99 100644
--- a/libraries/base/Control/Concurrent/Chan.hs
+++ b/libraries/base/Control/Concurrent/Chan.hs
@@ -100,7 +100,13 @@ writeChan (Chan _ writeVar) val = do
 -- completes and before modifyMVar_ installs the new value, it will set the
 -- Chan's write end to a filled hole.
 
--- |Read the next value from the 'Chan'.
+-- |Read the next value from the 'Chan'. Blocks when the channel is empty. Since
+-- the read end of a channel is an 'MVar', this operation inherits fairness
+-- guarantees of 'MVar's (e.g. threads blocked in this operation are woken up in
+-- FIFO order).
+--
+-- Throws 'BlockedIndefinitelyOnMVar' when the channel is empty and no other
+-- thread holds a reference to the channel.
 readChan :: Chan a -> IO a
 readChan (Chan readVar _) = do
   modifyMVarMasked readVar $ \read_end -> do -- Note [modifyMVarMasked]