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


-- | Scalable timer
--   
--   Scalable timer functions provided by a timer manager and thread
--   management functions to prevent thread leak by a thread manager.
@package time-manager
@version 0.2.2

module System.TimeManager

-- | A timeout manager
data Manager

-- | An action to be performed on timeout.
type TimeoutAction = IO ()

-- | A handle used by a timeout manager.
data Handle

-- | Creating timeout manager which works every N micro seconds where N is
--   the first argument.
initialize :: Int -> IO Manager

-- | Stopping timeout manager with onTimeout fired.
stopManager :: Manager -> IO ()

-- | Killing timeout manager immediately without firing onTimeout.
killManager :: Manager -> IO ()

-- | Call the inner function with a timeout manager. <a>stopManager</a> is
--   used after that.
withManager :: Int -> (Manager -> IO a) -> IO a

-- | Call the inner function with a timeout manager. <a>killManager</a> is
--   used after that.
withManager' :: Int -> (Manager -> IO a) -> IO a

-- | Registering a timeout action and unregister its handle when the body
--   action is finished. <a>Nothing</a> is returned on timeout.
withHandle :: Manager -> TimeoutAction -> (Handle -> IO a) -> IO (Maybe a)

-- | Registering a timeout action of killing this thread and unregister its
--   handle when the body action is killed or finished.
withHandleKillThread :: Manager -> TimeoutAction -> (Handle -> IO ()) -> IO ()

-- | Setting the state to active. <a>Manager</a> turns active to inactive
--   repeatedly.
tickle :: Handle -> IO ()

-- | Setting the state to paused. <a>Manager</a> does not change the value.
pause :: Handle -> IO ()

-- | Setting the paused state to active. This is an alias to <a>tickle</a>.
resume :: Handle -> IO ()

-- | Registering a timeout action.
register :: Manager -> TimeoutAction -> IO Handle

-- | Registering a timeout action of killing this thread.
--   <a>TimeoutThread</a> is thrown to the thread which called this
--   function on timeout. Catch <a>TimeoutThread</a> if you don't want to
--   leak the asynchronous exception to GHC RTS.
registerKillThread :: Manager -> TimeoutAction -> IO Handle

-- | Removing the <a>Handle</a> from the <a>Manager</a> immediately.
cancel :: Handle -> IO ()

-- | The asynchronous exception thrown if a thread is registered via
--   <a>registerKillThread</a>.
data TimeoutThread
TimeoutThread :: TimeoutThread
instance GHC.Exception.Type.Exception System.TimeManager.TimeoutThread
instance GHC.Show.Show System.TimeManager.TimeoutThread


-- | A thread manager including a time manager. The manager has
--   responsibility to kill managed threads.
module System.ThreadManager

-- | Manager to manage the thread and the timer.
data ThreadManager

-- | Starting a thread manager. Its action is initially set to 'return ()'
--   and should be set by <tt>setAction</tt>. This allows that the action
--   can include the manager itself.
newThreadManager :: Manager -> IO ThreadManager

-- | Stopping the manager.
--   
--   The action is run in the scope of an exception handler that catches
--   all exceptions (including asynchronous ones); this allows the cleanup
--   handler to cleanup in all circumstances. If an exception is caught, it
--   is rethrown after the cleanup is complete.
stopAfter :: ThreadManager -> IO a -> (Maybe SomeException -> IO ()) -> IO a

-- | An exception used internally to kill a managed thread.
data KilledByThreadManager
KilledByThreadManager :: Maybe SomeException -> KilledByThreadManager

-- | Fork a managed thread.
--   
--   This guarantees that the thread ID is added to the manager's queue
--   before the thread starts, and is removed again when the thread
--   terminates (normally or abnormally).
forkManaged :: ThreadManager -> String -> IO () -> IO ()

-- | Fork a managed thread with a cleanup function.
forkManagedFinally :: ThreadManager -> String -> IO () -> IO () -> IO ()

-- | Like <a>forkManaged</a>, but run action with exceptions masked
forkManagedUnmask :: ThreadManager -> String -> ((forall x. IO x -> IO x) -> IO ()) -> IO ()

-- | Fork a managed thread with a handle created by a timeout manager.
forkManagedTimeout :: ThreadManager -> String -> (Handle -> IO ()) -> IO ()

-- | Fork a managed thread with a handle created by a timeout manager and
--   with a cleanup function.
forkManagedTimeoutFinally :: ThreadManager -> String -> (Handle -> IO ()) -> IO () -> IO ()

-- | Wait until all managed thread are finished.
waitUntilAllGone :: ThreadManager -> IO ()

-- | A timeout manager
data Manager
withHandle :: ThreadManager -> TimeoutAction -> (Handle -> IO a) -> IO (Maybe a)

-- | A handle used by a timeout manager.
data Handle

-- | Setting the state to active. <a>Manager</a> turns active to inactive
--   repeatedly.
tickle :: Handle -> IO ()

-- | Setting the state to paused. <a>Manager</a> does not change the value.
pause :: Handle -> IO ()

-- | Setting the paused state to active. This is an alias to <a>tickle</a>.
resume :: Handle -> IO ()
instance GHC.Show.Show System.ThreadManager.KilledByThreadManager
instance GHC.Exception.Type.Exception System.ThreadManager.KilledByThreadManager