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


-- | Serializable closures for distributed programming.
--   
--   See README.
@package distributed-closure
@version 0.2.0.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 Data.Typeable.Internal.Typeable a => Data.Binary.Class.Binary (Control.Distributed.Closure.Internal.Closure a)


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

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

-- | Create a static dictionary from the given dictionaries. Example usage:
--   
--   <pre>
--   $cdictFrom 2 Dict Dict :: Closure (Static (Dict (Eq a, Show a)))
--   </pre>
cdictFrom :: Natural -> ExpQ


-- | Serializable closures for distributed programming.
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