Bracket laws

Author: natefaubion

src/Control/Monad/Fork/Class.purs

@@ -28,7 +28,16 @@ import Control.Monad.Trans.Class (lift)
 -- | Laws:
 -- |
 -- | ```purescript
+-- | -- Unjoined suspension is a no-op
+-- | suspend a1 *> suspend a2 = suspend a2
+-- |
+-- | -- Suspend/join is identity
 -- | suspend >=> join = id
+-- |
+-- | -- Fork/join is identity
+-- | fork >=> join = id
+-- |
+-- | -- Join is idempotent
 -- | join t *> join t = join t
 -- | ```
 class (Monad m, Functor f) ⇐ MonadFork f m | m → f where
@@ -51,15 +60,11 @@ instance monadForkReaderT ∷ MonadFork f m ⇒ MonadFork f (ReaderT r m) where
 -- | Laws:
 -- |
 -- | ```purescript
--- | (do t <- suspend (throwError e1)
--- |     kill e2 t
--- |     join t)
--- |   = throwError e2
+-- | -- Killed suspension is an exception
+-- | suspend a >>= \f -> kill e f *> join f = throwError e
 -- |
--- | (do t <- fork (pure a)
--- |     kill e2 t
--- |     join t)
--- |   = pure a
+-- | -- Suspend/kill is unit
+-- | suspend a >>= kill e = pure unit
 -- | ```
 class (MonadFork f m, MonadThrow e m) ⇐  MonadKill e f m | m → e f where
   kill ∷ ∀ a. e → f a → m Unit
@@ -77,8 +82,23 @@ data BracketCondition e a
 
 -- | Represents Monads which support cleanup in the presence of async
 -- | exceptions.
+-- |
+-- | Laws:
+-- | ```purescript
+-- | bracket a k \_ -> pure r
+-- |   = uninterruptible (a >>= k (Completed r))
+-- |
+-- | -- Release failed
+-- | bracket a k \_ -> throwError e
+-- |   = uninterruptible (a >>= k (Failed e) *> throwError e)
+-- |
+-- | -- Release killed
+-- | fork (bracket a k \_ -> never) >>= \f -> kill e f *> void (try (join f))
+-- |   = uninterruptible (a >>= k (Killed e))
+-- | ```
 class (MonadKill e f m, MonadError e m) ⇐ MonadBracket e f m | m → e f where
   bracket ∷ ∀ r a. m r → (BracketCondition e a → r → m Unit) → (r → m a) → m a
+  uninterruptible ∷ ∀ a. m a → m a
   never ∷ ∀ a. m a
 
 instance monadBracketAff ∷ MonadBracket Aff.Error (Aff.Fiber eff) (Aff.Aff eff) where
@@ -89,11 +109,14 @@ instance monadBracketAff ∷ MonadBracket Aff.Error (Aff.Fiber eff) (Aff.Aff eff
       , killed: release <<< Killed
       }
       run
+  uninterruptible = Aff.invincible
   never = Aff.never
 
 instance monadBracketReaderT ∷ MonadBracket e f m ⇒ MonadBracket e f (ReaderT r m) where
   bracket (ReaderT acquire) release run = ReaderT \r →
     bracket (acquire r)
       (\c a → runReaderT (release c a) r)
       (\a → runReaderT (run a) r)
+  uninterruptible k = ReaderT \r ->
+    uninterruptible (runReaderT k r)
   never = lift never