-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | A Pure-Haskell Timely Dataflow System
--   
--   See README
@package dataflower
@version 0.1.0.0


-- | Timely Dataflow in pure Haskell.
module Dataflow

-- | <a>Dataflow</a> is the type of all dataflow operations.
data Dataflow a

-- | An <a>Edge</a> is a typed reference to a computational vertex that
--   takes <tt>a</tt>s as its input.
data Edge a

-- | <a>Timestamp</a>s represent instants in the causal timeline.
data Timestamp

-- | Mutable state that holds an <tt>a</tt>.
data StateRef a

-- | Send an <a>input</a> item to be worked on to the indicated vertex.
send :: Typeable input => Edge input -> Timestamp -> input -> Dataflow ()

-- | Read the value stored in the <a>StateRef</a>.
readState :: StateRef a -> Dataflow a

-- | Overwrite the value stored in the <a>StateRef</a>.
writeState :: StateRef a -> a -> Dataflow ()

-- | Update the value stored in <a>StateRef</a>.
modifyState :: StateRef a -> (a -> a) -> Dataflow ()

-- | Construct a vertex with internal state. Like <a>statelessVertex</a>,
--   <a>statefulVertex</a> requires a procedure to invoke on each input. It
--   also needs an initial <tt>state</tt> value and a procedure to call
--   when all inputs for a given <a>Timestamp</a> value have been
--   delivered.
--   
--   NB: Until the finalizer has been called for a particular timestamp, a
--   stateful vertex must be capable of accepting data for multiple
--   timestamps simultaneously.
statefulVertex :: Typeable i => state -> (StateRef state -> Timestamp -> i -> Dataflow ()) -> (StateRef state -> Timestamp -> Dataflow ()) -> Dataflow (Edge i)

-- | Construct a vertex with no internal state. The given procedure is
--   invoked on each input.
--   
--   <tt>send</tt>ing to a stateless vertex is effectively a function call
--   and will execute in the caller's thread. By design this is a cheap
--   operation.
statelessVertex :: Typeable i => (Timestamp -> i -> Dataflow ()) -> Dataflow (Edge i)

-- | Construct an output vertex that stores items into the provided
--   <a>TVar</a>. The first argument is an update function so that, for
--   example, the <a>TVar</a> could contain a list of <tt>o</tt>s and the
--   update function could then <tt>cons</tt> new items onto the list.
outputTVar :: Typeable o => (o -> w -> w) -> TVar w -> Dataflow (Edge o)

-- | A <a>Program</a> represents a fully-preprocessed <a>Dataflow</a> that
--   may be executed against inputs.
data Program i

-- | Take a <a>Dataflow</a> which takes <tt>i</tt>s as input and compile it
--   into a <a>Program</a>.
compile :: Dataflow (Edge i) -> IO (Program i)

-- | Feed a traversable collection of inputs to a <a>Program</a>. All
--   inputs provided will have the same <a>Timestamp</a> associated with
--   them.
execute :: (Traversable t, Typeable i) => t i -> Program i -> IO ()

module Test.Dataflow
runDataflow :: (Typeable i, Typeable o, MonadIO io) => (Edge o -> Dataflow (Edge i)) -> [i] -> io [o]