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


-- | Application level triggered, and edge triggered event multiqueues.
--   
--   A system for providing late binding for how different types of events
--   are handled.
--   
--   It is often important for an application to control how it consumes
--   updates for optimal processing, but event sources are typically in
--   control of delivery. The EQueue abstraction allows the consumer to
--   provide an implimentation that balances delivery for its needs. To do
--   this, it distinguishes events into two types, level and edge
--   triggered.
--   
--   Level triggered events are used where the resulting state is cared
--   about and a pure model of how events combine is available as a
--   Semigroup instance. The transitions it took to get to the new state
--   between dequeues is not of interest.
--   
--   Edge triggered events are where the sequence of occurences are of
--   importance, or a pure model is not available.
@package equeue
@version 0


-- | This module provides the core abstractions that represent managers for
--   queueable events.
module Control.Concurrent.EQueue.Class

-- | An EQueue is a way of managing edge and level triggered events. The
--   choice of EQueue implementation allows late binding of the policy by
--   which the application processes events.
class EQueue eq

-- | Registers a level triggered event. These are the events that
--   accumulate a combined change or resulting state. Returns a function to
--   enqueue updates and unregister this event.
registerSemi :: (EQueue eq, MonadIO m, Semigroup b) => eq a -> (b -> a) -> m (b -> IO (), IO ())

-- | Registers an edge triggered event. Returns a function to enqueue
--   updates and unregister this event.
registerQueued :: (EQueue eq, MonadIO m) => eq a -> m (a -> IO (), IO ())

-- | An EQueueW is the interface for waiting on events in a queue.
class EQueueW eq where {
    
    -- | The WaitPolicy allows control per-call of waitEQ as to which policy is
    --   followed. For example, if it should return immediately if there are no
    --   events to dequeue or if it should wait for at least one event to be
    --   available.
    type family WaitPolicy eq :: *;
}

-- | The dequeue operation, collecting some set of available events,
--   depending on the particular policy the given EQueue impliments.
waitEQ :: (EQueueW eq, MonadIO m) => eq a -> WaitPolicy eq -> m [a]


-- | This module provides an EQueue implimentation that uses STM to wait on
--   the first available event among a set of possible events. When Waited
--   on it can provide up to one event from every available event source
--   when it provides one event, allowing coalescing.
module Control.Concurrent.EQueue.STMEQueue

-- | A basic example implimentation of an EQueue using STM. This
--   implimentation must look at every registered event source leading to
--   inefficiency in systems with a very large number of sources. For most
--   systems it should be a sufficient implimentation though.
data STMEQueue a
STMEQueue :: TVar (Map Unique (STM (Maybe a))) -> STMEQueue a
[_eqActiveSources] :: STMEQueue a -> TVar (Map Unique (STM (Maybe a)))

-- | Passed an STM dequeueing the current value of this signal. Returns an
--   action to unregister said.
register :: MonadIO m => STMEQueue a -> STM (Maybe a) -> m (IO ())

-- | Create a new STMEQueue which initally has no event sources registered.
newSTMEQueue :: MonadIO m => m (STMEQueue a)

-- | The policy for waiting on an STMEQueue.
data STMEQueueWait

-- | Immediately return, even if no events are available.
ReturnImmediate :: STMEQueueWait

-- | Wait for at least one event to be available before returning.
RequireEvent :: STMEQueueWait
instance GHC.Classes.Eq Control.Concurrent.EQueue.STMEQueue.STMEQueueWait
instance Control.Concurrent.EQueue.Class.EQueueW Control.Concurrent.EQueue.STMEQueue.STMEQueue
instance Control.Concurrent.EQueue.Class.EQueue Control.Concurrent.EQueue.STMEQueue.STMEQueue

module Control.Concurrent.EQueue

-- | An EQueue is a way of managing edge and level triggered events. The
--   choice of EQueue implementation allows late binding of the policy by
--   which the application processes events.
class EQueue eq

-- | Registers a level triggered event. These are the events that
--   accumulate a combined change or resulting state. Returns a function to
--   enqueue updates and unregister this event.
registerSemi :: (EQueue eq, MonadIO m, Semigroup b) => eq a -> (b -> a) -> m (b -> IO (), IO ())

