Add example to Control.Monad.join docs
authorNathan Collins <conathan@galois.com>
Sun, 10 Dec 2017 02:58:03 +0000 (18:58 -0800)
committerBen Gamari <ben@smart-cactus.org>
Tue, 2 Jan 2018 21:28:09 +0000 (16:28 -0500)
The example is using `join . atomically` to run IO actions computed by
STM transactions.

I couldn't figure out how to link to the STM docs in
`Control.Monad.STM`, because that module comes from the `stm` package,
not from `base`, even though `stm` is also part of the GHC source
tree. So, instead I linked to the STM docs in `GHC.Conc`, which seems
inferior to linking to `Control.Monad.STM`, but better than having no
links at all.

libraries/base/GHC/Base.hs

index 35de446..7875fef 100644 (file)
@@ -596,6 +596,33 @@ liftA3 f a b c = liftA2 f a b <*> c
 -- | The 'join' function is the conventional monad join operator. It
 -- is used to remove one level of monadic structure, projecting its
 -- bound argument into the outer level.
+--
+-- ==== __Examples__
+--
+-- A common use of 'join' is to run an 'IO' computation returned from
+-- an 'GHC.Conc.STM' transaction, since 'GHC.Conc.STM' transactions
+-- can't perform 'IO' directly. Recall that
+--
+-- @
+-- 'GHC.Conc.atomically' :: STM a -> IO a
+-- @
+--
+-- is used to run 'GHC.Conc.STM' transactions atomically. So, by
+-- specializing the types of 'GHC.Conc.atomically' and 'join' to
+--
+-- @
+-- 'GHC.Conc.atomically' :: STM (IO b) -> IO (IO b)
+-- 'join'       :: IO (IO b)  -> IO b
+-- @
+--
+-- we can compose them as
+--
+-- @
+-- 'join' . 'GHC.Conc.atomically' :: STM (IO b) -> IO b
+-- @
+--
+-- to run an 'GHC.Conc.STM' transaction and the 'IO' action it
+-- returns.
 join              :: (Monad m) => m (m a) -> m a
 join x            =  x >>= id