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


-- | Functional combinators for monadic actions that require allocation and de-allocation
--   
--   See module docs for more information, and <a>cv-combinators</a>
--   package for example usage.
@package allocated-processor
@version 0.0.2

module Foreign.ForeignPtrWrap

-- | A wrapper for newForeignPtr that handles nullPtrs, and can be chained
--   to an IO Ptr creator.
--   
--   Example usage:
--   
--   <pre>
--   myPtrCreator = (createForeignPtr deallocFunc) . allocFunc
--   </pre>
--   
--   where, allocFunc :: a-&gt;b-&gt;c-&gt;...-&gt; IO (Ptr z)
createForeignPtr :: (FunPtr (Ptr a -> IO ())) -> IO (Ptr a) -> IO (ForeignPtr a)

-- | Fails if the ptr is nullPtr
checkPtr :: IO (Ptr a) -> IO (Ptr a)

-- | Names a failure
errorName :: String -> IO a -> IO a


-- | Framework for expressing monadic actions that require initialization
--   and finalization. This module provides a <i>functional</i> interface
--   for defining and chaining a series of processors.
--   
--   Motivating example: in the IO monad, bindings to C libraries that use
--   functions such as: f(foo *src, foo *dst), where the pointer
--   <tt>dst</tt> must be pre-allocated. In this case we normally do:
--   
--   <pre>
--   foo *dst = allocateFoo();
--   ... 
--   while (something) {
--      f(src, dst);
--      ...
--   }
--   releaseFoo(dst);
--   </pre>
--   
--   You can use the <a>runUntil</a> function below to emulate that loop.
--   
--   Processor is an instance of Category, Functor, Applicative and Arrow.
--   
--   In addition to the general type <tt><a>Processor</a> m a b</tt>, this
--   module also defines (and gives a semantic model for)
--   <tt><a>Processor</a> IO a b</tt>, which has synonym
--   <tt><a>IOProcessor</a> a b</tt>.
module Control.Processor

-- | The type of Processors
--   
--   <ul>
--   <li><tt>a</tt>, <tt>b</tt> = the input and output types of the
--   processor (think a -&gt; b)</li>
--   <li>x = type of internal state (existentially quantified)</li>
--   </ul>
--   
--   The arguments to the constructor are:
--   
--   <ol>
--   <li><tt>a -&gt; x -&gt;m x</tt> - Processing function: Takes input and
--   internal state, and returns new internal state.</li>
--   <li><tt>a -&gt; m x</tt> - Allocator for internal state (this is run
--   only once): Takes (usually the first) input, and returns initial
--   internal state.</li>
--   <li><tt>x -&gt; m b</tt> - Convertor from state x to output b: Takes
--   internal state and returns the output.</li>
--   <li><tt>x -&gt; m ()</tt> - Releaser for internal state (finalizer,
--   run once): Run after processor is done being used, to release the
--   internal state.</li>
--   </ol>
--   
--   TODO: re-define in terms that don't need the <tt>x</tt> existential
--   (and the allocator), using a continuation-style processing function.
data Processor m a b
Processor :: (a -> x -> m x) -> (a -> m x) -> (x -> m b) -> (x -> m ()) -> Processor m a b

-- | The semantic model for <a>IOProcessor</a> is a function:
--   
--   <pre>
--   [[ 'IOProcessor' a b ]] = a -&gt; b
--   </pre>
--   
--   To satisfy this model, the Processor value (the implementation) must
--   obey the rules:
--   
--   <ol>
--   <li>The processing function (<tt>a -&gt; x -&gt; m x</tt>) must act as
--   if purely, so that indeed for a given input the output is always the
--   same. One particular thing to be careful with is that the output does
--   not depend on time (for example, you shouldn't use IOProcessor to
--   implement an input device). The <tt>IOSource</tt> type is defined
--   exactly for time-dependent processors. For pointer typed inputs and
--   outputs, see next law.</li>
--   <li>For processors that work on pointers, <tt>[[ Ptr t ]] = t</tt>.
--   This is guaranteed by the following implementation constraints for
--   <tt>IOProcessor a b</tt>:</li>
--   <li>If <tt>a</tt> is a pointer type (<tt>a = Ptr p</tt>), then the
--   processor must NOT write (modify) the referenced data.</li>
--   <li>If <tt>b</tt> is a pointer, the memory it points to (and its
--   allocation status) is only allowed to change by the processor that
--   created it (in the processing and releasing functions). In a way this
--   generalizes the first constraint.</li>
--   </ol>
--   
--   Note, that unlike <a>Yampa</a>, this model does not allow
--   transformations of the type <tt>(Time -&gt; a) -&gt; (Time -&gt;
--   b)</tt>. The reason is that I want to prevent arbitrary time access
--   (whether causal or not). This limitation means that everything is
--   essentially <a>point-wise</a> in time. To allow memory-full operations
--   under this model, <a>scanlT</a> is defined. See
--   <a>http://www.ee.bgu.ac.il/~noamle/_downloads/gaccum.pdf</a> for more
--   about arbitrary time access.
type IOProcessor a b = Processor IO a b

