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


-- | GHCi background threads, hot reloading and reload-surviving values
--   
--   This package provides a safe and convenient wrapper around
--   <a>foreign-store</a> for hot-reloadable background threads during a
--   GHCi session, useful for the development of long-running programs like
--   servers, web applications and interactive user interfaces.
--   
--   It can also be used in the context of batch-style programs to keep
--   resources that are expensive to create in memory instead of having to
--   recreate them after every module reload.
@package rapid
@version 0.1.0


-- | This library provides a safer and more convenient wrapper around the
--   <a>foreign-store library</a>.
--   
--   You can use it for background services within a GHCi session that
--   survive loading, reloading and unloading modules, which is
--   particularly useful when writing long-running programs like servers
--   and user interfaces.
--   
--   <b>Please read the "Safety and securty" section below!</b>
module Rapid

-- | Handle to the current Rapid state.
data Rapid k

-- | Retrieve the current Rapid state handle, and pass it to the given
--   continuation. If the state handle doesn't exist, it is created. The
--   key type <tt>k</tt> is used for naming reloadable services like
--   threads.
--   
--   <b>Warning</b>: The key type must not change during a session. If you
--   need to change the key type, currently the safest option is to restart
--   GHCi.
--   
--   This function uses the <a>foreign-store library</a> to establish a
--   state handle that survives GHCi reloads and is suitable for hot
--   reloading.
--   
--   The first argument is the <a>Store</a> index. If you do not use the
--   <i>foreign-store</i> library in your development workflow, just use 0,
--   otherwise use any unused index.
rapid :: forall k r. Word32 -> (Rapid k -> IO r) -> IO r

-- | Create a thread with the given name that runs the given action.
--   
--   The thread is restarted each time an update occurs.
restart :: (Ord k) => Rapid k -> k -> IO () -> IO ()

-- | Create a thread with the given name that runs the given action.
--   
--   When an update occurs and the thread is currently not running, it is
--   started.
start :: (Ord k) => Rapid k -> k -> IO () -> IO ()

-- | Delete the thread with the given name.
--   
--   When an update occurs and the thread is currently running, it is
--   cancelled.
stop :: (Ord k) => Rapid k -> k -> x -> IO ()

-- | Get the value of the mutable variable with the given name. If it does
--   not exist, it is created and initialised with the value returned by
--   the given action.
--   
--   Mutable variables should only be used with values that can be
--   garbage-collected, for example communication primitives like
--   <a>MVar</a> and <a>TVar</a>, but also pure run-time information that
--   is expensive to generate, for example the parsed contents of a file.
createRef :: (Ord k, Typeable a) => Rapid k -> k -> IO a -> IO a

-- | Delete the mutable variable with the given name, if it exists.
deleteRef :: (Ord k) => Rapid k -> k -> IO ()

-- | Overwrite the mutable variable with the given name with the value
--   returned by the given action. If the mutable variable does not exist,
--   it is created.
--   
--   This function may be used to change the value type of a mutable
--   variable.
writeRef :: (Ord k, Typeable a) => Rapid k -> k -> IO a -> IO a