-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | A timer wheel
--
-- This library provides a timer wheel data structure for registering
-- one-shot or recurring IO actions to fire after a given amount
-- of time. . It is similar to TimerManager from
-- GHC.Event, but supports recurring actions, and can scale to
-- handle many more registered actions.
@package timer-wheel
@version 1.0.0
-- | This module is intended to be imported qualified:
--
--
-- import TimerWheel (TimerWheel)
-- import TimerWheel qualified
--
module TimerWheel
-- | A timer wheel is a vector-of-collections-of timers to fire. Timers may
-- be one-shot or recurring, and may be scheduled arbitrarily far in the
-- future.
--
-- A timer wheel is configured with a spoke count and
-- resolution:
--
--
-- - The spoke count determines the size of the timer vector.A
-- larger spoke count will require more memory, but will
-- result in less insert contention.
-- - The resolution determines the duration of time that each
-- spoke corresponds to, and thus how often timers are checked for
-- expiry.For example, in a timer wheel with a resolution of
-- 1 second, a timer that is scheduled to fire at
-- 8.4 o'clock will end up firing around 9.0
-- o'clock instead (that is, on the 1
-- second-boundary).A larger resolution will result in
-- more insert contention and less accurate timers, but
-- will require fewer wakeups by the timeout thread.
--
--
-- The timeout thread has some important properties:
--
--
-- - There is only one, and it fires expired timers synchronously. If
-- your timer actions execute quicky, you can register them
-- directly. Otherwise, consider registering an action that enqueues the
-- real action to be performed on a job queue.
-- - A synchronous exception thrown by a registered timer will bring
-- the timeout thread down, and the exception will be propagated to the
-- thread that created the timer wheel. If you want to log and ignore
-- exceptions, for example, you will have to bake this into the
-- registered actions yourself.
--
--
-- API summary
--
-- TODO: table
data TimerWheel
-- | A timer wheel config.
--
--
-- - spokes must be ∈ [1, maxBound], and is set to
-- 1024 if invalid.
-- - resolution must be ∈ (0, ∞], and is set to
-- 1 if invalid.
--
--
-- API summary
--
-- TODO: table
data Config
Config :: {-# UNPACK #-} !Int -> !Seconds -> Config
-- | Spoke count
[$sel:spokes:Config] :: Config -> {-# UNPACK #-} !Int
-- | Resolution
[$sel:resolution:Config] :: Config -> !Seconds
-- | A number of seconds, with nanosecond precision.
--
-- You can use numeric literals to construct a value of this type, e.g.
-- 0.5.
--
-- Otherwise, to convert from a type like Int or
-- Double, you can use the generic numeric conversion function
-- realToFrac.
type Seconds = Fixed E9
-- | A registered timer, parameterized by the result of attempting to
-- cancel it:
--
--
-- - A one-shot timer may only be canceled if it has not already
-- fired.
-- - A recurring timer can always be canceled.
--
--
-- API summary
--
-- TODO: table
data Timer a
-- | Create a timer wheel in a scope.
create :: Scope -> Config -> IO TimerWheel
-- | Perform an action with a timer wheel.
with :: Config -> (TimerWheel -> IO a) -> IO a
-- | Get the number of timers in a timer wheel.
--
-- O(1).
count :: TimerWheel -> IO Int
-- | register wheel delay action registers action
-- in wheel to fire after delay seconds.
--
-- When canceled, the timer returns whether or not the cancelation was
-- successful; False means the timer had either already fired,
-- or had already been canceled.
register :: TimerWheel -> Seconds -> IO () -> IO (Timer Bool)
-- | Like register, but for when you don't intend to cancel the
-- timer.
register_ :: TimerWheel -> Seconds -> IO () -> IO ()
-- | recurring wheel action delay registers action
-- in wheel to fire in delay seconds, and
-- every delay seconds thereafter.
recurring :: TimerWheel -> Seconds -> IO () -> IO (Timer ())
-- | Like recurring, but for when you don't intend to cancel the
-- timer.
recurring_ :: TimerWheel -> Seconds -> IO () -> IO ()
-- | Cancel a timer.
cancel :: Timer a -> IO a
instance GHC.Show.Show TimerWheel.Config
instance GHC.Generics.Generic TimerWheel.Config