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.
• The first exception thrown by or to a thread created with fork, 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.2.0-inplace" 'False) (C1 ('MetaCons "Thread" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 ThreadId) :*: S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 (STM a))))

Fork

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

Create a thread within a scope.

If the thread throws an exception, the exception is 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 SomeException a))

Create a thread within a scope.

Throws:

• Calls error if the scope is closed.

asyncWithUnmask :: Scope -> (Context => (forall x. IO x -> IO x) -> IO a) -> IO (Thread (Either SomeException 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.

awaitSTM :: Thread a -> STM a

STM variant of await.

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

Variant of await that gives up after the given duration.

Soft-cancellation

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

cancel :: 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.

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.2.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 (or becomes) cancelled.