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


-- | Bounded channel for STM that discards old entries when full
--   
--   This package provides a FIFO channel for STM supporting a size limit.
--   When this limit is reached, older entries are discarded to make way
--   for newer entries.
--   
--   The motivation for this is logging. If log entries are written to a
--   plain <tt>TChan</tt>, the program will use a lot of memory if it
--   produces log entries faster than they can be processed. If log entries
--   are written to a bounded channel where writes block (e.g. the
--   <tt>stm-chans</tt> package), the program may deadlock if the log
--   channel fills up. With <a>Data.STM.RollingQueue</a>, old entries will
--   be discarded instead.
--   
--   Possible improvements (not available in <a>Data.STM.RollingQueue</a>)
--   include:
--   
--   <ul>
--   <li>Discard lower-priority entries first.</li>
--   <li>Discard every other entry, so some of the older entries will still
--   be available.</li>
--   </ul>
@package rolling-queue
@version 0.1


-- | This module is usually imported qualified:
--   
--   <pre>
--   import Data.STM.RollingQueue (RollingQueue)
--   import qualified Data.STM.RollingQueue as RQ
--   </pre>
module Data.STM.RollingQueue

-- | A <a>RollingQueue</a> is a bounded FIFO channel. When the size limit
--   is exceeded, older entries are discarded to make way for newer
--   entries.
--   
--   Note: if the size limit is less than <tt>1</tt>, <a>write</a> will
--   have no effect, and <a>read</a> will always <a>retry</a>.
data RollingQueue a

-- | Create a new, empty <a>RollingQueue</a>, with the given size limit.
--   
--   To change the size limit later, use <a>setLimit</a>.
new :: Int -> STM (RollingQueue a)

-- | <tt>IO</tt> variant of <a>new</a>. This is useful for creating
--   top-level <a>RollingQueue</a>s using <a>unsafePerformIO</a>, because
--   performing <a>atomically</a> inside a pure computation is extremely
--   dangerous (can lead to <a>NestedAtomically</a> errors and even
--   segfaults, see GHC ticket #5866).
--   
--   Example:
--   
--   <pre>
--   logQueue :: <a>RollingQueue</a> LogEntry
--   logQueue = <a>unsafePerformIO</a> (RQ.<a>newIO</a> 1000)
--   {-# NOINLINE logQueue #-}
--   </pre>
newIO :: Int -> IO (RollingQueue a)

-- | Write an entry to the rolling queue. If the queue is full, discard the
--   oldest entry.
--   
--   There is no <tt>tryWrite</tt>, because <a>write</a> never retries.
write :: RollingQueue a -> a -> STM ()

-- | Read the next entry from the <a>RollingQueue</a>. <a>retry</a> if the
--   queue is empty.
--   
--   The <a>Int</a> is the number of entries discarded since the last read
--   operation (usually 0).
read :: RollingQueue a -> STM (a, Int)

-- | Like <a>read</a>, but do not <a>retry</a>. Instead, return
--   <a>Nothing</a> if the queue is empty.
tryRead :: RollingQueue a -> STM (Maybe (a, Int))

-- | Test if the queue is empty.
isEmpty :: RollingQueue a -> STM Bool

-- | <i>O(1)</i> Get the number of items in the queue.
length :: RollingQueue a -> STM Int

-- | Adjust the size limit. Queue entries will be discarded if necessary to
--   satisfy the new limit.
setLimit :: RollingQueue a -> Int -> STM ()

-- | Get the current size limit. This will return 0 if a negative value was
--   passed to <a>new</a>, <a>newIO</a>, or <a>setLimit</a>.
getLimit :: RollingQueue a -> STM Int

-- | Verify internal structure. Throw a <a>CheckException</a> if the check
--   fails, signifying a bug in the implementation.
checkInvariants :: RollingQueue a -> STM ()
data CheckException
CheckException :: String -> CheckException

-- | Dump the RollingQueue (output and internal counters) to standard
--   output. This calls <a>checkInvariants</a> first.
dump :: Show a => RollingQueue a -> IO ()
instance Typeable1 RollingQueue
instance Typeable CheckException
instance Exception CheckException
instance Show CheckException
instance Eq (RollingQueue a)