Hello community,
here is the log from the commit of package ghc-unliftio for openSUSE:Factory
checked in at 2020-11-06 23:44:51
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Comparing /work/SRC/openSUSE:Factory/ghc-unliftio (Old)
and /work/SRC/openSUSE:Factory/.ghc-unliftio.new.11331 (New)
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Package is "ghc-unliftio"
Fri Nov 6 23:44:51 2020 rev:13 rq:846364 version:0.2.13.1
Changes:
--------
--- /work/SRC/openSUSE:Factory/ghc-unliftio/ghc-unliftio.changes
2020-08-28 21:40:26.760866664 +0200
+++ /work/SRC/openSUSE:Factory/.ghc-unliftio.new.11331/ghc-unliftio.changes
2020-11-06 23:45:13.847248516 +0100
@@ -1,0 +2,8 @@
+Fri Oct 30 03:01:41 UTC 2020 - psim...@suse.com
+
+- Update unliftio to version 0.2.13.1.
+ ## 0.2.13.1
+
+ * Improve `UnliftIO.Exception` documentation
+
+-------------------------------------------------------------------
Old:
----
unliftio-0.2.13.tar.gz
New:
----
unliftio-0.2.13.1.tar.gz
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Other differences:
------------------
++++++ ghc-unliftio.spec ++++++
--- /var/tmp/diff_new_pack.SsrTDK/_old 2020-11-06 23:45:14.867246556 +0100
+++ /var/tmp/diff_new_pack.SsrTDK/_new 2020-11-06 23:45:14.871246548 +0100
@@ -19,7 +19,7 @@
%global pkg_name unliftio
%bcond_with tests
Name: ghc-%{pkg_name}
-Version: 0.2.13
+Version: 0.2.13.1
Release: 0
Summary: The MonadUnliftIO typeclass for unlifting monads to IO
(batteries included)
License: MIT
++++++ unliftio-0.2.13.tar.gz -> unliftio-0.2.13.1.tar.gz ++++++
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/unliftio-0.2.13/ChangeLog.md
new/unliftio-0.2.13.1/ChangeLog.md
--- old/unliftio-0.2.13/ChangeLog.md 2020-05-21 10:45:35.000000000 +0200
+++ new/unliftio-0.2.13.1/ChangeLog.md 2020-10-29 10:02:46.000000000 +0100
@@ -1,5 +1,9 @@
# Changelog for unliftio
+## 0.2.13.1
+
+* Improve `UnliftIO.Exception` documentation
+
## 0.2.13
* Add `UnliftIO.STM.orElse`
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/unliftio-0.2.13/README.md
new/unliftio-0.2.13.1/README.md
--- old/unliftio-0.2.13/README.md 2020-05-21 10:45:16.000000000 +0200
+++ new/unliftio-0.2.13.1/README.md 2020-10-29 11:04:07.000000000 +0100
@@ -1,6 +1,6 @@
# unliftio
-[](https://dev.azure.com/fpco/unliftio/_build/latest?definitionId=3&branchName=master)
+
Provides the core `MonadUnliftIO` typeclass, a number of common
@@ -131,31 +131,33 @@
pre-unlifted versions of functions (like
`UnliftIO.Exception.catch`). But ultimately, you'll probably want to
use the typeclass directly. The type class has only one method --
-`askUnliftIO`:
+`withRunInIO`:
```haskell
-newtype UnliftIO m = UnliftIO { unliftIO :: forall a. m a -> IO a }
-
class MonadIO m => MonadUnliftIO m where
- askUnliftIO :: m (UnliftIO m)
+ withRunInIO :: ((forall a. m a -> IO a) -> IO b) -> m b
```
-`askUnliftIO` gives us a function to run arbitrary computation in `m`
+`withRunInIO` provides a function to run arbitrary computations in `m`
in `IO`. Thus the "unlift": it's like `liftIO`, but the other way around.
Here are some sample typeclass instances:
```haskell
instance MonadUnliftIO IO where
- askUnliftIO = return (UnliftIO id)
-instance MonadUnliftIO m => MonadUnliftIO (IdentityT m) where
- askUnliftIO = IdentityT $
- withUnliftIO $ \u ->
- return (UnliftIO (unliftIO u . runIdentityT))
+ withRunInIO inner = inner id
+
instance MonadUnliftIO m => MonadUnliftIO (ReaderT r m) where
- askUnliftIO = ReaderT $ \r ->
- withUnliftIO $ \u ->
- return (UnliftIO (unliftIO u . flip runReaderT r))
+ withRunInIO inner =
+ ReaderT $ \r ->
+ withRunInIO $ \run ->
+ inner (run . flip runReaderT r)
+
+instance MonadUnliftIO m => MonadUnliftIO (IdentityT m) where
+ withRunInIO inner =
+ IdentityT $
+ withRunInIO $ \run ->
+ inner (run . runIdentityT)
```
Note that:
@@ -163,21 +165,12 @@
* The `IO` instance does not actually do any lifting or unlifting, and
therefore it can use `id`
* `IdentityT` is essentially just wrapping/unwrapping its data
- constructor, and then recursively calling `withUnliftIO` on the
+ constructor, and then recursively calling `withRunInIO` on the
underlying monad.
* `ReaderT` is just like `IdentityT`, but it captures the reader
environment when starting.
-We can use `askUnliftIO` to unlift a function:
-
-```haskell
-timeout :: MonadUnliftIO m => Int -> m a -> m (Maybe a)
-timeout x y = do
- (u :: UnliftIO m) <- askUnliftIO
- liftIO $ System.Timeout.timeout x $ unliftIO u y
-```
-
-or more concisely using `withRunInIO`:
+We can use `withRunInIO` to unlift a function:
```haskell
timeout :: MonadUnliftIO m => Int -> m a -> m (Maybe a)
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/unliftio-0.2.13/src/UnliftIO/Exception.hs
new/unliftio-0.2.13.1/src/UnliftIO/Exception.hs
--- old/unliftio-0.2.13/src/UnliftIO/Exception.hs 2020-05-21
10:45:16.000000000 +0200
+++ new/unliftio-0.2.13.1/src/UnliftIO/Exception.hs 2020-10-29
10:02:46.000000000 +0100
@@ -9,7 +9,7 @@
--
-- This module works best when your cleanup functions adhere to certain
-- expectations around exception safety and interruptible actions.
--- For more details, see [this exception safety
tutorial](https://haskell.fpcomplete.com/tutorial/exceptions).
+-- For more details, see [this exception safety
tutorial](https://www.fpcomplete.com/haskell/tutorial/exceptions/).
module UnliftIO.Exception
( -- * Throwing
throwIO
@@ -101,10 +101,17 @@
import GHC.Stack.Types (HasCallStack, CallStack, getCallStack)
#endif
--- | Unlifted 'EUnsafe.catch', but will not catch asynchronous exceptions.
+-- | Catch a synchronous (but not asynchronous) exception and recover from it.
+--
+-- This is parameterized on the exception type. To catch all synchronous
exceptions,
+-- use 'catchAny'.
--
-- @since 0.1.0.0
-catch :: (MonadUnliftIO m, Exception e) => m a -> (e -> m a) -> m a
+catch
+ :: (MonadUnliftIO m, Exception e)
+ => m a -- ^ action
+ -> (e -> m a) -- ^ handler
+ -> m a
catch f g = withRunInIO $ \run -> run f `EUnsafe.catch` \e ->
if isSyncException e
then run (g e)
@@ -118,7 +125,7 @@
catchIO :: MonadUnliftIO m => m a -> (IOException -> m a) -> m a
catchIO = catch
--- | 'catch' specialized to catch all synchronous exception.
+-- | 'catch' specialized to catch all synchronous exceptions.
--
-- @since 0.1.0.0
catchAny :: MonadUnliftIO m => m a -> (SomeException -> m a) -> m a
@@ -182,7 +189,10 @@
handleJust :: (MonadUnliftIO m, Exception e) => (e -> Maybe b) -> (b -> m a)
-> m a -> m a
handleJust f = flip (catchJust f)
--- | Unlifted 'EUnsafe.try', but will not catch asynchronous exceptions.
+-- | Run the given action and catch any synchronous exceptions as a 'Left'
value.
+--
+-- This is parameterized on the exception type. To catch all synchronous
exceptions,
+-- use 'tryAny'.
--
-- @since 0.1.0.0
try :: (MonadUnliftIO m, Exception e) => m a -> m (Either e a)
@@ -235,7 +245,7 @@
pureTryDeep :: NFData a => a -> Either SomeException a
pureTryDeep = unsafePerformIO . tryAnyDeep . return
--- | Generalized version of 'EUnsafe.Handler'.
+-- | A helper data type for usage with 'catches' and similar functions.
--
-- @since 0.1.0.0
data Handler m a = forall e . Exception e => Handler (e -> m a)
@@ -248,8 +258,10 @@
Just e' -> handler e'
Nothing -> res
--- | Same as upstream 'EUnsafe.catches', but will not catch
--- asynchronous exceptions.
+-- | Similar to 'catch', but provides multiple different handler functions.
+--
+-- For more information on motivation, see @base@'s 'EUnsafe.catches'. Note
that,
+-- unlike that function, this function will not catch asynchronous exceptions.
--
-- @since 0.1.0.0
catches :: MonadUnliftIO m => m a -> [Handler m a] -> m a
@@ -274,7 +286,20 @@
evaluateDeep :: (MonadIO m, NFData a) => a -> m a
evaluateDeep = (evaluate $!!)
--- | Async safe version of 'EUnsafe.bracket'.
+-- | Allocate and clean up a resource safely.
+--
+-- For more information on motivation and usage of this function, see @base@'s
+-- 'EUnsafe.bracket'. This function has two differences from the one in @base@.
+-- The first, and more obvious, is that it works on any @MonadUnliftIO@
+-- instance, not just @IO@.
+--
+-- The more subtle difference is that this function will use uninterruptible
+-- masking for its cleanup handler. This is a subtle distinction, but at a
+-- high level, means that resource cleanup has more guarantees to complete.
+-- This comes at the cost that an incorrectly written cleanup function
+-- cannot be interrupted.
+--
+-- For more information, please see
<https://github.com/fpco/safe-exceptions/issues/3>.
--
-- @since 0.1.0.0
bracket :: MonadUnliftIO m => m a -> (a -> m b) -> (a -> m c) -> m c
@@ -295,13 +320,15 @@
_ <- EUnsafe.uninterruptibleMask_ $ run $ after x
return y
--- | Async safe version of 'EUnsafe.bracket_'.
+-- | Same as 'bracket', but does not pass the acquired resource to cleanup and
use functions.
+--
+-- For more information, see @base@'s 'EUnsafe.bracket_'.
--
-- @since 0.1.0.0
bracket_ :: MonadUnliftIO m => m a -> m b -> m c -> m c
bracket_ before after thing = bracket before (const after) (const thing)
--- | Async safe version of 'EUnsafe.bracketOnError'.
+-- | Same as 'bracket', but only perform the cleanup if an exception is thrown.
--
-- @since 0.1.0.0
bracketOnError :: MonadUnliftIO m => m a -> (a -> m b) -> (a -> m c) -> m c
@@ -323,10 +350,17 @@
bracketOnError_ :: MonadUnliftIO m => m a -> m b -> m c -> m c
bracketOnError_ before after thing = bracketOnError before (const after)
(const thing)
--- | Async safe version of 'EUnsafe.finally'.
+-- | Perform @thing@, guaranteeing that @after@ will run after, even if an
exception occurs.
+--
+-- Same interruptible vs uninterrupible points apply as with 'bracket'. See
@base@'s
+-- 'EUnsafe.finally' for more information.
--
-- @since 0.1.0.0
-finally :: MonadUnliftIO m => m a -> m b -> m a
+finally
+ :: MonadUnliftIO m
+ => m a -- ^ thing
+ -> m b -- ^ after
+ -> m a
finally thing after = withRunInIO $ \run -> EUnsafe.uninterruptibleMask $
\restore -> do
res1 <- EUnsafe.try $ restore $ run thing
case res1 of
@@ -353,7 +387,7 @@
EUnsafe.throwIO e1
Right x -> return x
--- | Async safe version of 'EUnsafe.onException'.
+-- | Like 'finally', but only call @after@ if an exception occurs.
--
-- @since 0.1.0.0
onException :: MonadUnliftIO m => m a -> m b -> m a
@@ -361,6 +395,9 @@
-- | Synchronously throw the given exception.
--
+-- Note that, if you provide an exception value which is of an asynchronous
+-- type, it will be wrapped up in 'SyncExceptionWrapper'. See
'toSyncException'.
+--
-- @since 0.1.0.0
throwIO :: (MonadIO m, Exception e) => e -> m a
throwIO = liftIO . EUnsafe.throwIO . toSyncException
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/unliftio-0.2.13/src/UnliftIO/Internals/Async.hs
new/unliftio-0.2.13.1/src/UnliftIO/Internals/Async.hs
--- old/unliftio-0.2.13/src/UnliftIO/Internals/Async.hs 2020-05-21
10:45:16.000000000 +0200
+++ new/unliftio-0.2.13.1/src/UnliftIO/Internals/Async.hs 2020-10-29
10:02:46.000000000 +0100
@@ -383,8 +383,8 @@
-- | A more efficient alternative to 'Concurrently', which reduces the
-- number of threads that need to be forked. For more information, see
--- @FIXME link to blog post@. This is provided as a separate type to
--- @Concurrently@ as it has a slightly different API.
+-- [this blog
post](https://www.fpcomplete.com/blog/transformations-on-applicative-concurrent-computations/).
+-- This is provided as a separate type to @Concurrently@ as it has a slightly
different API.
--
-- Use the 'conc' function to construct values of type 'Conc', and
-- 'runConc' to execute the composed actions. You can use the
diff -urN '--exclude=CVS' '--exclude=.cvsignore' '--exclude=.svn'
'--exclude=.svnignore' old/unliftio-0.2.13/unliftio.cabal
new/unliftio-0.2.13.1/unliftio.cabal
--- old/unliftio-0.2.13/unliftio.cabal 2020-05-21 10:48:46.000000000 +0200
+++ new/unliftio-0.2.13.1/unliftio.cabal 2020-10-29 11:04:07.000000000
+0100
@@ -4,10 +4,10 @@
--
-- see: https://github.com/sol/hpack
--
--- hash: bc7612e266638a6d07a620579aafe7d2690c4bef6d120416a1a7a3fc8999b416
+-- hash: c11215b81aa0898968a1dbf5189319f0bd07fa70861b5812ac34043c9f118ebb
name: unliftio
-version: 0.2.13
+version: 0.2.13.1
synopsis: The MonadUnliftIO typeclass for unlifting monads to IO
(batteries included)
description: Please see the documentation and README at
<https://www.stackage.org/package/unliftio>
category: Control
