-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | A lightweight structured concurrency library
--
-- A lightweight structured concurrency library.
--
-- For a variant of this API generalized to
-- MonadUnliftIO, see ki-unlifted.
--
-- Remember to link your program with -threaded to use the
-- threaded runtime!
@package ki
@version 1.0.0
-- | ki is a lightweight structured concurrency library.
--
-- For a variant of this API generalized to
-- MonadUnliftIO, see ki-unlifted.
--
-- Remember to link your program with -threaded to use the
-- threaded runtime!
module Ki
-- | A scope.
--
-- 👉 Details
--
--
-- - A scope delimits the lifetime of all threads created within
-- it.
--
--
--
-- - A scope is only valid during the callback provided to
-- scoped.
-- - The thread that creates a scope is considered the parent of all
-- threads created within it.
-- - All threads created within a scope can be awaited together (see
-- awaitAll).
-- - All threads created within a scope are terminated when the scope
-- closes.
--
data Scope
-- | A thread.
--
-- 👉 Details
--
--
-- - A thread's lifetime is delimited by the scope in which it was
-- created.
--
--
--
-- - The thread that creates a scope is considered the parent of all
-- threads created within it.
-- - If an exception is raised in a child thread, the child either
-- propagates the exception to its parent (see fork), or returns
-- the exception as a value (see forkTry).
-- - All threads created within a scope are terminated when the scope
-- closes.
--
data Thread a
-- | Open a scope, perform an IO action with it, then close the scope.
--
-- 👉 Details
--
--
-- - The thread that creates a scope is considered the parent of all
-- threads created within it.
--
--
--
-- - A scope is only valid during the callback provided to
-- scoped.
-- - When a scope closes (i.e. just before scoped
-- returns):
- The parent thread raises an exception in all of its
-- living children.
- The parent thread blocks until those threads
-- terminate.
--
scoped :: (Scope -> IO a) -> IO a
-- | Create a child thread to execute an action within a scope.
--
-- Note: The child thread does not mask asynchronous exceptions,
-- regardless of the parent thread's masking state. To create a child
-- thread with a different initial masking state, use forkWith.
fork :: Scope -> IO a -> IO (Thread a)
-- | Like fork, but the child thread does not propagate exceptions
-- that are both:
--
--
forkTry :: forall e a. Exception e => Scope -> IO a -> IO (Thread (Either e a))
-- | Wait for a thread to terminate.
await :: Thread a -> STM a
-- | Wait until all threads created within a scope terminate.
awaitAll :: Scope -> STM ()
-- | Variant of fork for threads that never return.
fork_ :: Scope -> IO Void -> IO ()
-- | Variant of fork that takes an additional options argument.
forkWith :: Scope -> ThreadOptions -> IO a -> IO (Thread a)
-- | Variant of forkWith for threads that never return.
forkWith_ :: Scope -> ThreadOptions -> IO Void -> IO ()
-- | Variant of forkTry that takes an additional options argument.
forkTryWith :: forall e a. Exception e => Scope -> ThreadOptions -> IO a -> IO (Thread (Either e a))
-- |
-- - affinity The affinity of a thread. A thread can be
-- unbound, bound to a specific capability, or bound to a specific OS
-- thread.Default: Unbound
-- - allocationLimit The maximum number of bytes a
-- thread may allocate before it is delivered an
-- AllocationLimitExceeded exception. If caught, the thread is
-- allowed to allocate an additional 100kb (tunable with +RTS
-- -xq) to perform any necessary cleanup actions; if exceeded, the
-- thread is delivered another.Default: Nothing (no limit)
-- - label The label of a thread, visible in the
-- event log (+RTS -l).Default: "" (no
-- label)
-- - maskingState The masking state a thread is created
-- in. To unmask, use unsafeUnmask.Default: Unmasked
--
data ThreadOptions
ThreadOptions :: ThreadAffinity -> Maybe ByteCount -> String -> MaskingState -> ThreadOptions
[$sel:affinity:ThreadOptions] :: ThreadOptions -> ThreadAffinity
[$sel:allocationLimit:ThreadOptions] :: ThreadOptions -> Maybe ByteCount
[$sel:label:ThreadOptions] :: ThreadOptions -> String
[$sel:maskingState:ThreadOptions] :: ThreadOptions -> MaskingState
-- | Default thread options.
--
--
-- ThreadOptions
-- { affinity = Nothing
-- , allocationLimit = Nothing
-- , label = ""
-- , maskingState = Unmasked
-- }
--
defaultThreadOptions :: ThreadOptions
-- | What, if anything, a thread is bound to.
data ThreadAffinity
-- | Unbound.
Unbound :: ThreadAffinity
-- | Bound to a capability.
Capability :: Int -> ThreadAffinity
-- | Bound to an OS thread.
OsThread :: ThreadAffinity
-- | A number of bytes.
data ByteCount
-- | A number of kilobytes.
kilobytes :: Natural -> ByteCount
-- | A number of megabytes.
megabytes :: Natural -> ByteCount