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


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


-- | Timeout manager. Since <tt>v0.3.0</tt>, timeout manager is a wrapper
--   of GHC System TimerManager, except on Windows, where it has a timer of
--   its own: the one in <tt>GHC.Event.Windows</tt> belongs to WinIO and
--   never runs under the I/O manager which is still the default there.
--   
--   Some caveats of using this package:
--   
--   <ul>
--   <li>Only works for GHC</li>
--   <li>Only works with a threaded runtime</li>
--   <li>Users of older versions should check the current semantics.</li>
--   <li>Using 32-bit systems means the max timeout is <tt><a>maxBound</a>
--   :: Int</tt> (2147483647) microseconds, which is less than 36
--   minutes.</li>
--   <li>Using the same <a>Handle</a> in different threads might cause
--   issues in some edge cases. (i.e. using <a>cancel</a>/<a>pause</a> in
--   one thread, and <a>resume</a> in another)</li>
--   </ul>
module System.TimeManager

-- | A timeout manager
data Manager

-- | A manager whose timeout value is 0 (no callbacks are fired).
defaultManager :: Manager

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

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

-- | Dummy <a>Handle</a>.
emptyHandle :: Handle

-- | Creating timeout manager with a timeout value in microseconds.
--   
--   Setting the timeout to zero or lower <tt>(&lt;= 0)</tt> will produce a
--   <a>defaultManager</a>.
initialize :: Int -> IO Manager

-- | Obsoleted since version 0.3.0 Is now equivalent to <tt>pure ()</tt>.

-- | <i>Deprecated: This function does nothing since version 0.3.0</i>
stopManager :: Manager -> IO ()

-- | Obsoleted since version 0.3.0 Is now equivalent to <tt>pure ()</tt>.

-- | <i>Deprecated: This function does nothing since version 0.3.0</i>
killManager :: Manager -> IO ()

-- | Call the inner function with a timeout manager.
withManager :: Int -> (Manager -> IO a) -> IO a

-- | Call the inner function with a timeout manager. This is identical to
--   <a>withManager</a>.

-- | <i>Deprecated: This function is the same as <a>withManager</a> since
--   version 0.3.0</i>
withManager' :: Int -> (Manager -> IO a) -> IO a

-- | Registering a timeout action and unregister its handle when the body
--   action is finished.
withHandle :: Manager -> TimeoutAction -> (Handle -> IO a) -> IO 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 ()

-- | Extending the timeout.
--   
--   To keep frequent callers cheap, the renewal is rate-limited: it is
--   skipped unless at least a quarter of the timeout (capped at one
--   second) has passed since the timeout was last registered or updated.
--   
--   Careful: this does NOT reactivate an already <a>pause</a>d
--   <a>Handle</a>!
tickle :: Handle -> IO ()

-- | Pauses the timeout so you can <a>resume</a> it later. Does not stop it
--   entirely. Use <a>cancel</a> if you want to make sure the action will
--   not be resumed.
--   
--   To resume a timeout with the same <a>Handle</a>, <a>resume</a> MUST be
--   called. Don't call <a>tickle</a> for resumption.
pause :: Handle -> IO ()

-- | Resuming the timeout.
--   
--   Works like <a>tickle</a> if the <a>Handle</a> wasn't <a>pause</a>d or
--   <a>cancel</a>ed.
resume :: Handle -> IO ()

-- | Unregistering the timeout.
--   
--   The timeout can not be <a>resume</a>d. To "resume" the timeout, you
--   need to <a>register</a> again.
cancel :: 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

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


-- | A thread manager. The manager has responsibility to kill managed
--   threads.
--   
--   Because this is based on the accompanying <a>System.TimeManager</a>
--   module, the same caveats apply:
--   
--   <ul>
--   <li>Only works for GHC.</li>
--   <li>Only works with a threaded runtime.</li>
--   <li>Users of older versions should check the current semantics.</li>
--   <li>Using 32-bit systems means the max timeout is <tt><a>maxBound</a>
--   :: Int</tt> (2147483647) microseconds, which is less than 36
--   minutes.</li>
--   <li>Using the same <tt>Handle</tt> in different threads might cause
--   issues in some edge cases. (i.e. using cancel/pause in one thread, and
--   resume in another)</li>
--   </ul>
module System.ThreadManager

