Skip to content
Browse files

Documentation Tweaks

  • Loading branch information...
1 parent a38f226 commit 2edf5c652ef642579919a18531bd3a8ad8cf7cee @lpsmith committed Feb 17, 2013
View
22 Setup.hs
@@ -1,2 +1,22 @@
import Distribution.Simple
-main = defaultMain
+import Distribution.Simple.Setup ( haddockDistPref, Flag(..))
+import Distribution.Verbosity ( normal )
+import Distribution.Simple.Utils ( copyFiles )
+import Distribution.Text ( display )
+import Text.Groom
+import System.FilePath ((</>))
+import System.Directory
+
+-- Ugly hack, logic copied from Distribution.Simple.Haddock
+haddockOutputDir flags pkg = destDir
+ where
+ baseDir = case haddockDistPref flags of
+ NoFlag -> "."
+ Flag x -> x
+ destDir = baseDir </> "doc" </> "html" </> display (packageName pkg)
+
+main = defaultMainWithHooks simpleUserHooks {
+ postHaddock = \args flags pkg lbi -> do
+ copyFiles normal (haddockOutputDir flags pkg) [("doc","split.png")]
+ postHaddock simpleUserHooks args flags pkg lbi
+ }
View
BIN doc/split.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
9 split-channel.cabal
@@ -1,5 +1,5 @@
name: split-channel
-version: 0.1.2.1
+version: 0.1.2.2
synopsis:
Control.Concurrent.Chan split into sending and receiving halves.
license: MIT
@@ -8,9 +8,12 @@ author: Leon P Smith
maintainer: leon@melding-monads.com
copyright: (c) 2012 Leon P Smith
category: Concurrency
-build-type: Simple
+build-type: Custom
cabal-version: >=1.8
+extra-source-files:
+ doc/split.png
+
library
hs-source-dirs: src
exposed-modules: Control.Concurrent.Chan.Split
@@ -26,4 +29,4 @@ source-repository head
source-repository this
type: git
location: http://github.com/lpsmith/split-channel
- tag: v0.1.2.1
+ tag: v0.1.2.2
View
58 src/Control/Concurrent/Chan/Split/Implementation.hs
@@ -50,7 +50,7 @@ new = do
-- | Produces a new channel that initially has zero @ReceivePorts@.
--- Any elements written to this channel before a reader is @'listen'ing@
+-- Any messages written to this channel before a reader is @'listen'ing@
-- will be eligible for garbage collection. Note that one can
-- one can implement 'newSendPort' in terms of 'new' by throwing away the
-- 'ReceivePort' and letting it be garbage collected, and that one can
@@ -62,7 +62,7 @@ newSendPort = SendPort `fmap` (newMVar =<< newEmptyMVar)
-- | Create a new @ReceivePort@ attached the same channel as a given
-- @SendPort@. This @ReceivePort@ starts out empty, and remains so
--- until more elements are written to the @SendPort@.
+-- until more messages are written to the @SendPort@.
listen :: SendPort a -> IO (ReceivePort a)
listen (SendPort a) = ReceivePort `fmap` withMVar a newMVar
@@ -77,7 +77,7 @@ duplicate :: ReceivePort a -> IO (ReceivePort a)
duplicate (ReceivePort a) = ReceivePort `fmap` withMVar a newMVar
--- | Fetch an element from a channel. If no element is available, it blocks
+-- | Fetch a message from a channel. If no message is available, it blocks
-- until one is. Can be used in conjunction with @System.Timeout@.
receive :: ReceivePort a -> IO a
@@ -86,8 +86,7 @@ receive (ReceivePort r) = do
(Item val new_read_end) <- readMVar read_end
return (new_read_end, val)
-
--- | Send an element to a channel. This is asynchronous and does not block.
+-- | Send a message to a channel. This is asynchronous and does not block.
send :: SendPort a -> a -> IO ()
send (SendPort s) a = do
@@ -141,50 +140,13 @@ sendMany s (a:as) = do
putMVar hole msgs
putMVar s new_hole
--- | This function associates a brand new channel with a existing send
--- port, returning a new receive port associated with the existing
--- send port and a new send port associated with the existing receive
--- ports of the existing send port.
---
--- A possible use case is to transparently replace the backend of a service
--- without affecting the clients of that service. For example, 'split' might
--- be used along the following lines:
---
--- @
--- data Service = Service { sp :: SendPort Request, .. }
---
--- swapService :: Service -> IO ()
--- swapService s = do
--- (rp', sp') <- split (sp s)
--- send sp' ShutdownRequest
--- forkNewService rp'
--- @
---
--- This is not a good solution in all cases. For example, the service
--- might consist of multiple threads, and maybe some of those send
--- internal messages on the same channel as the clients. It would probably
--- be a bug to change the destination of those internal messages.
---
--- Wrapping the @SendPort@ in 'MVar' would introduce an extra layer of
--- indirection, but also allows you to be selective about which senders
--- observe the effect. The clients would use an
--- @MVar (SendPort RequestOrInternalMessage)@ whereas the internal
--- threads would use the @SendPort RequestOrInternalMessage@ directly,
--- without going through the MVar. So instead we have something that
--- looks like:
---
--- @
--- data Service = Service { spRef :: MVar (SendPort Request), .. }
---
--- swapService :: Service -> IO ()
--- swapService s = do
--- (sp', rp') <- new
--- sp <- swapMVar (spRef s) sp'
--- send sp ShutdownRequest
--- forkNewService rp'
--- @
+-- | This function splits an existing channel in two; associating
+-- a new receive port with the old send port, and a new send
+-- port with the existing receive ports. The new receive port
+-- starts out empty, while the existing receive ports retain
+-- any unprocessed messages.
--
--- Note that this alternative does not use @split@ at all.
+-- <<split.png>>
split :: SendPort a -> IO (ReceivePort a, SendPort a)
split (SendPort s) = do
View
8 src/Control/Concurrent/Chan/Split/Internal.hs
@@ -15,10 +15,10 @@
-- If you come up with any new operations and some good use cases for them,
-- let me know and I'll consider including them here or in the public API.
--
--- Note that the usual caveat that this module does not follow Cabal's
--- Package Versioning policy applies. This can change at any time,
--- potentially even breaking your code without causing a compile-time
--- error.
+-- Note that the usual caveat that the Package Version Policy does not
+-- apply to this module. The interface can change at any time,
+-- potentially breaking your code without even causing a compile-time
+-- error.
--
------------------------------------------------------------------------------

0 comments on commit 2edf5c6

Please sign in to comment.
Something went wrong with that request. Please try again.