Marge Bot pushed to branch master at Glasgow Haskell Compiler / GHC Commits: d1d01fa5 by Wolfgang Jeltsch at 2026-08-27T13:17:59+03:00 Add `rethrowSTM` and improve STM-related documentation Adding `rethrowSTM` resolves #26758. The implementation of `rethrowSTM` is completely analogous to the one of `rethrowIO`. The following is established for the documentation of `throwSTM` and `catchSTM`: * Both operations are directly described as analogs of their `IO` counterparts. * There is no reference to `throw` in the documentation of `throwSTM`, because, although such a reference is great in the documentation of `throwIO`, it is somewhat out of place in the documentation of `throwSTM`. * Instead of repeating part of `throwIO`’s documentation, the documentation of `throwSTM` just recommends using `throwSTM` instead of `throw` and references the corresponding arguments in the documentation of `throwIO`. - - - - - 3 changed files: - + changelog.d/rethrow-stm - libraries/base/src/GHC/Conc.hs - libraries/ghc-internal/src/GHC/Internal/STM.hs Changes: ===================================== changelog.d/rethrow-stm ===================================== @@ -0,0 +1,4 @@ +section: ghc-internal +synopsis: Add `rethrowSTM`, an `STM` analog of `rethrowIO` +issues: #26758 +mrs: !16501 ===================================== libraries/base/src/GHC/Conc.hs ===================================== @@ -79,6 +79,9 @@ module GHC.Conc , retry , orElse , throwSTM +#if __GLASGOW_HASKELL__ >= 1002 + , rethrowSTM +#endif , catchSTM , TVar(..) , newTVar ===================================== libraries/ghc-internal/src/GHC/Internal/STM.hs ===================================== @@ -5,6 +5,11 @@ {-# LANGUAGE RankNTypes #-} {-# OPTIONS_HADDOCK not-home #-} +-- Make unused imports warnings instead of errors, because there are seemingly +-- unused imports of `throw`, `throwIO`, and `rethrowIO`, which are actually +-- used for documentation hyperlinking. +{-# OPTIONS_GHC -Wwarn=unused-imports #-} + module GHC.Internal.STM ( -- * the 'STM' monad @@ -13,6 +18,7 @@ module GHC.Internal.STM , retry , orElse , throwSTM + , rethrowSTM , catchSTM , unsafeIOToSTM -- * TVars @@ -28,7 +34,9 @@ import qualified GHC.Internal.Stack.Types as Rebindable import GHC.Internal.Base import GHC.Internal.Exception (Exception, toExceptionWithBacktrace, fromException, addExceptionContext) import GHC.Internal.Exception.Context (ExceptionAnnotation) -import GHC.Internal.Exception.Type (WhileHandling(..)) +import GHC.Internal.Exception.Type ( + WhileHandling(..), ExceptionWithContext, NoBacktrace (NoBacktrace), + ) import GHC.Internal.Maybe (Maybe(..)) import GHC.Internal.Prim ( RealWorld, State#, TVar#, atomically#, catchRetry#, catchSTM#, @@ -37,6 +45,10 @@ import GHC.Internal.Prim ( import GHC.Internal.Prim.PtrEq (sameTVar#) import GHC.Internal.Stack (HasCallStack, withFrozenCallStack) +-- Imports for documentation hyperlinking +import GHC.Internal.Exception (throw) +import GHC.Internal.IO (throwIO, rethrowIO) + -- TVars are shared memory locations which support atomic memory -- transactions. @@ -166,7 +178,7 @@ retry = STM $ \s# -> retry# s# orElse :: STM a -> STM a -> STM a orElse (STM m) e = STM $ \s -> catchRetry# m (unSTM e) s --- | A variant of 'throw' that can only be used within the 'STM' monad. +-- | The 'STM' analog of 'throwIO'. -- -- Throwing an exception in @STM@ aborts the transaction and propagates the -- exception. If the exception is caught via 'catchSTM', only the changes @@ -176,19 +188,8 @@ orElse (STM m) e = STM $ \s -> catchRetry# m (unSTM e) s -- If the exception is not caught inside of the 'STM', it is re-thrown by -- 'atomically', and the entire 'STM' is rolled back. -- --- Although 'throwSTM' has a type that is an instance of the type of 'throw', the --- two functions are subtly different: --- --- > throw e `seq` x ===> throw e --- > throwSTM e `seq` x ===> x --- --- The first example will cause the exception @e@ to be raised, --- whereas the second one won\'t. In fact, 'throwSTM' will only cause --- an exception to be raised when it is used within the 'STM' monad. --- The 'throwSTM' variant should be used in preference to 'throw' to --- raise an exception within the 'STM' monad because it guarantees --- ordering with respect to other 'STM' operations, whereas 'throw' --- does not. +-- Note that 'throwSTM' is preferable to 'throw', for the same reasons that +-- 'throwIO' is preferable to 'throw'. throwSTM :: (HasCallStack, Exception e) => e -> STM a throwSTM e = do -- N.B. Typically use of unsafeIOToSTM is very much frowned upon as this @@ -197,7 +198,11 @@ throwSTM e = do se <- unsafeIOToSTM (withFrozenCallStack $ toExceptionWithBacktrace e) STM $ raiseIO# se --- | Exception handling within STM actions. +-- | The 'STM' analog of 'rethrowIO'. +rethrowSTM :: Exception e => ExceptionWithContext e -> STM a +rethrowSTM e = throwSTM (NoBacktrace e) + +-- | The 'STM' analog of 'catch'. -- -- @'catchSTM' m f@ catches any exception thrown by @m@ using 'throwSTM', -- using the function @f@ to handle the exception. If an exception is View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/d1d01fa55ede5b5696bbfd517d37767f... -- View it on GitLab: https://gitlab.haskell.org/ghc/ghc/-/commit/d1d01fa55ede5b5696bbfd517d37767f... You're receiving this email because of your account on gitlab.haskell.org. Manage all notifications: https://gitlab.haskell.org/-/profile/notifications | Help: https://gitlab.haskell.org/help