-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Orchestration-style co-ordination EDSL
--
-- Provides an EDSL with Orc primitives.
@package orc
@version 1.2.1.3
-- | Hierarchical concurrent threads, which kill all of their descendants
-- when they are killed.
module Control.Concurrent.Hierarchical
-- | The HIO monad is simply the IO monad augmented with an
-- environment that tracks the current thread Group. This permits
-- us to keep track of forked threads and kill them en mass when an
-- ancestor is killed. The HIO monad is an instance of
-- MonadIO, so arbitrary IO actions may be embedded in it;
-- however, the user is advised that any action may be summarily killed,
-- and thus it is of extra importance that appropriate bracketing
-- functions are used.
data HIO a
-- | Runs a HIO operation inside a new thread group that has no
-- parent, and blocks until all subthreads of the operation are done
-- executing. If countingThreads is True, it then
-- prints some debugging information about the threads run (XXX: this
-- seems suboptimal.)
runHIO :: HIO b -> IO ()
-- | Creates a new, empty thread group.
newPrimGroup :: IO Group
-- | Creates a new thread group and registers the current environment's
-- thread group in it. If the current group is closed, immediately
-- terminates execution of the current thread.
newGroup :: HIO Group
-- | Explicitly sets the current Group environment for a HIO
-- monad.
local :: Group -> HIO a -> HIO a
-- | Kill all threads which are descendants of a Group and closes
-- the group, disallowing new threads or groups to be added to the group.
-- Doesn't do anything if the group is already closed.
close :: Group -> HIO ()
-- | A thread Group keeps tracks of its inhabitants, which may be
-- threads or other Groups.
type Group = (TVar Int, TVar Inhabitants)
-- | Blocks until the Group w is finished executing.
finished :: Group -> HIO ()
instance HasFork HIO
instance MonadIO HIO
instance Applicative HIO
instance Monad HIO
instance Functor HIO
-- | Primitive combinators for the Orc EDSL in Haskell.
module Orc.Monad
-- | A monad for many-valued concurrency, external actions and managed
-- resources. An expression of type Orc a may perform many
-- actions and return many results of type a. The
-- MonadPlus instance does not obey the Right-Zero law (p
-- >> stop /= stop).
data Orc a
-- | Finish the local thread of operations, so that anything sequenced
-- afterwards is not executed. It satisfies the following law: stop
-- >>= k == stop
stop :: Orc a
-- | Immediately fires up a thread for p, and then returns a
-- handle to the first result of that thread which is also of type
-- Orc a. An invocation to eagerly is non-blocking, while
-- an invocation of the resulting handle is blocking. eagerly
-- satisfies the following laws:
--
-- Par-eagerly:
--
--
-- eagerly p >>= (\x -> k x <|> h)
-- == (eagerly p >>= k) <|> h
--
--
-- Eagerly-swap:
--
--
-- do y <- eagerly p
-- x <- eagerly q
-- k x y
-- == do x <- eagerly q
-- y <- eagerly p
-- k x y
--
--
-- Eagerly-IO:
--
--
-- eagerly (liftIO m) >> p == (liftIO m >> stop) <|> p
--
eagerly :: Orc a -> Orc (Orc a)
-- | An alternate mechanism for eagerly, it fires up a thread for
-- p and returns a lazy thunk that contains the single (trimmed)
-- result of the computation. Be careful to use this function with
-- publish when these lazy values need to be fully evaluated
-- before proceeding further. For example, the following code succeeds
-- immediately:
--
--
-- do x <- val p
-- return x
--
--
-- Whereas this code waits until p has generated one result
-- before returning:
--
--
-- do x <- val p
-- publish p
--
val :: Orc a -> Orc a
-- | Biased choice operator (pronounced and-then) that performs the action
-- (and returns all the results) of p first, and then once done
-- performs the action of q.
(<+>) :: Orc a -> Orc a -> Orc a
-- | Runs an Orc computation, discarding the (many) results of the
-- computation. See collect on a mechanism for collecting the
-- results of a computation into a list, which may then be passed to
-- another IO thread.
runOrc :: Orc a -> IO ()
instance MonadPlus Orc
instance Applicative Orc
instance MonadIO Orc
instance Alternative Orc
instance Monad Orc
instance Functor Orc
module Orc.Combinators
-- | Alternate phrasing of return (), which can be placed at the
-- end of an Orc computation to signal that it has no more values to
-- produce.
signal :: Orc ()
-- | Cut executes an orc expression, waits for the first result, and then
-- suppresses the rest, including killing any threads involved in
-- computing the remainder.
cut :: Orc a -> Orc a
-- | Executes the computation p and done. Once
-- done returns its first result, kill both computations and
-- returns that result. This discards the results of p.
onlyUntil :: Orc a -> Orc b -> Orc b
-- | Immediately executes the computation p, but if it hasn't
-- returned a result in t seconds, execute the computation
-- q and return whichever computations returns a result first
-- (killing the other thread).
butAfter :: Orc a -> (Float, Orc a) -> Orc a
-- | Executes a computation p, but if it hasn't returned a result
-- in n seconds return a instead (killing the
-- p computation).
timeout :: Float -> a -> Orc a -> Orc a
-- | Executes the computation p but suppresses its results.
silent :: Orc a -> Orc b
-- | Lifts a list into an Orc monad.
liftList :: MonadPlus list => [a] -> list a
-- | Repeatedly executes the computation p and returns its
-- results. repeating works best when p is single-valued:
-- if p is multivalued Orc will spawn a repeating thread for
-- every result returned, resulting in an exponential blow-up of threads
-- (XXX: I don't think this was actually intended.)
repeating :: Orc a -> Orc a
-- | Runs a computation p and writes its results to the channel
-- ch.
runChan :: Chan a -> Orc a -> IO ()
-- | Takes the first result of p, the first result of q,
-- and applies them to f. The computations for p and
-- q are run in parallel.
sync :: (a -> b -> c) -> Orc a -> Orc b -> Orc c
-- | Runs the computation p and returns its first result, but
-- doesn't return before w seconds have elapsed.
notBefore :: Orc a -> Float -> Orc a
-- | Runs a list of Orc computations ps in parallel until they
-- produce their first result, and returns a list of all these results.
syncList :: [Orc a] -> Orc [a]
-- | Wait for a period of w seconds, then continue processing.
delay :: (RealFrac a, Show a) => a -> Orc ()
-- | Runs an Orc computation, eagerly printing out the results of an Orc
-- computation line-by-line.
printOrc :: Show a => Orc a -> IO ()
-- | Prompts the user for a string. Concurrency-safe.
prompt :: String -> Orc String
-- | Writes a string and newline to standard output. Concurrency-safe.
putStrLine :: String -> Orc ()
-- | Analogous to the list scan function, but the order in which the
-- combining function is applied to the results produced by p is
-- nondeterministic.
scan :: (a -> s -> s) -> s -> Orc a -> Orc s
-- | A variant of <+>, pronounced or-else, which performs and
-- returns the results of p, and if p produced no
-- answers go on and performa dn return the results of q.
() :: Orc a -> Orc a -> Orc a
-- | For each value produced by p, return a Left a. Once
-- p has finished, return a Right Int containing the
-- number of results produced.
count :: Orc a -> Orc (Either a Int)
-- | Collects all of the values of the computation p and delivers
-- them as a list when p is completed.
collect :: Orc a -> Orc [a]
-- | List-like functions
--
-- Runs the computation p and returns the first n
-- results.
takeOrc :: Int -> Orc a -> Orc a
-- | Drops the first n results of the computation p, and
-- then returns the rest of the results.
dropOrc :: Int -> Orc a -> Orc a
-- | Zips the results of two computations p and q. When
-- one computation finishes, kill the other.
zipOrc :: Orc a -> Orc b -> Orc (a, b)
-- | Runs the computation p, and repeatedly puts its results
-- (tagged with Just into the vals MVar. Puts
-- Nothing if there are no results left. Stops executing when the
-- end MVar is filled.
sandbox :: Orc a -> MVar (Maybe a) -> MVar () -> Orc ()
-- | The rough inverse of sandbox, repeatedly reads values from the
-- vals MVar until j values have been read or
-- the vals MVar is exhausted (a Nothing is passed). When
-- there are no more values to be returned, fills the end MVar.
echo :: Int -> MVar (Maybe a) -> MVar () -> Orc a
-- | Like echo, repeatedly reads values from the pvals and
-- qvals MVar, returning tuples of the values until one
-- MVar is exhausted. When there are no more values to be
-- returned, fills the end MVar.
zipp :: MVar (Maybe a) -> MVar (Maybe b) -> MVar () -> Orc (a, b)
-- | Publish is a hyperstrict form of return. It is useful for combining
-- results from multiple val computations, providing a
-- synchronization point.
publish :: NFData a => a -> Orc a
module Orc