Transient.Internals

See http://github.com/agocorona/transient everithing in this module is exported in order to allow extensibility.

Documentation

data TransIO x

Constructors

Transient

Fields

• runTrans :: StateT EventF IO (Maybe x)

Instances

Monad TransIO

Methods

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

(>>) :: TransIO a -> TransIO b -> TransIO b

return :: a -> TransIO a

fail :: String -> TransIO a

Functor TransIO

Methods

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

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

Applicative TransIO

Methods

pure :: a -> TransIO a

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

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

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

MonadIO TransIO

Methods

liftIO :: IO a -> TransIO a

Alternative TransIO

Methods

empty :: TransIO a

(<|>) :: TransIO a -> TransIO a -> TransIO a

some :: TransIO a -> TransIO [a]

many :: TransIO a -> TransIO [a]

MonadPlus TransIO

Methods

mzero :: TransIO a

mplus :: TransIO a -> TransIO a -> TransIO a

AdditionalOperators TransIO

Methods

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

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

atEnd' :: TransIO a -> TransIO b -> TransIO a

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

atEnd :: TransIO a -> TransIO b -> TransIO a

MonadState EventF TransIO

Methods

get :: TransIO EventF

put :: EventF -> TransIO ()

state :: (EventF -> (a, EventF)) -> TransIO a

(Num a, Eq a) => Num (TransIO a)

Methods

(+) :: TransIO a -> TransIO a -> TransIO a

(-) :: TransIO a -> TransIO a -> TransIO a

(*) :: TransIO a -> TransIO a -> TransIO a

negate :: TransIO a -> TransIO a

abs :: TransIO a -> TransIO a

signum :: TransIO a -> TransIO a

fromInteger :: Integer -> TransIO a

Monoid a => Monoid (TransIO a)

Methods

mempty :: TransIO a

mappend :: TransIO a -> TransIO a -> TransIO a

mconcat :: [TransIO a] -> TransIO a

type SData = ()

type EventId = Int

type TransientIO = TransIO

data LifeCycle

Constructors

Alive

Parent

Listener

Dead

Instances

Eq LifeCycle

Methods

(==) :: LifeCycle -> LifeCycle -> Bool

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

Show LifeCycle

Methods

showsPrec :: Int -> LifeCycle -> ShowS

show :: LifeCycle -> String

showList :: [LifeCycle] -> ShowS

data EventF

Constructors

EventF

Fields

• meffects :: ()
• event :: Maybe SData
• xcomp :: TransIO a
• fcomp :: [b -> TransIO b]
• mfData :: Map TypeRep SData
• mfSequence :: Int
• threadId :: ThreadId
• freeTh :: Bool
• parent :: Maybe EventF
• children :: MVar [EventF]
• maxThread :: Maybe (IORef Int)
• labelth :: IORef (LifeCycle, ByteString)

Instances

MonadState EventF TransIO

Methods

get :: TransIO EventF

put :: EventF -> TransIO ()

state :: (EventF -> (a, EventF)) -> TransIO a

type Effects = forall a b c. TransIO a -> TransIO a -> (a -> TransIO b) -> StateIO (StateIO (Maybe c) -> StateIO (Maybe c), Maybe a)

type StateIO = StateT EventF IO

noTrans :: StateT EventF IO x -> TransIO x

Run a "non transient" computation within the underlying state monad, so it is guaranteed that the computation neither can stop neither can trigger additional events/threads

runTransient :: TransIO x -> IO (Maybe x, EventF)

Run the transient computation with a blank state

runTransState :: EventF -> TransIO x -> IO (Maybe x, EventF)

Run the transient computation with an state

getCont :: TransIO EventF

Get the continuation context: closure, continuation, state, child threads etc

runCont :: EventF -> StateIO (Maybe a)

Run the closure and the continuation using the state data of the calling thread

runCont' :: EventF -> IO (Maybe a, EventF)

Run the closure and the continuation using his own state data

