diff options
| author | Nathan Collins <conathan@galois.com> | 2017-12-09 18:58:03 -0800 |
|---|---|---|
| committer | Ben Gamari <ben@smart-cactus.org> | 2018-01-02 16:28:09 -0500 |
| commit | a67c264201a5d73d3624a73359f36adfaf6ec33c (patch) | |
| tree | a0f76878bac0ecd9c35d43d16ccaa16aa8f6cd3b | |
| parent | 69f1e49dfe33de4e077ec8b1e43432929a4e833e (diff) | |
| download | haskell-a67c264201a5d73d3624a73359f36adfaf6ec33c.tar.gz | |
Add example to Control.Monad.join docs
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.
| -rw-r--r-- | libraries/base/GHC/Base.hs | 27 |
1 files changed, 27 insertions, 0 deletions
diff --git a/libraries/base/GHC/Base.hs b/libraries/base/GHC/Base.hs index 35de446ca6..7875fef3c1 100644 --- a/libraries/base/GHC/Base.hs +++ b/libraries/base/GHC/Base.hs @@ -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 |