Ki.Implicit

Context

type Context = ?context :: Context

A context models a program's call tree, and is used as a mechanism to propagate cancellation requests to every thread created within a scope.

Every thread is provided its own context, which is derived from its scope.

A thread can query whether its context has been cancelled, which is a suggestion to perform a graceful termination.

withGlobalContext :: (Context => IO a) -> IO a

Perform an IO action in the global context. The global context cannot be cancelled.

Scope

data Scope

A scope delimits the lifetime of all threads created within it.

scoped :: Context => (Context => Scope -> IO a) -> IO a

Open a scope, perform an IO action with it, then close the scope.

When the scope is closed, all remaining threads created within it are killed.

Throws:

• The exception thrown by the callback to scoped itself, if any.
• ThreadFailed containing the first exception a thread created with fork throws, if any.

Examples

scoped \scope -> do
  fork_ scope worker1
  fork_ scope worker2
  wait scope

wait :: Scope -> IO ()

Wait until all threads created within a scope finish.

waitSTM :: Scope -> STM ()

STM variant of wait.

waitFor :: Scope -> Duration -> IO ()

Variant of wait that waits for up to the given duration. This is useful for giving threads some time to fulfill a cancellation request before killing them.

Spawning threads

There are two variants of thread-creating functions with different exception-propagation semantics.

• If a thread created with fork throws an exception, it is immediately propagated up the call tree to the thread that created its scope.
• If a thread created with async throws an exception, it is not propagated up the call tree, but can be observed by await.

data Thread a

A running thread.

Instances

Functor Thread

Defined in Ki.Thread

Methods

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

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

Eq (Thread a)

Defined in Ki.Thread

Methods

(==) :: Thread a -> Thread a -> Bool

(/=) :: Thread a -> Thread a -> Bool

Ord (Thread a)

Defined in Ki.Thread

Methods

compare :: Thread a -> Thread a -> Ordering

(<) :: Thread a -> Thread a -> Bool

(<=) :: Thread a -> Thread a -> Bool

(>) :: Thread a -> Thread a -> Bool

(>=) :: Thread a -> Thread a -> Bool

max :: Thread a -> Thread a -> Thread a

min :: Thread a -> Thread a -> Thread a

Generic (Thread a)

Defined in Ki.Thread

Associated Types

type Rep (Thread a) :: Type -> Type

Methods

from :: Thread a -> Rep (Thread a) x

to :: Rep (Thread a) x -> Thread a

type Rep (Thread a)

Defined in Ki.Thread

