Acme.RealWorld

Primitives for manipulating the state of the universe.

The RealWorld type

data RealWorld

RealWorld is deeply magical. It is primitive, but it is not unlifted (hence ptrArg). We never manipulate values of type RealWorld; it's only used in the type system, to parameterise State#.

Universe manipulation primitives

getWorld :: IO RealWorld

Retrieve the current state of the universe.

putWorld :: RealWorld -> IO ()

Set the current state of the universe. Program values are not affected by this operation, but the rest of the universe is.

putWorld may not be called on the same state twice (this is enforced by the runtime system). Otherwise, it would be possible to trap the universe in a temporal loop:

getWorld >>= forever . putWorld

execIO :: IO a -> RealWorld -> RealWorld

Given an action, construct a function that, given a state of the universe, returns the state of the universe after the action has occurred.

Example:

main = do
    let f = execIO $ putStrLn "Second"
        g = execIO $ putStrLn "First"
        getWorld >>= putWorld . f . g

Derived combinators

hypothetically :: IO a -> IO a

Perform an action and return its value, but undo any side effects to the universe. Thus, it appears to return instantly, regardless of how long the action would take to run.

The caller must ensure that the program would have enough time to perform the computation. Otherwise, either an exception will be thrown, or the operation will block because it never gets a chance to restore the original state of the universe.