[commit: ghc] master: Improve stm haddocks (dd643bc)
git at git.haskell.org
git at git.haskell.org
Fri Sep 1 14:58:31 UTC 2017
Repository : ssh://git@git.haskell.org/ghc
On branch : master
Link : http://ghc.haskell.org/trac/ghc/changeset/dd643bcc970ac59507cab3b464905050d013b071/ghc
>---------------------------------------------------------------
commit dd643bcc970ac59507cab3b464905050d013b071
Author: Ben Gamari <ben at smart-cactus.org>
Date: Thu Aug 31 16:40:28 2017 -0400
Improve stm haddocks
While looking at #14171 I noticed these readability issues. Fix them.
>---------------------------------------------------------------
dd643bcc970ac59507cab3b464905050d013b071
libraries/base/GHC/Conc/Sync.hs | 59 ++++++++++++++++++++++-------------------
1 file changed, 32 insertions(+), 27 deletions(-)
diff --git a/libraries/base/GHC/Conc/Sync.hs b/libraries/base/GHC/Conc/Sync.hs
index f9514d6..06da99b 100644
--- a/libraries/base/GHC/Conc/Sync.hs
+++ b/libraries/base/GHC/Conc/Sync.hs
@@ -487,7 +487,7 @@ myThreadId = IO $ \s ->
case (myThreadId# s) of (# s1, tid #) -> (# s1, ThreadId tid #)
--- |The 'yield' action allows (forces, in a co-operative multitasking
+-- | The 'yield' action allows (forces, in a co-operative multitasking
-- implementation) a context-switch to any other currently runnable
-- threads (if any), and is occasionally useful when implementing
-- concurrency abstractions.
@@ -591,7 +591,7 @@ threadStatus (ThreadId t) = IO $ \s ->
mk_stat 17 = ThreadDied
mk_stat _ = ThreadBlocked BlockedOnOther
--- | returns the number of the capability on which the thread is currently
+-- | Returns the number of the capability on which the thread is currently
-- running, and a boolean indicating whether the thread is locked to
-- that capability or not. A thread is locked to a capability if it
-- was created with @forkOn at .
@@ -602,7 +602,7 @@ threadCapability (ThreadId t) = IO $ \s ->
case threadStatus# t s of
(# s', _, cap#, locked# #) -> (# s', (I# cap#, isTrue# (locked# /=# 0#)) #)
--- | make a weak pointer to a 'ThreadId'. It can be important to do
+-- | Make a weak pointer to a 'ThreadId'. It can be important to do
-- this if you want to hold a reference to a 'ThreadId' while still
-- allowing the thread to receive the @BlockedIndefinitely@ family of
-- exceptions (e.g. 'BlockedIndefinitelyOnMVar'). Holding a normal
@@ -714,7 +714,7 @@ instance MonadPlus STM
unsafeIOToSTM :: IO a -> STM a
unsafeIOToSTM (IO m) = STM m
--- |Perform a series of STM actions atomically.
+-- | Perform a series of STM actions atomically.
--
-- You cannot use 'atomically' inside an 'unsafePerformIO' or 'unsafeInterleaveIO'.
-- Any attempt to do so will result in a runtime error. (Reason: allowing
@@ -727,19 +727,20 @@ unsafeIOToSTM (IO m) = STM m
atomically :: STM a -> IO a
atomically (STM m) = IO (\s -> (atomically# m) s )
--- |Retry execution of the current memory transaction because it has seen
--- values in TVars which mean that it should not continue (e.g. the TVars
+-- | Retry execution of the current memory transaction because it has seen
+-- values in 'TVar's which mean that it should not continue (e.g. the 'TVar's
-- represent a shared buffer that is now empty). The implementation may
--- block the thread until one of the TVars that it has read from has been
+-- block the thread until one of the 'TVar's that it has read from has been
-- updated. (GHC only)
retry :: STM a
retry = STM $ \s# -> retry# s#
--- |Compose two alternative STM actions (GHC only). If the first action
--- completes without retrying then it forms the result of the orElse.
--- Otherwise, if the first action retries, then the second action is
--- tried in its place. If both actions retry then the orElse as a
--- whole retries.
+-- | Compose two alternative STM actions (GHC only).
+--
+-- If the first action completes without retrying then it forms the result of
+-- the 'orElse'. Otherwise, if the first action retries, then the second action
+-- is tried in its place. If both actions retry then the 'orElse' as a whole
+-- retries.
orElse :: STM a -> STM a -> STM a
orElse (STM m) e = STM $ \s -> catchRetry# m (unSTM e) s
@@ -772,16 +773,17 @@ catchSTM (STM m) handler = STM $ catchSTM# m handler'
Just e' -> unSTM (handler e')
Nothing -> raiseIO# e
--- | Low-level primitive on which always and alwaysSucceeds are built.
--- checkInv differs form these in that (i) the invariant is not
--- checked when checkInv is called, only at the end of this and
--- subsequent transcations, (ii) the invariant failure is indicated
--- by raising an exception.
+-- | Low-level primitive on which 'always' and 'alwaysSucceeds' are built.
+-- 'checkInv' differs from these in that,
+--
+-- 1. the invariant is not checked when 'checkInv' is called, only at the end of
+-- this and subsequent transactions
+-- 2. the invariant failure is indicated by raising an exception.
checkInv :: STM a -> STM ()
checkInv (STM m) = STM (\s -> case (check# m) s of s' -> (# s', () #))
--- | alwaysSucceeds adds a new invariant that must be true when passed
--- to alwaysSucceeds, at the end of the current transaction, and at
+-- | 'alwaysSucceeds' adds a new invariant that must be true when passed
+-- to 'alwaysSucceeds', at the end of the current transaction, and at
-- the end of every subsequent transaction. If it fails at any
-- of those points then the transaction violating it is aborted
-- and the exception raised by the invariant is propagated.
@@ -789,9 +791,9 @@ alwaysSucceeds :: STM a -> STM ()
alwaysSucceeds i = do ( i >> retry ) `orElse` ( return () )
checkInv i
--- | always is a variant of alwaysSucceeds in which the invariant is
--- expressed as an STM Bool action that must return True. Returning
--- False or raising an exception are both treated as invariant failures.
+-- | 'always' is a variant of 'alwaysSucceeds' in which the invariant is
+-- expressed as an @STM Bool@ action that must return @True at . Returning
+-- @False@ or raising an exception are both treated as invariant failures.
always :: STM Bool -> STM ()
always i = alwaysSucceeds ( do v <- i
if (v) then return () else ( errorWithoutStackTrace "Transactional invariant violation" ) )
@@ -803,13 +805,13 @@ data TVar a = TVar (TVar# RealWorld a)
instance Eq (TVar a) where
(TVar tvar1#) == (TVar tvar2#) = isTrue# (sameTVar# tvar1# tvar2#)
--- |Create a new TVar holding a value supplied
+-- | Create a new 'TVar' holding a value supplied
newTVar :: a -> STM (TVar a)
newTVar val = STM $ \s1# ->
case newTVar# val s1# of
(# s2#, tvar# #) -> (# s2#, TVar tvar# #)
--- |@IO@ version of 'newTVar'. This is useful for creating top-level
+-- | @IO@ version of 'newTVar'. This is useful for creating top-level
-- 'TVar's using 'System.IO.Unsafe.unsafePerformIO', because using
-- 'atomically' inside 'System.IO.Unsafe.unsafePerformIO' isn't
-- possible.
@@ -818,7 +820,7 @@ newTVarIO val = IO $ \s1# ->
case newTVar# val s1# of
(# s2#, tvar# #) -> (# s2#, TVar tvar# #)
--- |Return the current value stored in a TVar.
+-- | Return the current value stored in a 'TVar'.
-- This is equivalent to
--
-- > readTVarIO = atomically . readTVar
@@ -828,11 +830,11 @@ newTVarIO val = IO $ \s1# ->
readTVarIO :: TVar a -> IO a
readTVarIO (TVar tvar#) = IO $ \s# -> readTVarIO# tvar# s#
--- |Return the current value stored in a TVar
+-- |Return the current value stored in a 'TVar'.
readTVar :: TVar a -> STM a
readTVar (TVar tvar#) = STM $ \s# -> readTVar# tvar# s#
--- |Write the supplied value into a TVar
+-- |Write the supplied value into a 'TVar'.
writeTVar :: TVar a -> a -> STM ()
writeTVar (TVar tvar#) val = STM $ \s1# ->
case writeTVar# tvar# val s1# of
@@ -842,6 +844,8 @@ writeTVar (TVar tvar#) val = STM $ \s1# ->
-- MVar utilities
-----------------------------------------------------------------------------
+-- | Provide an 'IO' action with the current value of an 'MVar'. The 'MVar'
+-- will be empty for the duration that the action is running.
withMVar :: MVar a -> (a -> IO b) -> IO b
withMVar m io =
mask $ \restore -> do
@@ -851,6 +855,7 @@ withMVar m io =
putMVar m a
return b
+-- | Modify the value of an 'MVar'.
modifyMVar_ :: MVar a -> (a -> IO a) -> IO ()
modifyMVar_ m io =
mask $ \restore -> do
More information about the ghc-commits
mailing list