type Rep (Thread a) = D1 ('MetaData "Thread" "Ki.Thread" "ki-0-inplace" 'False) (C1 ('MetaCons "Thread" 'PrefixI 'True) (S1 ('MetaSel ('Just "threadId") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 ThreadId) :*: S1 ('MetaSel ('Just "action") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 (STM a))))

Fork

fork :: Scope -> (Context => IO a) -> IO (Thread a)

Create a thread within a scope to compute a value concurrently.

If the thread throws an exception, the exception is wrapped in ThreadFailed and immediately propagated up the call tree to the thread that opened its scope, unless that exception is a CancelToken that fulfills a cancellation request.

Throws:

• Calls error if the scope is closed.

fork_ :: Scope -> (Context => IO ()) -> IO ()

Variant of fork that does not return a handle to the created thread.

Throws:

• Calls error if the scope is closed.

forkWithUnmask :: Scope -> (Context => (forall x. IO x -> IO x) -> IO a) -> IO (Thread a)

Variant of fork that provides the thread a function that unmasks asynchronous exceptions.

Throws:

• Calls error if the scope is closed.

forkWithUnmask_ :: Scope -> (Context => (forall x. IO x -> IO x) -> IO ()) -> IO ()

Variant of forkWithUnmask that does not return a handle to the created thread.

Throws:

• Calls error if the scope is closed.

Async

async :: Scope -> (Context => IO a) -> IO (Thread (Either ThreadFailed a))

Create a thread within a scope to compute a value concurrently.

Throws:

• Calls error if the scope is closed.

asyncWithUnmask :: Scope -> (Context => (forall x. IO x -> IO x) -> IO a) -> IO (Thread (Either ThreadFailed a))

Variant of async that provides the thread a function that unmasks asynchronous exceptions.

Throws:

• Calls error if the scope is closed.

Await

await :: Thread a -> IO a

Wait for a thread to finish.

Throws:

• ThreadFailed if the thread threw an exception and was created with fork.

awaitSTM :: Thread a -> STM a

STM variant of await.

Throws:

• ThreadFailed if the thread threw an exception and was created with fork.

awaitFor :: Thread a -> Duration -> IO (Maybe a)

Variant of await that waits for up to the given duration.

Throws:

• ThreadFailed if the thread threw an exception and was created with fork.

Soft-cancellation

cancelScope :: Scope -> IO ()

Cancel all contexts derived from a scope.

cancelled :: Context => IO (Maybe CancelToken)

Return whether the current context is cancelled.

Threads running in a cancelled context should terminate as soon as possible. The cancel token may be thrown to fulfill the cancellation request in case the thread is unable or unwilling to terminate normally with a value.

cancelledSTM :: Context => STM CancelToken

STM variant of cancelled; blocks until the current context is cancelled.

data CancelToken

A cancel token represents a request for cancellation; this request can be fulfilled by throwing the token as an exception.

Instances

Eq CancelToken

Defined in Ki.CancelToken

Methods

(==) :: CancelToken -> CancelToken -> Bool

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

Show CancelToken

Defined in Ki.CancelToken

Methods

showsPrec :: Int -> CancelToken -> ShowS

show :: CancelToken -> String

showList :: [CancelToken] -> ShowS

Exception CancelToken

Defined in Ki.CancelToken

Methods

toException :: CancelToken -> SomeException

fromException :: SomeException -> Maybe CancelToken

displayException :: CancelToken -> String

Miscellaneous

data Duration

A length of time with microsecond precision. Numeric literals are treated as seconds.

Instances

Enum Duration

Defined in Ki.Duration

Methods

succ :: Duration -> Duration

pred :: Duration -> Duration

toEnum :: Int -> Duration

fromEnum :: Duration -> Int

enumFrom :: Duration -> [Duration]

enumFromThen :: Duration -> Duration -> [Duration]

enumFromTo :: Duration -> Duration -> [Duration]

enumFromThenTo :: Duration -> Duration -> Duration -> [Duration]

Eq Duration

Defined in Ki.Duration

Methods

(==) :: Duration -> Duration -> Bool

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

Fractional Duration

Defined in Ki.Duration

Methods

(/) :: Duration -> Duration -> Duration

recip :: Duration -> Duration

fromRational :: Rational -> Duration

Data Duration

Defined in Ki.Duration

Methods

gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> Duration -> c Duration

gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c Duration

toConstr :: Duration -> Constr

dataTypeOf :: Duration -> DataType

dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c Duration)

dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c Duration)

gmapT :: (forall b. Data b => b -> b) -> Duration -> Duration

gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> Duration -> r

gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> Duration -> r

gmapQ :: (forall d. Data d => d -> u) -> Duration -> [u]

gmapQi :: Int -> (forall d. Data d => d -> u) -> Duration -> u

gmapM :: Monad m => (forall d. Data d => d -> m d) -> Duration -> m Duration

gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> Duration -> m Duration

gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> Duration -> m Duration

Num Duration

Defined in Ki.Duration

Methods

(+) :: Duration -> Duration -> Duration

(-) :: Duration -> Duration -> Duration

(*) :: Duration -> Duration -> Duration

negate :: Duration -> Duration

abs :: Duration -> Duration

signum :: Duration -> Duration

fromInteger :: Integer -> Duration

Ord Duration

Defined in Ki.Duration

Methods

compare :: Duration -> Duration -> Ordering

(<) :: Duration -> Duration -> Bool

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

(>) :: Duration -> Duration -> Bool

(>=) :: Duration -> Duration -> Bool

max :: Duration -> Duration -> Duration

min :: Duration -> Duration -> Duration

Read Duration

Defined in Ki.Duration

Methods

readsPrec :: Int -> ReadS Duration

readList :: ReadS [Duration]

readPrec :: ReadPrec Duration

readListPrec :: ReadPrec [Duration]

Real Duration

Defined in Ki.Duration

Methods

toRational :: Duration -> Rational

RealFrac Duration

Defined in Ki.Duration

Methods

properFraction :: Integral b => Duration -> (b, Duration)

truncate :: Integral b => Duration -> b

round :: Integral b => Duration -> b

ceiling :: Integral b => Duration -> b

floor :: Integral b => Duration -> b

Show Duration

Defined in Ki.Duration

Methods

showsPrec :: Int -> Duration -> ShowS

show :: Duration -> String

showList :: [Duration] -> ShowS

Generic Duration

Defined in Ki.Duration

Associated Types

type Rep Duration :: Type -> Type

Methods

from :: Duration -> Rep Duration x

to :: Rep Duration x -> Duration

type Rep Duration

Defined in Ki.Duration

type Rep Duration = D1 ('MetaData "Duration" "Ki.Duration" "ki-0-inplace" 'True) (C1 ('MetaCons "Duration" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Fixed E6))))

microseconds :: Duration

One microsecond.

milliseconds :: Duration

One millisecond.

seconds :: Duration

One second.

timeoutSTM :: Duration -> STM (IO a) -> IO a -> IO a

Wait for an STM action to return an IO action, or if the given duration elapses, return the given IO action instead.

sleep :: Context => Duration -> IO ()

Context-aware, duration-based threadDelay.

Throws:

• Throws CancelToken if the current context is cancelled.

Exceptions

data ThreadFailed

A thread failed, either by throwing or being thrown an exception.

Constructors

ThreadFailed

Fields

• threadId :: ThreadId
• exception :: SomeException

Instances

Show ThreadFailed

Defined in Ki.ThreadFailed

Methods

showsPrec :: Int -> ThreadFailed -> ShowS

show :: ThreadFailed -> String

showList :: [ThreadFailed] -> ShowS

Exception ThreadFailed

Defined in Ki.ThreadFailed

Methods

toException :: ThreadFailed -> SomeException

fromException :: SomeException -> Maybe ThreadFailed

displayException :: ThreadFailed -> String