Lifetimes

This package is centered around a couple types:

• Acquire is a monadic context in which resources can be acquired. These can be executed using acquire, or for simpler cases withAcquire or acquireValue.
• Resource is a handle to a resource. The value for the resource can be read from this, and the Resource can also be used to manipulate the resource's lifetime.
• Liftime is the type of first-class liftimes; resources are attached to these and can be moved between them.

Lifetimes

data Lifetime

A Lifetime is a represents the scope in which a Resource is valid; resources are attached to a lifetime when they are acquired, and will be released when the lifetime ends.

newLifetime :: Acquire Lifetime

Acquire a new lifetime, as its own resource. This allows creating sub-groups of resources, which can be later moved as a unit.

withLifetime :: (Lifetime -> IO a) -> IO a

Execute an IO action within the scope of a newly allocated lifetime, which ends when the IO action completes.

Acquiring resources

data Acquire a

An Acquire is a monadic action that acquires some number of resources, and registers cleanup handlers to be executed when their lifetime expires.

Instances

Monad Acquire

Defined in Lifetimes

Methods

(>>=) :: Acquire a -> (a -> Acquire b) -> Acquire b

(>>) :: Acquire a -> Acquire b -> Acquire b

return :: a -> Acquire a

Functor Acquire

Defined in Lifetimes

Methods

fmap :: (a -> b) -> Acquire a -> Acquire b

(<$) :: a -> Acquire b -> Acquire a

Applicative Acquire

Defined in Lifetimes

Methods

pure :: a -> Acquire a

(<*>) :: Acquire (a -> b) -> Acquire a -> Acquire b

liftA2 :: (a -> b -> c) -> Acquire a -> Acquire b -> Acquire c

(*>) :: Acquire a -> Acquire b -> Acquire b

(<*) :: Acquire a -> Acquire b -> Acquire a

MonadIO Acquire

Defined in Lifetimes

Methods

liftIO :: IO a -> Acquire a

mkAcquire :: IO a -> (a -> IO ()) -> Acquire a

mkAcquire get cleanup acquires a resource with get, which will be released by calling cleanup when its lifetime ends.

withAcquire :: Acquire a -> (a -> IO b) -> IO b

withAcquire acuires a resource, uses it, and then releases it. withAcquire (mkAcquire get cleanup) is equivalent to bracket get cleanup.

acquire :: Lifetime -> Acquire a -> IO (Resource a)

Acquire a resource, attaching it to the supplied lifetime.

acquireValue :: Lifetime -> Acquire a -> IO a

Like acquire, but returns the value, rather than a Resource wrapper. conveinent when you don't need to move the resource or release it before the lifetime expires.

currentLifetime :: Acquire Lifetime

Get the lifetime for the resources being acquired.

Using resources

data Resource a

Represents a resource with type a, which has a lifetime and an associated cleanup handler.

getResource :: MonadSTM m => Resource a -> m (Maybe a)

Get the value associated with a resource, returning Nothing if the resource's lifetime is expired.

mustGetResource :: MonadSTM m => Resource a -> m a

Like getResource, but throws a ResourceExpired exception instead of returning a Maybe.

Releasing resources

releaseEarly :: Resource a -> IO ()

Release a resource early, before its lifetime would otherwise end.

detach :: MonadSTM m => Resource a -> m (IO ())

Detach the resource from its lifetime, returning the cleanup handler. NOTE: if the caller does not otherwise arrange to run the cleanup handler, it will *not* be executed.

Move semantics

moveTo :: MonadSTM m => Resource a -> Lifetime -> m ()

Move a resource to another lifetime. The resource will be detached from its existing lifetime, and so may live past it, but will be released when the new lifetime expires.

Errors

data ResourceExpired

Error thrown when an attempt is made to use an expired resource or lifetime.

Constructors

ResourceExpired

Instances

Eq ResourceExpired

Defined in Lifetimes

Methods

(==) :: ResourceExpired -> ResourceExpired -> Bool

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

Ord ResourceExpired

Defined in Lifetimes

Methods

compare :: ResourceExpired -> ResourceExpired -> Ordering

(<) :: ResourceExpired -> ResourceExpired -> Bool

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

(>) :: ResourceExpired -> ResourceExpired -> Bool

(>=) :: ResourceExpired -> ResourceExpired -> Bool

max :: ResourceExpired -> ResourceExpired -> ResourceExpired

min :: ResourceExpired -> ResourceExpired -> ResourceExpired

Read ResourceExpired

Defined in Lifetimes

Methods

readsPrec :: Int -> ReadS ResourceExpired

readList :: ReadS [ResourceExpired]

readPrec :: ReadPrec ResourceExpired

readListPrec :: ReadPrec [ResourceExpired]

Show ResourceExpired

Defined in Lifetimes

Methods

showsPrec :: Int -> ResourceExpired -> ShowS

show :: ResourceExpired -> String

showList :: [ResourceExpired] -> ShowS

Exception ResourceExpired

Defined in Lifetimes

Methods

toException :: ResourceExpired -> SomeException

fromException :: SomeException -> Maybe ResourceExpired

displayException :: ResourceExpired -> String