-- | <tt><a>IOSource</a> a b</tt> is the type of time-dependent processors,
--   such that:
--   
--   <pre>
--   [[ 'IOSource' a b ]] = (a, Time) -&gt; b
--   </pre>
--   
--   Thus, it is ok to implement a processing action that outputs arbitrary
--   time-dependent values during runtime regardless of input. (Although
--   the more useful case is to calculate something from the input
--   <tt>a</tt> that is also time-dependent. The <tt>a</tt> input is often
--   not required and in those cases <tt>a = ()</tt> is used.
--   
--   Notice that this means that IOSource doesn't qualify as an
--   <a>IOProcessor</a>. However, currently the implementation <i>does
--   NOT</i> enforce this, i.e. IOSource is not a newtype; I don't know how
--   to implement it correctly. Also, one question is whether primitives
--   like <a>chain</a> will have to disallow placing <a>IOSource</a> as the
--   second element in a chain. Maybe they should, maybe they shouldn't.
type IOSource a b = Processor IO a b

-- | TODO: What's the semantic model for <tt><a>IOSink</a> a</tt>?
type IOSink a = IOProcessor a ()

-- | TODO: do we need this? we're exporting the data constructor anyway for
--   now, so maybe we don't.
processor :: Monad m => (a -> x -> m x) -> (a -> m x) -> (x -> m b) -> (x -> m ()) -> Processor m a b

-- | Chains two processors serially, so one feeds the next.
chain :: Processor m a b' -> Processor m b' b -> Processor m a b

-- | A processor that represents two sub-processors in parallel (although
--   the current implementation runs them sequentially, but that may change
--   in the future)
parallel :: Processor m a b -> Processor m c d -> Processor m (a, c) (b, d)

-- | Constructs a processor that: given two processors, gives source as
--   input to both processors and runs them independently, and after both
--   have have finished, outputs their combined outputs.
--   
--   Semantic meaning, using Arrow's (&amp;&amp;&amp;) operator: [[
--   forkJoin ]] = &amp;&amp;&amp; Or, considering the Applicative instance
--   of functions (which are the semantic meanings of a processor): [[
--   forkJoin ]] = liftA2 (,) Alternative implementation to consider: f
--   &amp;&amp;&amp; g = (,) <a>&amp;</a> f <a>*</a> g
forkJoin :: Processor m a b -> Processor m a b' -> Processor m a (b, b')

-- | The identity processor: output = input. Semantically, [[ empty ]] = id
empty :: Monad m => Processor m a a

-- | Splits (duplicates) the output of a functor, or on this case a
--   processor.
split :: Functor f => f a -> f (a, a)