getContinuations :: StateIO [a -> TransIO b]

Warning: radiactive untyped stuff. handle with care

compose :: (Monad f, Alternative f) => [a1 -> f a1] -> a1 -> f a

Compose a list of continuations

runClosure :: EventF -> StateIO (Maybe a)

Run the closure (the x in 'x >>= f') of the current bind operation.

runContinuation :: EventF -> a -> StateIO (Maybe b)

Run the continuation (the f in 'x >>= f') of the current bind operation with the current state

setContinuation :: TransIO a -> (a -> TransIO b) -> [c -> TransIO c] -> StateIO ()

withContinuation :: t -> TransIO b -> TransIO b

runContinuations :: [a -> TransIO b] -> c -> TransIO d

run a chain of continuations. It is up to the programmer to assure by construction that each continuation type-check with the next, that the parameter type match the input of the first continuation. Normally this makes sense if it stop the current flow with stop after the invocation

restoreStack :: MonadState EventF m => [b -> TransIO b] -> m ()

readWithErr :: (Read a, Typeable * a) => String -> IO [(a, String)]

readsPrec' :: (Typeable * a, Read a) => t -> String -> [(a, String)]

class (Show a, Read a, Typeable a) => Loggable a

Instances

(Show a, Read a, Typeable * a) => Loggable a

data IDynamic

Dynamic serializable data for logging

Constructors

IDyns String

Loggable a => IDynamic a

Instances

Read IDynamic

Methods

readsPrec :: Int -> ReadS IDynamic

readList :: ReadS [IDynamic]

readPrec :: ReadPrec IDynamic

readListPrec :: ReadPrec [IDynamic]

Show IDynamic

Methods

showsPrec :: Int -> IDynamic -> ShowS

show :: IDynamic -> String

showList :: [IDynamic] -> ShowS

type Recover = Bool

type CurrentPointer = [LogElem]

type LogEntries = [LogElem]

data LogElem

Constructors

Wait

Exec

Var IDynamic

Instances

Read LogElem

Methods

readsPrec :: Int -> ReadS LogElem

readList :: ReadS [LogElem]

readPrec :: ReadPrec LogElem

readListPrec :: ReadPrec [LogElem]

Show LogElem

Methods

showsPrec :: Int -> LogElem -> ShowS

show :: LogElem -> String

showList :: [LogElem] -> ShowS

data Log

Constructors

Log Recover CurrentPointer LogEntries

Instances

Show Log

Methods

showsPrec :: Int -> Log -> ShowS

show :: Log -> String

showList :: [Log] -> ShowS

data RemoteStatus

Constructors

WasRemote

WasParallel

NoRemote

Instances

Eq RemoteStatus

Methods

(==) :: RemoteStatus -> RemoteStatus -> Bool

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

Show RemoteStatus

Methods

showsPrec :: Int -> RemoteStatus -> ShowS

show :: RemoteStatus -> String

showList :: [RemoteStatus] -> ShowS

stop :: Alternative m => m stopped

A sinonym of empty that can be used in a monadic expression. it stop the computation and execute the next alternative computation (composed with <|>)

class AdditionalOperators m where

Minimal complete definition

(**>), (<**), (<***)

Methods

(**>) :: m a -> m b -> m b infixr 1

Executes the second operand even if the frist return empty. A normal imperative (monadic) sequence uses the operator (>>) which in the Transient monad does not execute the next operand if the previous one return empty.

(<**) :: m a -> m b -> m a infixr 1

Forces the execution of the second operand even if the first stop. It does not execute the second operand as result of internal events occuring in the first operand. Return the first result

atEnd' :: m a -> m b -> m a

(<***) :: m a -> m b -> m a infixr 1

Forces the execution of the second operand even if the first stop. Return the first result. The second operand is executed also when internal events happens in the first operand and it returns something

atEnd :: m a -> m b -> m a

Instances

AdditionalOperators TransIO

