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


-- | Serializable closures for distributed programming.
--   
--   See README.
@package distributed-closure
@version 0.4.0


-- | Private internals. You should not use this module unless you are
--   determined to monkey with the internals. This module comes with no API
--   stability guarantees whatsoever. Use at your own risks.
module Control.Distributed.Closure.Internal

-- | Values that can be sent across the network.
type Serializable a = (Binary a, Typeable a)

-- | Type of serializable closures. Abstractly speaking, a closure is a
--   code reference paired together with an environment. A serializable
--   closure includes a <i>shareable</i> code reference (i.e. a
--   <a>StaticPtr</a>). Closures can be serialized only if all expressions
--   captured in the environment are serializable.
data Closure a
[StaticPtr] :: !(StaticPtr a) -> Closure a
[Encoded] :: !ByteString -> Closure ByteString
[Ap] :: !(Closure (a -> b)) -> !(Closure a) -> Closure b
[Duplicate] :: Closure a -> Closure (Closure a)
[Closure] :: a -> !(Closure a) -> Closure a

-- | Lift a Static pointer to a closure with an empty environment.
closure :: StaticPtr a -> Closure a

-- | Resolve a <a>Closure</a> to the value that it represents. Calling
--   <a>unclosure</a> multiple times on the same closure is efficient: for
--   most argument values the result is memoized.
unclosure :: Closure a -> a

-- | A closure can be created from any serializable value. <a>cpure</a>
--   corresponds to <a>Control.Applicative</a>'s <a>pure</a>, but
--   restricted to lifting serializable values only.
cpure :: Closure (Dict (Serializable a)) -> a -> Closure a

-- | Closure application. Note that <a>Closure</a> is not a functor, let
--   alone an applicative functor, even if it too has a meaningful notion
--   of application.
cap :: Typeable a => Closure (a -> b) -> Closure a -> Closure b

-- | Nested closure application.
capDup :: Typeable a => Closure (Closure a -> b) -> Closure a -> Closure b

-- | <a>Closure</a> is not a <a>Functor</a>, in that we cannot map
--   arbitrary functions over it. That is, we cannot define <a>fmap</a>.
--   However, we can map a static pointer to a function over a
--   <a>Closure</a>.

-- | <i>Deprecated: Use staticMap instead.</i>
cmap :: Typeable a => StaticPtr (a -> b) -> Closure a -> Closure b

-- | Turn a closure into a closure of a closure.
cduplicate :: Closure a -> Closure (Closure a)
instance GHC.StaticPtr.IsStatic Control.Distributed.Closure.Internal.Closure
instance Data.Typeable.Internal.Typeable a => Data.Binary.Class.Binary (Control.Distributed.Closure.Internal.Closure a)


-- | Serializable closures for distributed programming. This package builds
--   a "remotable closure" abstraction on top of <a>static pointers</a>.
--   See <a>this blog post</a> for a longer introduction.
module Control.Distributed.Closure

-- | Values that can be sent across the network.
type Serializable a = (Binary a, Typeable a)

-- | Type of serializable closures. Abstractly speaking, a closure is a
--   code reference paired together with an environment. A serializable
--   closure includes a <i>shareable</i> code reference (i.e. a
--   <a>StaticPtr</a>). Closures can be serialized only if all expressions
--   captured in the environment are serializable.
data Closure a

-- | Lift a Static pointer to a closure with an empty environment.
closure :: StaticPtr a -> Closure a

-- | Resolve a <a>Closure</a> to the value that it represents. Calling
--   <a>unclosure</a> multiple times on the same closure is efficient: for
--   most argument values the result is memoized.
unclosure :: Closure a -> a

-- | A closure can be created from any serializable value. <a>cpure</a>
--   corresponds to <a>Control.Applicative</a>'s <a>pure</a>, but
--   restricted to lifting serializable values only.
cpure :: Closure (Dict (Serializable a)) -> a -> Closure a

