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


-- | Haskell values that cannot be evaluated immediately.
--   
--   Procrastinating variables (<a>PVar</a>s) are meant to be used in cases
--   where you want to give someone a value that you do not have available
--   yet, but will definitely have ready by the time that they need to use
--   it.
--   
--   <a>PVar</a>s have the advantage that you do not make the user of your
--   value execute some kind of unwrapping routine in order to get access
--   to the value within. For example, this is useful when you are
--   constructing closures that you want to go ahead and construct now even
--   though some of the values that they contain are not available yet.
--   
--   <a>PVar</a>s are implemented with a lazy thunk that reads from an
--   <a>IORef</a>; before the <a>IORef</a> is written to, it contains _|_
--   (an exception with a descriptive error message) so that an error is
--   raised in the user code if the variable is accidently accessed before
--   the value is ready.
--   
--   NOTE: <a>PVar</a>s are modeled closely on the <a>IVar</a>
--   implementation in the ivar-simple package. The major difference is
--   that if you try to read an <a>IVar</a> before it has been given a
--   value, it blocks until the value is available, whereas reading from a
--   <a>PVar</a> before it is ready raises an exception. The reason behind
--   the different symantics for <a>PVar</a> is because if the user
--   accidently accesses the value too early, you want there to be a lot of
--   noise to let him or her know about it, rather than merely blocking the
--   thread indefinitely and causing them to wonder what went wrong.
@package procrastinating-variable
@version 1.0.2


-- | Procrastinating variables (<a>PVar</a>s) are meant to be used in cases
--   where you want to give someone a value that you do not have available
--   yet, but will definitely have ready by the time that they need to use
--   it.
--   
--   <a>PVar</a>s have the advantage that you do not make the user of your
--   value execute some kind of unwrapping routine in order to get access
--   to the value within. For example, this is useful when you are
--   constructing closures that you want to go ahead and construct now even
--   though some of the values that they contain are not available yet.
--   
--   <a>PVar</a>s are implemented with a lazy thunk that reads from an
--   <a>IORef</a>; before the <a>IORef</a> is written to, it contains
--   <tt>_|_</tt> ( in the form of an exception with a descriptive error
--   message) so that an error is raised in the user code if the variable
--   is accidently accessed before the value is ready.
--   
--   NOTE: <a>PVar</a>s are modeled closely on the <tt>IVar</tt>
--   implementation in the ivar-simple package. The major difference is
--   that if you try to read an <tt>IVar</tt> before it has been given a
--   value, it blocks until the value is available, whereas reading from a
--   <a>PVar</a> before it is ready raises an exception. The reason behind
--   the different symantics for <a>PVar</a> is because if the user
--   accidently accesses the value too early, you want there to be a lot of
--   noise to let him or her know about it, rather than merely blocking the
--   thread indefinitely and causing them to wonder what went wrong.
module Data.PVar

-- | A procrastinating variable (<a>PVar</a> for short).
data PVar a

-- | Creates a new, empty <a>PVar</a>, and returns both a reference you can
--   use to fill the value later as well as a lazy thunk which you can
--   treat as a normal variable; the latter evaluates to the value stored
--   in the reference if it is available and to bottom otherwise.
newPVar :: IO (PVar a, a)

-- | Creates a new, empty <a>PVar</a> that raises an exception with a
--   custom message. (Use this if you want to make explicit to the user of
--   this variable exactly when they should expect its value to become
--   available.)
newPVarWithCustomMessage :: String -> IO (PVar a, a)

-- | Writes a value to a <a>PVar</a>. Raises an <a>AlreadyHasAValue</a>
--   exception if the <a>PVar</a> already has a value.
writePVar :: PVar a -> a -> IO ()

-- | Tries to read a <a>PVar</a>, but does not throw an exception if the
--   value is not ready yet; instead, if the value is ready it returns
--   <tt>Just value</tt> and otherwise it returns <tt>Nothing</tt>.
tryReadPVar :: PVar a -> IO (Maybe a)

-- | Attempts to a value to a <a>PVar</a>, but instead of throwing an
--   exception it returns <a>True</a> if it was successful and <a>False</a>
--   otherwise.
tryWritePVar :: PVar a -> a -> IO Bool

-- | The exception raised when a <a>PVar</a> is accessed before it is
--   ready.
data AccessedTooEarly

-- | The exception raised by <a>writePVar</a> when one attempts to write to
--   a <a>PVar</a> after it has already been given a value.
data AlreadyHasAValue
instance Typeable AlreadyHasAValue
instance Typeable AccessedTooEarly
instance Show AlreadyHasAValue
instance Show AccessedTooEarly
instance Exception AlreadyHasAValue
instance Exception AccessedTooEarly