Improve `readChan` documentation:
authorÖmer Sinan Ağacan <omeragacan@gmail.com>
Mon, 10 Apr 2017 17:36:45 +0000 (20:36 +0300)
committerÖmer Sinan Ağacan <omeragacan@gmail.com>
Mon, 10 Apr 2017 17:37:00 +0000 (20:37 +0300)
- 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

libraries/base/Control/Concurrent/Chan.hs

index ed8e02b..ebbec7e 100644 (file)
@@ -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]