-- | Manager to own threads.
data ThreadManager

-- | Create a thread manager.
--   
--   A manager owns threads; it does not time them out. A caller which
--   wants both passes its own <a>Manager</a> to <a>forkManagedTimeout</a>.
newThreadManager :: IO ThreadManager

-- | Stopping the manager.
--   
--   <pre>
--   stopAfter threadManager action cleanup
--   </pre>
--   
--   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.
--   
--   This tells the managed threads to stop; it does not wait for them to
--   be gone, and neither does the cleanup handler. They are the manager's
--   until they end, so <a>countManaged</a> goes on counting them -- which
--   is what a caller waits on with <a>waitUntilAllGone</a> before it frees
--   what those threads were using.
--   
--   A thread whose place is still being kept by <a>reserveManaged</a> is
--   not told but refused when it arrives, and never runs.
--   
--   A thread which swallows the exception and never ends is therefore
--   counted for ever, and <a>waitUntilAllGone</a> on such a manager never
--   returns. Nothing here can make it end; a caller which cannot rule that
--   out should put its own timeout around the wait.
stopAfter :: ThreadManager -> IO a -> (Maybe SomeException -> IO ()) -> IO a

-- | Generalization of <a>stopAfter</a> where the cleanup handler is
--   allowed to construct the final result
--   
--   Unlike in <a>stopAfter</a>, if an exception is thrown, it is not
--   re-thrown after the cleanup handler completes; the cleanup handler
--   itself can decide to rethrow it or compute a result.
stopAfterWithResult :: ThreadManager -> IO a -> (Either SomeException a -> IO b) -> IO b

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

-- | A place kept for a thread that is not running yet.
--   
--   Registering a thread needs its <a>ThreadId</a>, and it is the thread
--   itself which provides it, by asking for its own. A caller which forks
--   through a function that hands no identity back cannot do it on the
--   thread's behalf, so until the thread arrives and registers itself,
--   what is counted is the place kept for it.
data Reservation

-- | Keeping a place for a thread about to be forked. It counts towards
--   <a>countManaged</a> from here, so that a manager stopped in between
--   does not see a connection that has been accepted as one that is gone.
--   A place that is never taken is never given back, so a caller which
--   reserves and then fails to fork leaves the manager counting it.
reserveManaged :: ThreadManager -> IO Reservation

-- | Running the action of a thread which was reserved for, taking the
--   place kept for it: the thread records itself, so that <a>stopAfter</a>
--   can reach it, and gives the reservation back.
--   
--   The reservation is given back only once the thread is recorded, so
--   that it is counted throughout. A thread which gets here after
--   <a>stopAfter</a> has stopped the manager is killed rather than
--   registered.
--   
--   The reservation must be one kept by this manager. Taking one kept by
--   another lowers this manager's count instead of that one's: the other
--   manager never reaches zero, and once this count goes negative,
--   <a>countManaged</a>, <a>isAllGone</a> and <a>waitUntilAllGone</a>
--   throw <a>AssertionFailed</a>.
takeReservation :: ThreadManager -> Reservation -> IO () -> IO ()

-- | Fork a managed thread.
--   
--   A place is kept for the thread before it is forked, so that it counts
--   towards <a>countManaged</a> from this call rather than from the moment
--   the run-time system gives the thread its first step. The thread adds
--   itself to the manager's queue as the first thing it does, takes the
--   place over, and is removed again when it terminates (normally or
--   abnormally).
forkManaged :: ThreadManager -> String -> IO () -> IO ()

