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


-- | Serializable closures for distributed programming.
--   
--   See README.
@package distributed-closure
@version 0.3.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
[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

-- | <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>.
cmap :: Typeable a => StaticPtr (a -> b) -> Closure a -> Closure b
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>.
cmap :: Typeable a => StaticPtr (a -> b) -> Closure a -> Closure b

-- | 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) :: 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)


-- | 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>
withStatic :: DecsQ -> DecsQ
