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


-- | A reference counting library to alias linear resources
--   
--   A reference counting library to alias linear resources. Get started by
--   importing <tt><a>Data.Linear.Alias</a></tt>!
@package reference-counting
@version 0.1.0.0

module Data.Linear.Alias.Internal

-- | A reference counted alias
data Alias m a
[Alias] :: (a %1 -> m ()) -> !Counter -> a -> Alias m a

-- | Return all reference counted (recursively nested) fields of
--   <tt>a</tt>. These are not only <tt><a>Alias</a>es</tt> directly, but
--   all the recursively nested <tt><a>Alias</a>es</tt> in <tt>a</tt>.
countedFields :: (Generic a, Fields (Rep a)) => a -> [SomeAlias]
data SomeAlias
SomeAlias :: Alias m b -> SomeAlias
class Fields rep
fields :: Fields rep => rep a -> [SomeAlias]
instance Data.Linear.Alias.Internal.Fields GHC.Generics.V1
instance Data.Linear.Alias.Internal.Fields GHC.Generics.U1
instance forall k (f :: k -> *) i (c :: GHC.Generics.Meta). Data.Linear.Alias.Internal.Fields f => Data.Linear.Alias.Internal.Fields (GHC.Generics.M1 i c f)
instance forall k (a :: k -> *) (b :: k -> *). (Data.Linear.Alias.Internal.Fields a, Data.Linear.Alias.Internal.Fields b) => Data.Linear.Alias.Internal.Fields (a GHC.Generics.:+: b)
instance forall k (a :: k -> *) (b :: k -> *). (Data.Linear.Alias.Internal.Fields a, Data.Linear.Alias.Internal.Fields b) => Data.Linear.Alias.Internal.Fields (a GHC.Generics.:*: b)
instance Data.Linear.Alias.Internal.Fields (GHC.Generics.K1 i (Data.Linear.Alias.Internal.Alias m a))


-- | This module is designed to be imported qualified. It provides unsafe
--   operations over the reference counted structures in order to build new
--   primitives wrt linearity.
--   
--   <pre>
--   import qualified Data.Counted.Unsafe as Unsafe
--   </pre>
module Data.Linear.Alias.Unsafe

-- | Unsafely increment the counter of some reference counted resource
inc :: MonadIO m => Alias m' a %1 -> m (Alias m' a)

-- | Unsafely decrement the counter of some reference counted resource and
--   get the reference counted value (it's really, really quite unsafe).
--   
--   This doesn't free the resource if the reference count reaches 0.
dec :: MonadIO m => Alias μ a %1 -> m (Ur a)

-- | Unsafely get an aliased value. All counters are kept unchanged.
get :: Alias m' a -> a


-- | Simple reference counting with linear types inspired by Advanced
--   Topics in Types and Programming Languages Chapter 1
module Data.Linear.Alias

-- | A reference counted alias
data Alias m a
class Shareable m a

-- | Share a linear resource
--   
--   Careful! You must make sure that all aliases recursively nested within
--   this structure <tt>a</tt> are properly shared/incremented.
--   
--   If you fail to implement this correctly, reference counting won't be
--   sound. Good thing is we can do this automatically! It's much less
--   bug-prone, especially if you update the definition of a datatype. Your
--   <tt>a</tt> just needs to instance <a>Generic</a>.
share :: (Shareable m a, MonadIO m) => a %1 -> m (a, a)

-- | Share a linear resource
--   
--   Careful! You must make sure that all aliases recursively nested within
--   this structure <tt>a</tt> are properly shared/incremented.
--   
--   If you fail to implement this correctly, reference counting won't be
--   sound. Good thing is we can do this automatically! It's much less
--   bug-prone, especially if you update the definition of a datatype. Your
--   <tt>a</tt> just needs to instance <a>Generic</a>.
share :: (Shareable m a, Generic a, Fields (Rep a)) => MonadIO m => a %1 -> m (a, a)
class Forgettable m a

-- | Forget the existence of a linear resource
forget :: (Forgettable m a, MonadIO m) => a %1 -> m ()

-- | This function returns a value that is aliased in a linear pair with a
--   function to free the linear value. Since both the value and freeing
--   function must be consumed linearly, it is guaranteed that the returned
--   function is the one used to free the resource.
--   
--   The cleanup function can be one of two things:
--   
--   <ul>
--   <li>If the returned value was the last reference, the function is the
--   one passed as an argument to <tt>new</tt></li>
--   <li>Otherwise, if this isn't the last reference to the value, the
--   freeing function will be a no-op, but still must be called on the
--   value.</li>
--   </ul>
--   
--   Usage:
--   
--   <pre>
--   (x, cleanup) &lt;- Alias.get ref
--   x' &lt;- useSomehow x
--   cleanup x'
--   </pre>
get :: MonadIO μ => Alias μ a %1 -> μ (a, a %1 -> μ ())

-- | Like <a>useM</a>
use :: Alias μ a %1 -> (a %1 -> (a, b)) %1 -> (Alias μ a, b)

-- | Use a reference value in an action that uses that value linearly
--   without destroying it.
--   
--   The value with the same reference count will be returned together with
--   a byproduct of the linear computation.
useM :: MonadIO m => Alias μ a %1 -> (a %1 -> m (a, b)) %1 -> m (Alias μ a, b)

-- | Like <a>modifyM</a>
modify :: (a %1 -> a) %1 -> Alias μ a %1 -> Alias μ a

-- | Run a monadic function that modifies a reference counted resource.
modifyM :: MonadIO m => (a %1 -> m a) %1 -> Alias μ a %1 -> m (Alias μ a)
hoist :: MonadIO m => ((a %1 -> m ()) %1 -> b %1 -> μ ()) %1 -> (a %1 -> b) %1 -> Alias m a %1 -> Alias μ b

-- | Create an alias for a resource.
newAlias :: MonadIO m => (a %1 -> μ ()) %1 -> a %1 -> m (Alias μ a)
instance Data.Linear.Alias.Shareable m (Data.Linear.Alias.Internal.Alias μ a)
instance (GHC.Generics.Generic a, Data.Linear.Alias.Internal.Fields (GHC.Generics.Rep a)) => Data.Linear.Alias.Shareable m (GHC.Generics.Generically a)
instance (Data.Linear.Alias.Shareable m a, Data.Linear.Alias.Shareable m b) => Data.Linear.Alias.Shareable m (a, b)
instance Data.Linear.Alias.Shareable m a => Data.Linear.Alias.Shareable m (Data.IntMap.Internal.IntMap a)
instance Data.Linear.Alias.Shareable m a => Data.Linear.Alias.Shareable m [a]
instance Data.Linear.Alias.Shareable m GHC.Types.Int
instance Data.Linear.Alias.Forgettable μ (Data.Linear.Alias.Internal.Alias μ a)
instance (Data.Linear.Alias.Forgettable m a, Data.Linear.Alias.Forgettable m b) => Data.Linear.Alias.Forgettable m (a, b)
instance (Data.Linear.Alias.Forgettable m a, Data.Linear.Alias.Forgettable m b, Data.Linear.Alias.Forgettable m c) => Data.Linear.Alias.Forgettable m (a, b, c)
instance Data.Linear.Alias.Forgettable m a => Data.Linear.Alias.Forgettable m (Data.IntMap.Internal.IntMap a)
instance Data.Linear.Alias.Forgettable m a => Data.Linear.Alias.Forgettable m [a]
instance Data.Linear.Alias.Forgettable m GHC.Types.Int