-- | Registers an edge triggered event. Returns a function to enqueue
--   updates and unregister this event.
registerQueued :: (EQueue eq, MonadIO m) => eq a -> m (a -> IO (), IO ())

-- | An EQueueW is the interface for waiting on events in a queue.
class EQueueW eq

-- | The dequeue operation, collecting some set of available events,
--   depending on the particular policy the given EQueue impliments.
waitEQ :: (EQueueW eq, MonadIO m) => eq a -> WaitPolicy eq -> m [a]

-- | Allows us to return an unknown instance of EQueue, getting around
--   Haskells lack of existential qualification.
data AnyEQueue a
[AEQ] :: EQueue eq => eq a -> AnyEQueue a

-- | A wrapper that translates level triggered events into events that
--   observe the edges.
data ForceEdge a
[EEQ] :: EQueue eq => eq a -> ForceEdge a

-- | A wrapper that allows us to pretend a queue of one type is of another.
data MappedEQueue eq b a
[MEQ] :: (a -> b) -> eq b -> MappedEQueue eq b a

-- | Retrieve the EQueue we're mapping to from the MappedEQueue.
meqEQ :: MappedEQueue eq b a -> eq b

-- | A basic example implimentation of an EQueue using STM. This
--   implimentation must look at every registered event source leading to
--   inefficiency in systems with a very large number of sources. For most
--   systems it should be a sufficient implimentation though.
data STMEQueue a

-- | The policy for waiting on an STMEQueue.
data STMEQueueWait

-- | Immediately return, even if no events are available.
ReturnImmediate :: STMEQueueWait

-- | Wait for at least one event to be available before returning.
RequireEvent :: STMEQueueWait

-- | Create a new STMEQueue which initally has no event sources registered.
newSTMEQueue :: MonadIO m => m (STMEQueue a)
instance Data.Functor.Contravariant.Contravariant (Control.Concurrent.EQueue.MappedEQueue eq b)
instance Control.Concurrent.EQueue.Class.EQueue eq => Control.Concurrent.EQueue.Class.EQueue (Control.Concurrent.EQueue.MappedEQueue eq b)
instance Control.Concurrent.EQueue.Class.EQueue Control.Concurrent.EQueue.ForceEdge
instance Control.Concurrent.EQueue.Class.EQueue Control.Concurrent.EQueue.AnyEQueue


-- | Simple compatability newtype wrappers to standard queues used in the
--   Haskell wild.
module Control.Concurrent.EQueue.Simple

-- | A policy for waiting until a single event can be gotten and returning
--   just one. Since these standard queing options are fairly simple the
--   don't allows more detailed policies abiding by EQueue's laws.
data JustOneEventually
JustOneEventually :: JustOneEventually

-- | A wrapper for EQueueing events into a Chan.
newtype ChanEQueue a
CEQ :: Chan a -> ChanEQueue a

-- | A wrapper for EQueueing events into a TChan.
newtype TChanEQueue a
TCEQ :: TChan a -> TChanEQueue a

-- | A wrapper for EQueueing events into a TQueue.
newtype TQueueEQueue a
TQEQ :: TQueue a -> TQueueEQueue a

-- | A wrapper for EQueueing events that we have an IO action to submit.
newtype IOEQueue a
IOEQ :: (a -> IO ()) -> IOEQueue a
instance Control.Concurrent.EQueue.Class.EQueue Control.Concurrent.EQueue.Simple.IOEQueue
instance Control.Concurrent.EQueue.Class.EQueue Control.Concurrent.EQueue.Simple.TQueueEQueue
instance Control.Concurrent.EQueue.Class.EQueueW Control.Concurrent.EQueue.Simple.TQueueEQueue
instance Control.Concurrent.EQueue.Class.EQueue Control.Concurrent.EQueue.Simple.TChanEQueue
instance Control.Concurrent.EQueue.Class.EQueueW Control.Concurrent.EQueue.Simple.TChanEQueue
instance Control.Concurrent.EQueue.Class.EQueue Control.Concurrent.EQueue.Simple.ChanEQueue
instance Control.Concurrent.EQueue.Class.EQueueW Control.Concurrent.EQueue.Simple.ChanEQueue