-- | Closure application. Note that <a>Closure</a> is not a functor, let
--   alone an applicative functor, even if it too has a meaningful notion
--   of application.
cap :: Typeable a => Closure (a -> b) -> Closure a -> Closure b

-- | <a>Closure</a> is not a <a>Functor</a>, in that we cannot map
--   arbitrary functions over it. That is, we cannot define <a>fmap</a>.
--   However, we can map a static pointer to a function over a
--   <a>Closure</a>.

-- | <i>Deprecated: Use staticMap instead.</i>
cmap :: Typeable a => StaticPtr (a -> b) -> Closure a -> Closure b

-- | Turn a closure into a closure of a closure.
cduplicate :: Closure a -> Closure (Closure a)

-- | A newtype-wrapper useful for defining instances of classes indexed by
--   higher-kinded types.
newtype WrappedArrowClosure a b
WrapArrowClosure :: Closure (a -> b) -> WrappedArrowClosure a b
[unwrapClosureArrow] :: WrappedArrowClosure a b -> Closure (a -> b)
type /-> = WrappedArrowClosure

-- | Values of type <tt><a>Dict</a> p</tt> capture a dictionary for a
--   constraint of type <tt>p</tt>.
--   
--   e.g.
--   
--   <pre>
--   <a>Dict</a> :: <a>Dict</a> (<a>Eq</a> <a>Int</a>)
--   </pre>
--   
--   captures a dictionary that proves we have an:
--   
--   <pre>
--   instance <a>Eq</a> 'Int
--   </pre>
--   
--   Pattern matching on the <a>Dict</a> constructor will bring this
--   instance into scope.
data Dict a :: Constraint -> *
[Dict] :: Dict a

-- | It's often useful to create a static dictionary on-the-fly given any
--   constraint. Morally, all type class constraints have associated static
--   dictionaries, since these are either global values or simple
--   combinations thereof. But GHC doesn't yet know how to invent a static
--   dictionary on-demand yet given any type class constraint, so we'll
--   have to do it manually for the time being. By defining instances of
--   this type class manually, or via <a>withStatic</a> if it becomes too
--   tedious.
class c => Static c
closureDict :: Static c => Closure (Dict c)
instance (Data.Typeable.Internal.Typeable b, Data.Typeable.Internal.Typeable a) => Data.Binary.Class.Binary (Control.Distributed.Closure.WrappedArrowClosure a b)


-- | Utility Template Haskell macros.
module Control.Distributed.Closure.TH

-- | <tt>$(cstatic 'foo)</tt> is an abbreviation for <tt>closure (static
--   foo)</tt>.
cstatic :: Name -> ExpQ
cstaticDict :: Name -> ExpQ

-- | Abbreviation for <tt>closure (static Dict)</tt>. Example usage:
--   
--   <pre>
--   foo :: Closure (Dict (Num a)) -&gt; ...
--   
--   foo $cdict ...
--   </pre>
cdict :: ExpQ
cdictFrom :: Natural -> ExpQ

-- | Auto-generates the <a>Static</a> instances corresponding to the given
--   class instances. Example:
--   
--   <pre>
--   data T a = T a
--   
--   withStatic [d| instance Show a =&gt; Show (T a) where ... |]
--   ======&gt;
--   instance Show a =&gt; Show (T a) where ...
--   instance (Static (Show a), Typeable a) =&gt; Static (Show (T a)) where
--     closureDict = closure (static (Dict -&gt; Dict)) <a>cap</a> closureDict
--   </pre>
--   
--   You will probably want to enable <tt>FlexibleContexts</tt> and
--   <tt>ScopedTypeVariables</tt> in modules that use <a>withStatic</a>.
withStatic :: DecsQ -> DecsQ