Methods

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

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

atEnd' :: TransIO a -> TransIO b -> TransIO a

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

atEnd :: TransIO a -> TransIO b -> TransIO a

(<|) :: TransIO a -> TransIO b -> TransIO a

When the first operand is an asynchronous operation, the second operand is executed once (one single time) when the first completes his first asyncronous operation.

This is useful for spawning asynchronous or distributed tasks that are singletons and that should start when the first one is set up.

for example a streaming where the event receivers are acivated before the senders.

setEventCont :: TransIO a -> (a -> TransIO b) -> StateIO EventF

Set the current closure and continuation for the current statement

resetEventCont :: MonadState EventF m => Maybe t1 -> t -> m (a -> a)

Reset the closure and continuation. remove inner binds than the previous computations may have stacked in the list of continuations. resetEventCont :: Maybe a -> EventF -> StateIO (TransIO b -> TransIO b)

tailsafe :: [t] -> [t]

Threads

waitQSemB :: (Num a, Ord a) => IORef a -> IO Bool

signalQSemB :: Num a => IORef a -> IO ()

threads :: Int -> TransIO a -> TransIO a

Set the maximun number of threads for a procedure. It is useful to limit the parallelization of transient code that uses parallel spawn and waitEvents

oneThread :: TransIO a -> TransIO a

Delete all the previous child threads generated by the expression taken as parameter and continue execution of the current thread.

labelState :: (MonadIO m, MonadState EventF m) => String -> m ()

Add a label to the current passing threads so it can be printed by debugging calls like showThreads

printBlock :: MVar ()

showThreads :: MonadIO m => EventF -> m ()

topState :: TransIO EventF

Return the state of the thread that initiated the transient computation

showState :: (Typeable a, MonadIO m, Alternative m) => String -> EventF -> m (Maybe a)

Return the state variable of the type desired with which a thread, identified by his number in the treee was initiated

addThreads' :: Int -> TransIO ()

Add n threads to the limit of threads. If there is no limit, it set it

addThreads :: Int -> TransIO ()

Assure that at least there are n threads available

freeThreads :: TransIO a -> TransIO a

The threads generated in the process passed as parameter will not be killed by `kill*` primitives.

Since there is no thread control, the application run slightly faster.

hookedThreads :: TransIO a -> TransIO a

The threads will be killed when the parent thread dies. That is the default. This can be invoked to revert the effect of freeThreads

killChilds :: TransIO ()

kill all the child threads of the current thread

killBranch :: TransIO ()

Kill the current thread and the childs

killBranch' :: MonadIO m => EventF -> m ()

Kill the childs and the thread of an state

extensible state: session data management

getData :: (MonadState EventF m, Typeable a) => m (Maybe a)

Get the state data for the desired type if there is any.

getSData :: Typeable a => TransIO a

getData specialized for the Transient monad. if Nothing, the monadic computation does not continue.

If there is no such data, getSData silently stop the computation. That may or may not be the desired behaviour. To make sure that this does not get unnoticed, use this construction:

 getSData <|> error "no data"

To have the same semantics and guarantees than get, use a default value:

getInt= getSData <|> return (0 :: Int)

The default value (0 in this case) has the same role than the initial value in a state monad. The difference is that you can define as many get as you need for all your data types.

To distingish two data with the same types, use newtype definitions.

getState :: Typeable a => TransIO a

Synonym for getSData

setData :: (MonadState EventF m, Typeable a) => a -> m ()

Set session data for this type. retrieved with getData or getSData Note that this is data in a state monad, that means that the update only affect downstream in the monad execution. it is not a global state neither a per user or per thread state it is a monadic state like the one of a state monad.

modifyData :: (MonadState EventF m, Typeable a) => (Maybe a -> Maybe a) -> m ()

Modify state data. It accept a function that get the current state (if exist) as parameter. The state will be deleted or changed depending on function result

modifyState :: (MonadState EventF m, Typeable a) => (Maybe a -> Maybe a) -> m ()