-- | 'f --&lt; g' means: split f and feed it into g. Useful for feeding
--   parallelized (***'d) processors. For example, a --<a> (b *** c) = a
--   </a>&gt;&gt; (b &amp;&amp;&amp; c)
(--<) :: (Functor (cat a), Category cat) => cat a a1 -> cat (a1, a1) c -> cat a c

-- | Runs the processor once: allocates, processes, converts to output, and
--   deallocates.
run :: Monad m => Processor m a b -> a -> m b

-- | Keeps running the processing function in a loop until a predicate on
--   the output is true. Useful for processors whose main function is after
--   the allocation and before deallocation.
runUntil :: Monad m => Processor m a b -> a -> (b -> m Bool) -> m b

-- | Runs the processor once, but passes the processing + conversion action
--   to the given function.
runWith :: Monad m => (m b -> m b') -> Processor m a b -> a -> m b'

-- | Creates a processor that operates around an inner processor.
--   
--   Useful for sharing resources between two actions, a pre and a post
--   action.
--   
--   The outer processor has <i>two</i> processing functions, pre:
--   <tt>a-&gt;b</tt> and post: <tt>c-&gt;d</tt>. The last argument is the
--   inner processor, <tt>Processor b c</tt>. Thus, the resulting processor
--   takes the <tt>a</tt>, processes it into a <tt>b</tt>, feeds that
--   through the inner processor to get a <tt>c</tt>, and finally
--   post-processes the <tt>c</tt> into a <tt>d</tt>.
--   
--   <i>Example scenario</i>: A singleton hardware device context, that
--   cannot be duplicated or allocated more than once. You need to both
--   read and write to that device. It's not possible to create two
--   processors, one for reads and one for writes, because they need to use
--   the same allocation (the device context). With wrapPrcessor you can
--   have the read as the pre-processing and write as the post-processing.
--   Let's call the result of calling wrapProcessor except the last
--   argument, <a>myDeviceProcessor</a>. Thus, you have:
--   
--   <pre>
--   [[ myDeviceProcessor innerProc ]] = read &gt;&gt;&gt; innerProc &gt;&gt;&gt; write
--   </pre>
--   
--   TODO: Find a more general / elegant solution to the <a>shared
--   resource</a> problem.
wrapProcessor :: Monad m => (a -> x -> m x) -> (c -> x -> m x) -> (a -> m x) -> (x -> m b) -> (x -> m d) -> (x -> m ()) -> Processor m b c -> Processor m a d
trace :: Show a => IOProcessor a a

-- | scanlT provides the primitive for performing memory-full operations on
--   time-dependent processors, as | described in
--   <a>http://www.ee.bgu.ac.il/~noamle/_downloads/gaccum.pdf</a>.
--   
--   <i>Untested</i>, and also doesn't implement the <a>limit as dt -&gt;
--   0</a> part of the model. Currently the precision of the approximation
--   is set by the samplerate (how many times per second the resulting
--   processor is run, the more the better for precision).
--   
--   scanlT and all its uses are probably most (or only?) useful in the
--   context of Processor IO. However for generality it is defined here on
--   arbitrary Processor m.
--   
--   The <tt>Processor m a b</tt> argument should really be time-dependent
--   during runtime, so it's model can't be <tt>a -&gt; b</tt>. Thus it is
--   most logical to use only <a>IOSource</a> types for the processor
--   argument.
scanlT :: Monad m => m t -> (b -> b -> t -> c -> c) -> c -> Processor m a b -> Processor m a c

-- | Differentiate of time-dependent values, using <a>scanlT</a>
differentiate :: (VectorSpace v, Fractional (Scalar v), Monad m) => m (Scalar v) -> Processor m a v -> Processor m a v

-- | Integration of time-dependent values, using <a>scanlT</a>, implemented
--   by trapezoidal approximation.
integrate :: (VectorSpace v, Fractional (Scalar v), Monad m) => m (Scalar v) -> Processor m a v -> Processor m a v

-- | Running maximum of a processor's values
maxP :: (Ord b, Monad m) => m t -> b -> Processor m a b -> Processor m a b

-- | Running minimum of a processor's values
minP :: (Ord b, Monad m) => m t -> b -> Processor m a b -> Processor m a b
nStepsMemory :: Monad m => Int -> ([(t, b)] -> c) -> (t, b) -> c -> m t -> Processor m a b -> Processor m a c

-- | Holds a Maybe-valued processor and reports the time passed since last
--   value was seen.
holdMaybe :: (Num t, Monad m) => b -> m t -> Processor m a (Maybe b) -> Processor m a (b, t)

-- | Given a <a>holdMaybe</a>-type processor, reverts back to a default
--   value if no input was seen for more than a given time limit
revertAfterT :: (Monad m, Ord t) => t -> b -> Processor m a (b, t) -> Processor m a b
discreteConv :: VectorSpace a => [Scalar a] -> [a] -> a

-- | Finite impulse response
fir :: (Monad m, Fractional (Scalar v), VectorSpace v) => [Scalar v] -> t -> m t -> Processor m a v -> Processor m a v
instance Monad m => Arrow (Processor m)
instance Monad m => Applicative (Processor m a)
instance Monad m => Functor (Processor m a)
instance Monad m => Category (Processor m)