-- | <a>Closure</a> is not a functor, since we cannot map arbitrary
--   functions over it. But it sure looks like one, and an applicative one
--   at that. What we can do is map <i>static pointers to</i> arbitrary
--   functions over it (or in general, closures). <a>Closure</a> is not
--   just an applicative functor, it's also a monad, as well as a comonad,
--   if again we limit the function space to those functions that can be
--   statically pointed to.
--   
--   In fact an entire hierarchy of classes mirroring the standard classes
--   can be defined, where nearly the only difference lies in the fact that
--   higher-order arguments must be a proof of <i>static</i>-ness (i.e. a
--   <a>Closure</a>). The other difference is that composing static values
--   requires a proof of typeability, so we carry those around
--   (<a>Typeable</a> constraints).
--   
--   This module and others define just such a class hierarchy in the
--   category of static functions (aka values of type <tt><a>Closure</a> (a
--   -&gt; b)</tt>).
module Data.Functor.Static

-- | Instances of <a>StaticFunctor</a> should satisfy the following laws:
--   
--   <pre>
--   <a>staticMap</a> (static <a>id</a>) = <a>id</a>
--   <a>staticMap</a> (static (.) `<a>cap</a>` f `<a>cap</a>` g) = <a>staticMap</a> f . <a>staticMap</a> g
--   </pre>
class Typeable f => StaticFunctor f
staticMap :: (StaticFunctor f, Typeable a, Typeable b) => Closure (a -> b) -> f a -> f b
instance Data.Functor.Static.StaticFunctor Control.Distributed.Closure.Internal.Closure

module Control.Comonad.Static

-- | Instances of <a>StaticExtend</a> should satisfy the following laws:
--   
--   <pre>
--   <a>staticExtend</a> f = <a>staticMap</a> f . <a>staticDuplicate</a>
--   <a>staticDuplicate</a> = <a>staticExtend</a> (static <a>id</a>)
--   <a>staticExtend</a> f . <a>staticExtend</a> g = <a>staticExtend</a> (static (.) <a>cap</a> f <a>cap</a> <a>staticExtend</a> g)
--   <a>staticDuplicate</a> . <a>staticDuplicate</a> = <a>staticMap</a> (static <a>staticDuplicate</a>) . <a>staticDuplicate</a>
--   </pre>
class StaticFunctor w => StaticExtend w
staticDuplicate :: (StaticExtend w, Typeable a) => w a -> w (w a)
staticExtend :: (StaticExtend w, Typeable a, Typeable b) => Closure (w a -> b) -> w a -> w b
class StaticExtend w => StaticComonad w
staticExtract :: (StaticComonad w, Typeable a) => w a -> a
instance Control.Comonad.Static.StaticComonad Control.Distributed.Closure.Internal.Closure
instance Control.Comonad.Static.StaticExtend Control.Distributed.Closure.Internal.Closure

module Control.Applicative.Static

-- | Instances of <a>StaticApply</a> should satisfy the following laws
--   (writing <a>staticMap</a>, <a>staticApply</a> as infix
--   <tt>(<a>&lt;$&gt;</a>)</tt>, <tt>(<a>&lt;*&gt;</a>)</tt>,
--   respectively):
--   
--   <pre>
--   static (.) <a>&lt;$&gt;</a> u <a>&lt;*&gt;</a> v <a>&lt;*&gt;</a> w = u <a>&lt;*&gt;</a> (v <a>&lt;*&gt;</a> w)
--   x <a>&lt;*&gt;</a> (f <a>&lt;$&gt;</a> y) = (static (flip (.)) `<a>cap</a>` f) <a>&lt;$&gt;</a> x <a>&lt;*&gt;</a> y
--   f <a>&lt;$&gt;</a> (x <a>&lt;*&gt;</a> y) = (static (.) `<a>cap</a>` f) <a>&lt;$&gt;</a> x <a>&lt;*&gt;</a> y
--   </pre>
class StaticFunctor f => StaticApply f
staticApply :: (StaticApply f, Typeable a, Typeable b) => f (a -> b) -> f a -> f b
class StaticApply f => StaticApplicative f
staticPure :: (StaticApplicative f, Typeable a) => a -> f a
instance Control.Applicative.Static.StaticApply Control.Distributed.Closure.Internal.Closure