-- | Like <a>forkManaged</a>, but with a cleanup function, run regardless
--   of how the action ends. An exception from the action is not caught: it
--   ends the thread as it would under <a>forkManaged</a>.
forkManagedFinally :: ThreadManager -> String -> IO () -> IO () -> IO ()

-- | Like <a>forkManaged</a>, but run the action with exceptions masked
--   until the provided <tt>unmask</tt> is used. (i.e. <tt>(forall x. IO x
--   -&gt; IO x)</tt>)
forkManagedUnmask :: ThreadManager -> String -> ((forall x. () => IO x -> IO x) -> IO ()) -> IO ()

-- | Like <a>forkManagedUnmask</a>, but with a cleanup function, run
--   regardless of how the action ends. An exception from the action is not
--   caught: it ends the thread as it would under <a>forkManagedUnmask</a>.
forkManagedUnmaskFinally :: ThreadManager -> String -> ((forall x. () => IO x -> IO x) -> IO ()) -> IO () -> IO ()

-- | Fork a managed thread with a fork of the caller's own, for a caller
--   which does not fork with <a>forkIO</a>. (The <tt>warp</tt> library,
--   for example, forks the thread serving a connection through a function
--   of its settings, so that the user can replace it.)
--   
--   A place is kept for the thread before the fork, so that it counts
--   towards <a>countManaged</a> from here rather than from the moment the
--   thread starts, and the place is given back whether the fork makes the
--   thread or throws. A caller which forks by itself can do the same with
--   <a>reserveManaged</a> and <a>takeReservation</a>, which this is made
--   of.
forkManagedBy :: ThreadManager -> (((forall x. () => IO x -> IO x) -> IO ()) -> IO a) -> String -> ((forall x. () => IO x -> IO x) -> IO ()) -> IO a

-- | Like <a>forkManagedBy</a>, but with a cleanup function.
forkManagedByFinally :: ThreadManager -> (((forall x. () => IO x -> IO x) -> IO ()) -> IO a) -> String -> ((forall x. () => IO x -> IO x) -> IO ()) -> IO () -> IO a

-- | Fork a managed thread with a handle created by a timeout manager.
--   
--   The time manager is the caller's, since this manager has none: owning
--   a thread and timing it out are separate things, and only this pair of
--   functions needs both. What needs them together is the lock that keeps
--   the timeout and <a>stopAfter</a> from both throwing at the thread.
forkManagedTimeout :: ThreadManager -> Manager -> String -> (Handle -> IO ()) -> IO ()

-- | Like <a>forkManagedTimeout</a>, but with a cleanup function, run
--   regardless of how the action ends. An exception from the action is not
--   caught: it ends the thread as it would under
--   <a>forkManagedTimeout</a>.
forkManagedTimeoutFinally :: ThreadManager -> Manager -> String -> (Handle -> IO ()) -> IO () -> IO ()

-- | Wait until all managed threads are finished.
--   
--   After <a>stopAfter</a> this waits for the threads it stopped to end,
--   not merely for them to have been told. See there for the thread that
--   never ends.
--   
--   A place kept by <a>reserveManaged</a> and never taken is never given
--   back, so this never returns for a caller which reserves and then fails
--   to fork.
waitUntilAllGone :: ThreadManager -> IO ()

-- | STM action that checks if all managed threads are finished.
isAllGone :: ThreadManager -> STM Bool

-- | STM action for how many threads are managed, counting the places kept
--   by <a>reserveManaged</a> for threads which have not started, and the
--   threads <a>stopAfter</a> has stopped which have not ended yet.
--   
--   Throws <a>AssertionFailed</a> if the count of places has gone
--   negative, which happens when a reservation is taken by a manager other
--   than the one that kept it. A mistake of that kind which does not drive
--   the count negative goes unnoticed.
countManaged :: ThreadManager -> STM Int
instance GHC.Internal.Exception.Type.Exception System.ThreadManager.KilledByThreadManager
instance GHC.Internal.Show.Show System.ThreadManager.KilledByThreadManager
