Control.Monad.Scoped

The Scoped monad to safely allocate and deallocate resources.

Scoped computations and ScopedResources

data Scoped (s :: [Type]) (m :: k -> TYPE rep) a

The Scoped monad that provides the possibility to safely scope the allocation of a resource

It is used to abstract over all of the CPS style withSomething functions, like withFile

Be sure to properly mask handlers if you are using UnsafeMkScoped. Use safe helper functions like registerHandler or bracketScoped where possible.

Scoped also works for wrapping unboxed and unlifted monad transformers.

Instances

Monad m => Scoping (s ': ss) (m :: Type -> Type) (Scoped (s ': ss) m)

Defined in Control.Monad.Scoped.Internal

Methods

scoped :: (forall s0. Scoped (s0 ': (s ': ss)) m a) -> Scoped (s ': ss) m a

MonadTrans (Scoped s :: (Type -> Type) -> Type -> Type)

You can use all the actions you can use in the underlying monad m also in the Scoped monad by lifting into it.

Defined in Control.Monad.Scoped.Internal

Methods

lift :: Monad m => m a -> Scoped s m a

(MonadIO m', m' ~~ m) => MonadIO (Scoped s m)

You can perform IO in a scoped block, but it does not inherit its safety guarantees

Defined in Control.Monad.Scoped.Internal

Methods

liftIO :: IO a -> Scoped s m a

(Alternative m', m' ~~ m) => Alternative (Scoped s m)

Defined in Control.Monad.Scoped.Internal

Methods

empty :: Scoped s m a

(<|>) :: Scoped s m a -> Scoped s m a -> Scoped s m a

some :: Scoped s m a -> Scoped s m [a]

many :: Scoped s m a -> Scoped s m [a]

Applicative (Scoped s m)

Defined in Control.Monad.Scoped.Internal

Methods

pure :: a -> Scoped s m a

(<*>) :: Scoped s m (a -> b) -> Scoped s m a -> Scoped s m b

liftA2 :: (a -> b -> c) -> Scoped s m a -> Scoped s m b -> Scoped s m c

(*>) :: Scoped s m a -> Scoped s m b -> Scoped s m b

(<*) :: Scoped s m a -> Scoped s m b -> Scoped s m a

Functor (Scoped s m)

Defined in Control.Monad.Scoped.Internal

Methods

fmap :: (a -> b) -> Scoped s m a -> Scoped s m b

(<$) :: a -> Scoped s m b -> Scoped s m a

Monad (Scoped s m)

Defined in Control.Monad.Scoped.Internal

Methods

(>>=) :: Scoped s m a -> (a -> Scoped s m b) -> Scoped s m b

(>>) :: Scoped s m a -> Scoped s m b -> Scoped s m b

return :: a -> Scoped s m a

(Alternative m', m' ~~ m) => MonadPlus (Scoped s m)

Defined in Control.Monad.Scoped.Internal

Methods

mzero :: Scoped s m a

mplus :: Scoped s m a -> Scoped s m a -> Scoped s m a

(MonadFail m', m' ~~ m) => MonadFail (Scoped s m)

You can fail in a Scoped block

Defined in Control.Monad.Scoped.Internal

Methods

fail :: String -> Scoped s m a

data ScopedResource s a

A scoped resource with token s belonging to a Scoped block with the same token.

If you are creating a ScopedResource, make sure the resource is deallocated properly when the Scoped block is exited.

Instances

Show a => Show (ScopedResource s a)

Defined in Control.Monad.Scoped.Internal

Methods

showsPrec :: Int -> ScopedResource s a -> ShowS

show :: ScopedResource s a -> String

showList :: [ScopedResource s a] -> ShowS

Eq a => Eq (ScopedResource s a)

Defined in Control.Monad.Scoped.Internal

Methods

(==) :: ScopedResource s a -> ScopedResource s a -> Bool

(/=) :: ScopedResource s a -> ScopedResource s a -> Bool

Ord a => Ord (ScopedResource s a)

Defined in Control.Monad.Scoped.Internal

Methods

compare :: ScopedResource s a -> ScopedResource s a -> Ordering

(<) :: ScopedResource s a -> ScopedResource s a -> Bool

(<=) :: ScopedResource s a -> ScopedResource s a -> Bool

(>) :: ScopedResource s a -> ScopedResource s a -> Bool

(>=) :: ScopedResource s a -> ScopedResource s a -> Bool

max :: ScopedResource s a -> ScopedResource s a -> ScopedResource s a

min :: ScopedResource s a -> ScopedResource s a -> ScopedResource s a

Safely work with scopes

scoped :: Scoping ss m n => (forall s. Scoped (s ': ss) m a) -> n a

Run a Scoped block safely, making sure that none of the safely allocated resources can escape it, using the same trick as ST

All of the allocated resources will live until the end of the block is reached

registerHandler

Arguments

:: forall m a (ss :: [Type]). MonadUnliftIO m

=> m a

the handler to be registered

-> Scoped ss m ()

Run a handler masked for async exception when the Scoped block ends

You can register a handler wherever in your Scoped block you want, but it will nonetheless be run in reverse order that the handlers have been registered, after the scoped block's actions have been finished

class s :< (ss :: [Type])

when using a resource, all that matters is that the resource can only be used in the scope that it was created in or any scope that is farther in than that scope

This constraint has to be put to connect the resource and the scope that it was created in

Instances

s :< (s ': (s'' ': ss))

Defined in Control.Monad.Scoped.Internal

s :< '[s]

Defined in Control.Monad.Scoped.Internal

s :< (s'' ': ss) => s :< (s' ': (s'' ': ss))

Defined in Control.Monad.Scoped.Internal

Safely work with Asyncs

type ScopedAsync s a = ScopedResource s (Async a)

Just like Async but bound to a Scoped block

async :: forall m a s (ss :: [Type]). MonadUnliftIO m => m a -> Scoped (s ': ss) m (ScopedAsync s a)

Run an IO action asynchronously in a Scoped block. When the Scoped block ends, the Async is cancelled

asyncBound :: forall m a s (ss :: [Type]). MonadUnliftIO m => m a -> Scoped (s ': ss) m (ScopedAsync s a)

Like async but uses forkOS internally

wait :: forall (m :: Type -> Type) s (ss :: [Type]) a. (MonadIO m, s :< ss) => ScopedAsync s a -> Scoped ss m a

Wait for the ScopedAsync to finish immediately

waitCatch :: forall (m :: Type -> Type) s (ss :: [Type]) a. (MonadIO m, s :< ss) => ScopedAsync s a -> Scoped ss m (Either SomeException a)

Like wait but return either Left SomeException or Right a

waitScoped :: forall (m :: Type -> Type) s (ss :: [Type]) a. (MonadUnliftIO m, s :< ss) => ScopedAsync s a -> Scoped ss m ()

Like wait but wait as part of the handlers of the Scoped block

waitCatchScoped :: forall (m :: Type -> Type) s (ss :: [Type]) a. (MonadUnliftIO m, s :< ss) => ScopedAsync s a -> Scoped ss m ()

Like waitCatch but wait as part of the handlers of the Scoped block

Safely work with Handles

type ScopedHandle s = ScopedResource s Handle

Just like Handle but bound to a Scoped block

file :: forall (m :: Type -> Type) s (ss :: [Type]). MonadUnliftIO m => FilePath -> IOMode -> Scoped (s ': ss) m (ScopedHandle s)

Given a FilePath, safely allocates and deallocates a ScopedHandle in a Scoped block

data IOMode

See openFile

Constructors

ReadMode

WriteMode

AppendMode

ReadWriteMode

Instances

Enum IOMode

@since base-4.2.0.0

Defined in GHC.Internal.IO.IOMode

Methods

succ :: IOMode -> IOMode

pred :: IOMode -> IOMode

toEnum :: Int -> IOMode

fromEnum :: IOMode -> Int

enumFrom :: IOMode -> [IOMode]

enumFromThen :: IOMode -> IOMode -> [IOMode]

enumFromTo :: IOMode -> IOMode -> [IOMode]

enumFromThenTo :: IOMode -> IOMode -> IOMode -> [IOMode]

Ix IOMode

@since base-4.2.0.0

Defined in GHC.Internal.IO.IOMode

Methods

range :: (IOMode, IOMode) -> [IOMode]

index :: (IOMode, IOMode) -> IOMode -> Int

unsafeIndex :: (IOMode, IOMode) -> IOMode -> Int

inRange :: (IOMode, IOMode) -> IOMode -> Bool

rangeSize :: (IOMode, IOMode) -> Int

unsafeRangeSize :: (IOMode, IOMode) -> Int

Read IOMode

@since base-4.2.0.0

Defined in GHC.Internal.IO.IOMode

Methods

readsPrec :: Int -> ReadS IOMode

readList :: ReadS [IOMode]

readPrec :: ReadPrec IOMode

readListPrec :: ReadPrec [IOMode]

Show IOMode

@since base-4.2.0.0

Defined in GHC.Internal.IO.IOMode

Methods

showsPrec :: Int -> IOMode -> ShowS

show :: IOMode -> String

showList :: [IOMode] -> ShowS

Eq IOMode

@since base-4.2.0.0

Defined in GHC.Internal.IO.IOMode

Methods

(==) :: IOMode -> IOMode -> Bool

(/=) :: IOMode -> IOMode -> Bool

Ord IOMode

@since base-4.2.0.0

Defined in GHC.Internal.IO.IOMode

Methods

compare :: IOMode -> IOMode -> Ordering

(<) :: IOMode -> IOMode -> Bool

(<=) :: IOMode -> IOMode -> Bool

(>) :: IOMode -> IOMode -> Bool

(>=) :: IOMode -> IOMode -> Bool

max :: IOMode -> IOMode -> IOMode

min :: IOMode -> IOMode -> IOMode

hPutStrLn :: forall (m :: Type -> Type) s (ss :: [Type]). (MonadIO m, s :< ss) => ScopedHandle s -> Text -> Scoped ss m ()

Like hPutStrLn but for ScopedHandle

hPutStr :: forall (m :: Type -> Type) s (ss :: [Type]). (MonadIO m, s :< ss) => ScopedHandle s -> Text -> Scoped ss m ()

Like hPutStr but for ScopedHandle

hGetLine :: forall (m :: Type -> Type) s (ss :: [Type]). (MonadIO m, s :< ss) => ScopedHandle s -> Scoped ss m Text

Like hGetLine but for ScopedHandle

hGetContents :: forall (m :: Type -> Type) s (ss :: [Type]). (MonadIO m, s :< ss) => ScopedHandle s -> Scoped ss m Text

Like hGetContents but for ScopedHandle

Safely work with tempfiles

tempFile :: forall (m :: Type -> Type) s (ss :: [Type]). MonadUnliftIO m => FilePath -> String -> Scoped (s ': ss) m (FilePath, ScopedHandle s)

Like withTempFile but for Scoped

systemTempFile :: forall (m :: Type -> Type) s (ss :: [Type]). MonadUnliftIO m => String -> Scoped (s ': ss) m (FilePath, ScopedHandle s)

Like withSystemTempFile but for Scoped

Safely work with Ptrs

type Ptr s a = ScopedResource s (Ptr a)

A Ptr that is associated to a scope but it is mutable (can be read from and written to)

mut :: forall a (m :: Type -> Type) s (ss :: [Type]). (Storable a, MonadUnliftIO m) => a -> Scoped (s ': ss) m (Ptr s a)

Acquire mutable memory for the duration of a scope. The value is automatically dropped at the end of the scope.

(.=) :: forall a (m :: Type -> Type) s (ss :: [Type]). (Storable a, MonadIO m, s :< ss) => Ptr s a -> a -> Scoped ss m ()

write a value to a pointer

(?) :: forall a (m :: Type -> Type) s (ss :: [Type]). (Storable a, MonadIO m, s :< ss) => Ptr s a -> Scoped ss m a

read a value from a pointer