Data.PVar

Procrastinating variables (PVars) 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.

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

PVars are implemented with a lazy thunk that reads from an IORef; before the IORef 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: PVars are modeled closely on the IVar implementation in the ivar-simple package. The major difference is that if you try to read an IVar before it has been given a value, it blocks until the value is available, whereas reading from a PVar before it is ready raises an exception. The reason behind the different symantics for PVar 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.

PVar creation

data PVar a

A procrastinating variable (PVar for short).

newPVar :: IO (PVar a, a)

Creates a new, empty PVar, 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.

newPVarWithCustomMessage :: String -> IO (PVar a, a)

Creates a new, empty PVar 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.)

Writing to PVars

writePVar :: PVar a -> a -> IO ()

Writes a value to a PVar. Raises an AlreadyHasAValue exception if the PVar already has a value.

Probing PVars

tryReadPVar :: PVar a -> IO (Maybe a)

Tries to read a PVar, but does not throw an exception if the value is not ready yet; instead, if the value is ready it returns Just value and otherwise it returns Nothing.

tryWritePVar :: PVar a -> a -> IO Bool

Attempts to a value to a PVar, but instead of throwing an exception it returns True if it was successful and False otherwise.

Errors

data AccessedTooEarly

The exception raised when a PVar is accessed before it is ready.

Instances

Show AccessedTooEarly

Typeable AccessedTooEarly

Exception AccessedTooEarly

data AlreadyHasAValue

The exception raised by writePVar when one attempts to write to a PVar after it has already been given a value.

Instances

Show AlreadyHasAValue

Typeable AlreadyHasAValue

Exception AlreadyHasAValue