module Control.Monad.Static

-- | Instances of <a>StaticBind</a> should satisfy the following laws
--   (writing <a>staticMap</a>, <a>staticApply</a>, <a>staticBind</a> as
--   infix <tt>(<a>&lt;$&gt;</a>)</tt>, <tt>(<a>&lt;*&gt;</a>)</tt>,
--   <tt>(&gt;&gt;=)</tt>, respectively):
--   
--   <pre>
--   (m &gt;&gt;= f) &gt;&gt;= g = m &gt;&gt;= static (.) `<a>cap</a>` (staticFlippedBind g) <a>cap</a> f
--   <a>staticJoin</a> . <a>staticJoin</a> = <a>staticJoin</a> . <a>staticMap</a> (static <a>staticJoin</a>)
--   </pre>
--   
--   where
--   
--   <pre>
--   staticFlippedBind :: Closure (b -&gt; m c) -&gt; Closure (m b -&gt; m c)
--   staticFlippedBind = capDup (static (flip staticBind))
--   </pre>
class StaticApply m => StaticBind m
staticBind :: (StaticBind m, Typeable a, Typeable b) => m a -> Closure (a -> m b) -> m b
staticJoin :: (StaticBind m, Typeable a) => m (m a) -> m a
class (StaticApplicative m, StaticBind m) => StaticMonad m
staticReturn :: (StaticApplicative m, Typeable a) => a -> m a
instance (Control.Applicative.Static.StaticApplicative m, Control.Monad.Static.StaticBind m) => Control.Monad.Static.StaticMonad m
instance Control.Monad.Static.StaticBind Control.Distributed.Closure.Internal.Closure

module Data.Profunctor.Static

-- | Instances of <a>StaticProfunctor</a> should satisfy the following
--   laws:
--   
--   <pre>
--   <a>staticDimap</a> (static id) (static id) = static id
--   <a>staticLmap</a> (static id) = static id
--   <a>staticRmap</a> (static id) = static id
--   <a>staticDimap</a> f g = staticLmap f . staticRmap g
--   </pre>
class Typeable p => StaticProfunctor p
staticDimap :: (StaticProfunctor p, Typeable a, Typeable b, Typeable c, Typeable d) => Closure (a -> b) -> Closure (c -> d) -> p b c -> p a d
staticLmap :: (StaticProfunctor p, Typeable a, Typeable b, Typeable c) => Closure (a -> b) -> p b c -> p a c
staticRmap :: (StaticProfunctor p, Typeable a, Typeable c, Typeable d) => Closure (c -> d) -> p a c -> p a d
instance Data.Profunctor.Static.StaticProfunctor Control.Distributed.Closure.WrappedArrowClosure

module Data.Profunctor.Choice.Static
class StaticProfunctor p => StaticChoice p
staticLeft' :: (StaticChoice p, Typeable a, Typeable b, Typeable c) => p a b -> p (Either a c) (Either b c)
staticRight' :: (StaticChoice p, Typeable a, Typeable b, Typeable c) => p a b -> p (Either c a) (Either c b)
instance Data.Profunctor.Choice.Static.StaticChoice Control.Distributed.Closure.WrappedArrowClosure

module Data.Profunctor.Strong.Static
class StaticProfunctor p => StaticStrong p
staticFirst' :: (StaticStrong p, Typeable a, Typeable b, Typeable c) => p a b -> p (a, c) (b, c)
staticSecond' :: (StaticStrong p, Typeable a, Typeable b, Typeable c) => p a b -> p (c, a) (c, b)
instance Data.Profunctor.Strong.Static.StaticStrong Control.Distributed.Closure.WrappedArrowClosure
