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


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


-- | Common utility operators for data flows
module Dataflow.Operators

-- | Construct a stateless vertex that sends each input to every
--   <a>Edge</a> in the output list.
fanout :: [Edge a] -> Dataflow (Edge a)

-- | Construct a stateless vertex that applies the provided function to
--   every input and sends the result to the output.
map :: (i -> o) -> Edge o -> Dataflow (Edge i)

-- | Construct a stateful vertex with two input edges.
join2 :: state -> (StateRef state -> Timestamp -> i -> Dataflow ()) -> (StateRef state -> Timestamp -> j -> Dataflow ()) -> (StateRef state -> Timestamp -> Dataflow ()) -> Dataflow (Edge i, Edge j)

-- | Construct a stateful vertex with three input edges.
join3 :: state -> (StateRef state -> Timestamp -> i -> Dataflow ()) -> (StateRef state -> Timestamp -> j -> Dataflow ()) -> (StateRef state -> Timestamp -> k -> Dataflow ()) -> (StateRef state -> Timestamp -> Dataflow ()) -> Dataflow (Edge i, Edge j, Edge k)

-- | Construct a stateful vertex with four input edges.
join4 :: state -> (StateRef state -> Timestamp -> i1 -> Dataflow ()) -> (StateRef state -> Timestamp -> i2 -> Dataflow ()) -> (StateRef state -> Timestamp -> i3 -> Dataflow ()) -> (StateRef state -> Timestamp -> i4 -> Dataflow ()) -> (StateRef state -> Timestamp -> Dataflow ()) -> Dataflow (Edge i1, Edge i2, Edge i3, Edge i4)

-- | Construct a stateful vertex with five input edges.
join5 :: state -> (StateRef state -> Timestamp -> i1 -> Dataflow ()) -> (StateRef state -> Timestamp -> i2 -> Dataflow ()) -> (StateRef state -> Timestamp -> i3 -> Dataflow ()) -> (StateRef state -> Timestamp -> i4 -> Dataflow ()) -> (StateRef state -> Timestamp -> i5 -> Dataflow ()) -> (StateRef state -> Timestamp -> Dataflow ()) -> Dataflow (Edge i1, Edge i2, Edge i3, Edge i4, Edge i5)

-- | Construct a stateful vertex with six input edges.
join6 :: state -> (StateRef state -> Timestamp -> i1 -> Dataflow ()) -> (StateRef state -> Timestamp -> i2 -> Dataflow ()) -> (StateRef state -> Timestamp -> i3 -> Dataflow ()) -> (StateRef state -> Timestamp -> i4 -> Dataflow ()) -> (StateRef state -> Timestamp -> i5 -> Dataflow ()) -> (StateRef state -> Timestamp -> i6 -> Dataflow ()) -> (StateRef state -> Timestamp -> Dataflow ()) -> Dataflow (Edge i1, Edge i2, Edge i3, Edge i4, Edge i5, Edge i6)


-- | 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 :: 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 :: 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.
--   
--   <a>send</a>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 :: (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 :: (o -> w -> w) -> TVar w -> Dataflow (Edge o)

-- | Construct a vertex that pretty-prints items and passes them through
--   unchanged.
trace :: Show i => Edge i -> Dataflow (Edge i)

-- | Construct a vertex that discards anything sent to it.
discard :: Dataflow (Edge i)

-- | 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 :: MonadIO io => 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 :: (MonadIO io, Traversable t) => t i -> Program i -> io (Program i)

module Test.Dataflow

-- | Run a dataflow with a list of inputs. All inputs will be sent as part
--   of a single epoch.
runDataflow :: MonadIO io => (Edge o -> Dataflow (Edge i)) -> [i] -> io [o]

-- | Run a dataflow with a list of lists of inputs. Each outer list will be
--   sent as its own epoch.
runDataflowMany :: MonadIO io => (Edge o -> Dataflow (Edge i)) -> [[i]] -> io [[o]]