Synonym for modifyData

setState :: (MonadState EventF m, Typeable a) => a -> m ()

Synonym for setData

delData :: (MonadState EventF m, Typeable a) => a -> m ()

delState :: (MonadState EventF m, Typeable a) => a -> m ()

try :: TransIO a -> TransIO a

Executes the computation and reset the state if it fails.

sandbox :: TransIO a -> TransIO a

Executes the computation and reset the state either if it fails or not

genId :: MonadState EventF m => m Int

Generator of identifiers that are unique withing the current monadic sequence They are not unique in the whole program.

getPrevId :: MonadState EventF m => m Int

data StreamData a

Async calls

Constructors

SMore a

SLast a

SDone

SError SomeException

Instances

Read a => Read (StreamData a)

Methods

readsPrec :: Int -> ReadS (StreamData a)

readList :: ReadS [StreamData a]

readPrec :: ReadPrec (StreamData a)

readListPrec :: ReadPrec [StreamData a]

Show a => Show (StreamData a)

Methods

showsPrec :: Int -> StreamData a -> ShowS

show :: StreamData a -> String

showList :: [StreamData a] -> ShowS

waitEvents :: IO b -> TransIO b

Variant of parallel that repeatedly executes the IO computation without end

async :: IO b -> TransIO b

Variant of parallel that execute the IO computation once

sync :: TransIO a -> TransIO a

in an alternative computation it executes an async operations synchronously. This means that the alternatives do not execute until the async operation finishes. Do not use in Applicatives.

spawn :: IO a -> TransIO a

`spawn= freeThreads . waitEvents`

sample :: Eq a => IO a -> Int -> TransIO a

Executes an IO action each certain interval of time and return his value if it changes

parallel :: IO (StreamData b) -> TransIO (StreamData b)

Return empty to the current thread and execute the IO action in a new thread. When the IO action returns, the transient computation continues with this value as the result The IO action may be re-executed or not depending on the result. So parallel can spawn any number of threads/results.

If the maximum number of threads, set with threads has been reached parallel perform the work sequentially, in the current thread. So parallel means that 'it can be parallelized if there are thread available'

if there is a limitation of threads, when a thread finish, the counter of threads available is increased so another parallel can make use of it.

The behaviour of parallel depend on StreamData; If SMore, parallel will excute again the IO action. With SLast, SDone and SError, parallel will not repeat the IO action anymore.

loop :: EventF -> IO (StreamData t) -> IO ()

free :: ThreadId -> EventF -> IO ()

hangThread :: EventF -> EventF -> IO ()

killChildren :: MVar [EventF] -> IO ()

kill all the child threads associated with the continuation context

react :: Typeable eventdata => ((eventdata -> IO response) -> IO ()) -> IO response -> TransIO eventdata

De-invert an event handler.

The first parameter is the setter of the event handler to be deinverted. Usually it is the primitive provided by a framework to set an event handler

the second parameter is the value to return to the event handler. Usually it is `return()`

it configures the event handler by calling the setter of the event handler with the current continuation

abduce :: TransIO ()

continue the computation in another thread and return empty to the computation in the curren thread.

Useful for executing alternative computations

non-blocking keyboard input

getLineRef :: TVar (Maybe a)

roption :: MVar [t]

option :: (Typeable b, Show b, Read b, Eq b) => b -> String -> TransIO b

Install a event receiver that wait for a string and trigger the continuation when this string arrives.

input :: (Typeable a, Read a, Show a) => (a -> Bool) -> String -> TransIO a

Validates an input entered in the keyboard in non blocking mode. non blocking means that the user can enter also anything else to activate other option unlike option, wich watch continuously, input only wait for one valid response

getLine' :: (Read a, Typeable * a) => (a -> Bool) -> IO a

Non blocking getLine with a validator

reads1 :: (Typeable * a, Read a) => String -> [(a, String)]

