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


-- | Fast concurrent queues much inspired by unagi-chan
--   
--   "kazura-queue" provides an implementation of FIFO queue. It is faster
--   than Chan, TQueue or TChan by the benefit of fetch-and-add
--   instruction.
--   
--   Main motivation of this package is to solve some difficulty of
--   "unagi-chan" package.
--   
--   <ul>
--   <li>In "unagi-chan", the item in the queue/chan can be lost when async
--   exception is throwed to the read thread while waiting for read.
--   (Although it has handler to recover lost item, it is difficult to keep
--   FIFO in such case)</li>
--   <li>In "unagi-chan", garbage items of the queue cannot be collected
--   immediately. Since the buffer in the queue has the reference to the
--   items until the buffer is garbage-collected.</li>
--   </ul>
--   
--   "kazura-queue" is slightly slower than "unagi-chan" instead of solving
--   these issues.
--   
--   "kazura-queue" lost broadcast function to improve the second issue. It
--   means that kazura-queue is not "Chan" but is just "Queue".
@package kazura-queue
@version 0.1.0.4


-- | WVar is waitable <a>IORef</a>. It is similar to <a>MVar</a> but
--   different at some points.
--   
--   <ul>
--   <li>The latest (cached) value can be read while someone is updating
--   the value.</li>
--   <li>Put operation can overwrite the value if the value is fresh and
--   cannot be blocked for waiting empty.</li>
--   <li>WVar is strict. It means that the new value storing into the WVar
--   will be evaluated (WHNF) before actual storing.</li>
--   </ul>
--   
--   There are two states in the user viewpoint.
--   
--   <ul>
--   <li><i><tt>Fresh</tt></i> The <a>WVar</a> is not being updated. This
--   state corresponds to full state of <a>MVar</a>.</li>
--   <li><i><tt>Updating</tt></i> The <a>WVar</a> is being updated by
--   someone. This state corresponds to empty state of <a>MVar</a>.
--   However, cached previous value can be read while Updating.</li>
--   </ul>
module Control.Concurrent.WVar

-- | "a" is the type of data in the WVar.
data WVar a

-- | Create a fresh <a>WVar</a> that contains the supplied value.
newWVar :: a -> IO (WVar a)

-- | Take the value of a <a>WVar</a> like <a>takeMVar</a>. It blocks when
--   the <a>WVar</a> is being updated.
takeWVar :: WVar a -> IO a

-- | Non-blocking version of <a>takeWVar</a>.
tryTakeWVar :: WVar a -> IO (Bool, a)

-- | Put the supplied value into a <a>WVar</a>. It performs simple "write"
--   when the <a>WVar</a> is Fresh. When the supplied value is already
--   evaluated, it never blocks.
putWVar :: WVar a -> a -> IO ()

-- | Read the cached value of the <a>WVar</a>. It never blocks.
readWVar :: WVar a -> IO a

-- | Read the fresh value of the <a>WVar</a>. It blocks and waits for a
--   fresh value when the <a>WVar</a> is being updated by someone.
readFreshWVar :: WVar a -> IO a

-- | Non-blocking version of <a>readFreshWVar</a>
tryReadFreshWVar :: WVar a -> IO (Bool, a)

-- | WCached consists of WVar and its cached ticket.
data WCached a
WCached :: {-# UNPACK #-} !WVar a -> WTicket a -> WCached a
[cachedVar] :: WCached a -> {-# UNPACK #-} !WVar a
[cachedTicket] :: WCached a -> WTicket a
type WTicket a = Ticket (WContent a)

-- | Cache the current value of the <a>WVar</a> and create <a>WCached</a>.
cacheWVar :: WVar a -> IO (WCached a)

-- | Recache the <a>WCached</a>.
--   
--   <pre>
--   recacheWCached = cacheWVar . cachedVar
--   </pre>
recacheWCached :: WCached a -> IO (WCached a)

-- | Read the value of the <a>WTicket</a>
readWTicket :: WTicket a -> a

-- | Take the value of the <a>WCached</a> like <a>takeMVar</a>. It blocks
--   when the <a>WCached</a> is being updated.
takeWCached :: WCached a -> IO (WTicket a)

-- | Non-blocking version of <a>takeWCached</a>.
tryTakeWCached :: WCached a -> IO (Bool, WTicket a)

-- | Put the value to the <a>WCached</a>. It performs simple "write" when
--   the <a>WVar</a> is <i>Fresh</i>. When the supplied value is already
--   evaluated, it never blocks.
putWCached :: WCached a -> a -> IO (WTicket a)

-- | Put the value to a <a>WCached</a>. It performs simple "write" when the
--   <a>WVar</a> is <i>Fresh</i>. It fails when the cache is obsoleted.
--   When the supplied value is already evaluated, it never blocks.
tryPutWCached :: WCached a -> a -> IO (Bool, WTicket a)

-- | Read the cached value of the <a>WCached</a>. It never blocks.
readWCached :: WCached a -> a

-- | Read the <i>Fresh</i> value of the <a>WCached</a>. It blocks and waits
--   for a <i>Fresh</i> value when the <a>WCached</a> is being updated by
--   someone.
readFreshWCached :: WCached a -> IO (WTicket a)

-- | Non-blocking version of <a>readFreshWCached</a>
tryReadFreshWCached :: WCached a -> IO (Bool, WTicket a)
instance GHC.Classes.Eq (Control.Concurrent.WVar.WCached a)
instance GHC.Classes.Eq (Control.Concurrent.WVar.WVar a)
instance GHC.Show.Show a => GHC.Show.Show (Control.Concurrent.WVar.WCached a)
instance GHC.Show.Show a => GHC.Show.Show (Control.Concurrent.WVar.WContent a)
instance GHC.Show.Show (Control.Concurrent.WVar.WState a)


-- | KazuraQueue is the fast queue implementation inspired by unagi-chan.
module Control.Concurrent.KazuraQueue

-- | Type of a Queue. <i>a</i> is the type of an item in the Queue.
data Queue a

-- | Create a new empty <a>Queue</a>.
newQueue :: IO (Queue a)

-- | Read an item from the <a>Queue</a>.
readQueue :: Queue a -> IO a

-- | Non-masked version of <a>readQueue</a>. It is not safe for
--   asynchronous exception.
readQueueWithoutMask :: Queue a -> IO a

-- | Try to read an item from the <a>Queue</a>. It never blocks.
--   
--   Note: It decreases "length" of <a>Queue</a> even when it returns
--   Nothing. In such case, "length" will be lower than 0.
tryReadQueue :: Queue a -> IO (Maybe a)

-- | Non-masked version of <a>tryReadQueue</a>. It is not safe for
--   asynchronous exception.
tryReadQueueWithoutMask :: Queue a -> IO (Maybe a)

-- | Write an item to the <a>Queue</a>. The item is evaluated (WHNF) before
--   actual queueing.
writeQueue :: Queue a -> a -> IO ()

-- | Non-masked version of <a>writeQueue</a>. It is not safe for
--   asynchronous exception.
writeQueueWithoutMask :: Queue a -> a -> IO ()

-- | Get the length of the items in the <a>Queue</a>.
--   
--   Caution: It returns the value which is lower than 0 when the Queue is
--   empty and some threads are waiting for new value.
lengthQueue :: Queue a -> IO Int

-- | Non-minus version of <a>lengthQueue</a>.
lengthQueue' :: Queue a -> IO Int
