[commit: ghc] ghc-8.2: Improve `readChan` documentation: (f92b2f6)

[git at git.haskell.org]

Repository : ssh://git@git.haskell.org/ghc

On branch  : ghc-8.2
Link       : http://ghc.haskell.org/trac/ghc/changeset/f92b2f6f31a029300324142b6a6f48d38428c518/ghc

>---------------------------------------------------------------

commit f92b2f6f31a029300324142b6a6f48d38428c518
Author: Ömer Sinan Ağacan <omeragacan at gmail.com>
Date:   Mon Apr 10 20:36:45 2017 +0300

    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
    
    (cherry picked from commit 42ef0845d0d2a7cc524e7048502f651d66f6a543)


>---------------------------------------------------------------

f92b2f6f31a029300324142b6a6f48d38428c518
 libraries/base/Control/Concurrent/Chan.hs | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/libraries/base/Control/Concurrent/Chan.hs b/libraries/base/Control/Concurrent/Chan.hs
index ed8e02b..ebbec7e 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]