inputLoop :: IO b

processLine :: MonadIO m => String -> m ()

stay :: MVar (Maybe a) -> IO (Maybe a)

Wait for the execution of exit and return the result or the exhaustion of thread activity

newtype Exit a

Constructors

Exit a

keep :: Typeable a => TransIO a -> IO (Maybe a)

Keep the main thread running, initiate the non blocking keyboard input and execute the transient computation.

It also read a slash-separated list of string that are read by option and input as if they were entered by the keyboard

 foo  -p  options/to/be/read/by/option/and/input

keep' :: Typeable a => TransIO a -> IO (Maybe a)

Same than keep but do not initiate the asynchronous keyboard input. Useful for debugging or for creating background tasks, as well as to embed the Transient monad inside another computation. It returns either the value returned by exit. or Nothing, when there is no more threads running

execCommandLine :: IO ()

exit :: Typeable a => a -> TransIO a

Force the finalization of the main thread and thus, all the Transient block (and the application if there is no more code)

onNothing :: Monad m => m (Maybe b) -> m b -> m b

Alternative operator for maybe values. Used in infix mode

data Backtrack b

Constructors

Show b => Backtrack

Fields

• backtracking :: Maybe b
• backStack :: [EventF]

backCut :: (Typeable reason, Show reason) => reason -> TransientIO ()

Assures that backtracking will not go further back

undoCut :: TransientIO ()

onBack :: (Typeable b, Show b) => TransientIO a -> (b -> TransientIO a) -> TransientIO a

The second parameter will be executed when backtracking

onUndo :: TransientIO a -> TransientIO a -> TransientIO a

registerBack :: (Typeable b, Show b) => b -> TransientIO a -> TransientIO a

Register an action that will be executed when backtracking

registerUndo :: TransientIO a -> TransientIO a

forward :: (Typeable b, Show b) => b -> TransIO ()

backtracking is stopped. the exection continues forward from this point on.

retry :: TransIO ()

noFinish :: TransIO ()

back :: (Typeable b, Show b) => b -> TransientIO a

Execute backtracking. It execute the registered actions in reverse order.

If the backtracking flag is changed the flow proceed forward from that point on.

If the backtrack stack is finished or undoCut executed, the backtracking will stop.

backStateOf :: (Monad m, Show a, Typeable a) => a -> m (Backtrack a)

undo :: TransIO a

newtype FinishReason

Constructors

FinishReason (Maybe SomeException)

Instances

Show FinishReason

Methods

showsPrec :: Int -> FinishReason -> ShowS

show :: FinishReason -> String

showList :: [FinishReason] -> ShowS

initFinish :: TransientIO ()

Initialize the event variable for finalization. all the following computations in different threads will share it it also isolate this event from other branches that may have his own finish variable

onFinish :: (Maybe SomeException -> TransIO ()) -> TransIO ()

Set a computation to be called when the finish event happens

onFinish' :: TransIO a -> (Maybe SomeException -> TransIO a) -> TransIO a

Set a computation to be called when the finish event happens this only apply for

finish :: Maybe SomeException -> TransIO a

Trigger the event, so this closes all the resources

checkFinalize :: StreamData a -> TransIO a

trigger finish when the stream of data ends

onException :: Exception e => (e -> TransIO ()) -> TransIO ()

When a exception is produced anywhere after this statement, the handler is executed. | handlers are executed Last in first out.

onException' :: Exception e => TransIO a -> (e -> TransIO a) -> TransIO a

cutExceptions :: TransientIO ()

stop the backtracking mechanism from executing further handlers

continue :: TransIO ()

Resume to normal execution at this point

catcht :: Exception e => TransIO b -> (e -> TransIO b) -> TransIO b

Orphan instances

Read SomeException

Methods

readsPrec :: Int -> ReadS SomeException

readList :: ReadS [SomeException]

readPrec :: ReadPrec SomeException

readListPrec :: ReadPrec [SomeException]