-- 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
--   <a>bottom</a> (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


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

-- | Creates a new, empty <a>PVar</a>, and returns both a reference you can
--   use to fill the value later as well as
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 a <tt>IVar</tt>. Raises a
--   <a>AlreadyHasAValue</a> exception if the <a>PVar</a> already has a
--   value.
writePVar :: PVar a -> a -> IO ()

-- | Try to read a procrastinating variable. Returns <a>Nothing</a> if the
--   value is not ready yet.
tryReadPVar :: PVar a -> IO (Maybe a)

-- | Writes a value to a <a>PVar</a>. Returns <a>True</a> if successful.
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 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