Commit 4887c308 authored by Nathan Collins's avatar Nathan Collins Committed by Ben Gamari
Browse files

Improve Control.Monad docs

Summary:
* Reformat Control.Monad.mfilter docs

The formatting was bad, with everything running together, and a
paranthesis was missing. Now the examples and relation between
`filter` and `mfilter` are typeset as code blocks instead of inline.

* 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.

* Add example to Control.Monad.forever docs

The example is a simple TCP echo server. To make the uses of `forever`
stand out in the example code, I only link to the non-`forever`
functions (e.g. `forkFinally`) in the import lists.

Reviewers: bgamari, hvr

Subscribers: rwbarton, thomie, carter

Differential Revision: https://phabricator.haskell.org/D4259
parent a67c2642
......@@ -152,7 +152,37 @@ f >=> g = \x -> f x >>= g
(<=<) :: Monad m => (b -> m c) -> (a -> m b) -> (a -> m c)
(<=<) = flip (>=>)
-- | @'forever' act@ repeats the action infinitely.
-- | Repeat an action indefinitely.
--
-- ==== __Examples__
--
-- Simple network servers can be created by writing a function to
-- handle a single client connection and then using 'forever' to
-- accept client connections and fork threads to handle them.
--
-- For example, here is a [TCP echo
-- server](https://en.wikipedia.org/wiki/Echo_Protocol) implemented
-- with 'forever':
--
-- @
-- import "Control.Concurrent" ( 'Control.Concurrent.forkFinally' )
-- import "Control.Monad" ( 'forever' )
-- import Network ( PortID(..), accept, listenOn )
-- import "System.IO" ( 'System.IO.hClose', 'System.IO.hGetLine', 'System.IO.hPutStrLn' )
--
-- main :: IO ()
-- main = do
-- sock <- listenOn (PortNumber 7)
-- 'forever' $ do
-- (handle, _, _) <- accept sock
-- echo handle \`forkFinally\` const (hClose handle)
-- where
-- echo handle = 'forever' $
-- hGetLine handle >>= hPutStrLn handle
-- @
--
-- The @Network@ module is provided by the [network
-- package](https://hackage.haskell.org/package/network).
forever :: (Applicative f) => f a -> f b
{-# INLINE forever #-}
forever a = let a' = a *> a' in a'
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment