<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<head>
<!-- Generated by HsColour, http://code.haskell.org/~malcolm/hscolour/ -->
<title>src/Control/Concurrent/MSemN2.hs</title>
<link type='text/css' rel='stylesheet' href='hscolour.css' />
</head>
<body>
<pre><a name="line-1"></a><span class='hs-comment'>{-# LANGUAGE DeriveDataTypeable #-}</span>
<a name="line-2"></a><span class='hs-comment'>-- | </span>
<a name="line-3"></a><span class='hs-comment'>-- Module : Control.Concurrent.MSemN2</span>
<a name="line-4"></a><span class='hs-comment'>-- Copyright : (c) Chris Kuklewicz 2011</span>
<a name="line-5"></a><span class='hs-comment'>-- License : 3 clause BSD-style (see the file LICENSE)</span>
<a name="line-6"></a><span class='hs-comment'>-- </span>
<a name="line-7"></a><span class='hs-comment'>-- Maintainer : haskell@list.mightyreason.com</span>
<a name="line-8"></a><span class='hs-comment'>-- Stability : experimental</span>
<a name="line-9"></a><span class='hs-comment'>-- Portability : non-portable (concurrency)</span>
<a name="line-10"></a><span class='hs-comment'>--</span>
<a name="line-11"></a><span class='hs-comment'>-- Quantity semaphores in which each thread may wait for an arbitrary amount. This modules is</span>
<a name="line-12"></a><span class='hs-comment'>-- intended to improve on "Control.Concurrent.QSemN".</span>
<a name="line-13"></a><span class='hs-comment'>-- </span>
<a name="line-14"></a><span class='hs-comment'>-- This semaphore gracefully handles threads which die while blocked waiting for quantity. The</span>
<a name="line-15"></a><span class='hs-comment'>-- fairness guarantee is that blocked threads are FIFO. An early thread waiting for a large</span>
<a name="line-16"></a><span class='hs-comment'>-- quantity will prevent a later thread waiting for a small quantity from jumping the queue.</span>
<a name="line-17"></a><span class='hs-comment'>--</span>
<a name="line-18"></a><span class='hs-comment'>-- If 'with' is used to guard a critical section then no quantity of the semaphore will be lost</span>
<a name="line-19"></a><span class='hs-comment'>-- if the activity throws an exception.</span>
<a name="line-20"></a><span class='hs-comment'>--</span>
<a name="line-21"></a><span class='hs-comment'>-- The functions below are generic in (Integral i) with specialization to Int and Integer.</span>
<a name="line-22"></a><span class='hs-comment'>--</span>
<a name="line-23"></a><span class='hs-comment'>-- Overflow warning: These operations do not check for overflow errors. If the Integral type is too</span>
<a name="line-24"></a><span class='hs-comment'>-- small to accept the new total then the behavior of these operations is undefined. Using (MSem</span>
<a name="line-25"></a><span class='hs-comment'>-- Integer) prevents the possibility of an overflow error.</span>
<a name="line-26"></a><span class='hs-keyword'>module</span> <span class='hs-conid'>Control</span><span class='hs-varop'>.</span><span class='hs-conid'>Concurrent</span><span class='hs-varop'>.</span><span class='hs-conid'>MSemN2</span>
<a name="line-27"></a> <span class='hs-layout'>(</span><span class='hs-conid'>MSemN</span>
<a name="line-28"></a> <span class='hs-layout'>,</span><span class='hs-varid'>new</span>
<a name="line-29"></a> <span class='hs-layout'>,</span><span class='hs-varid'>with</span>
<a name="line-30"></a> <span class='hs-layout'>,</span><span class='hs-varid'>wait</span>
<a name="line-31"></a> <span class='hs-layout'>,</span><span class='hs-varid'>signal</span>
<a name="line-32"></a> <span class='hs-layout'>,</span><span class='hs-varid'>withF</span>
<a name="line-33"></a> <span class='hs-layout'>,</span><span class='hs-varid'>waitF</span>
<a name="line-34"></a> <span class='hs-layout'>,</span><span class='hs-varid'>signalF</span>
<a name="line-35"></a> <span class='hs-layout'>,</span><span class='hs-varid'>peekAvail</span>
<a name="line-36"></a> <span class='hs-layout'>)</span> <span class='hs-keyword'>where</span>
<a name="line-37"></a>
<a name="line-38"></a><span class='hs-keyword'>import</span> <span class='hs-conid'>Prelude</span><span class='hs-layout'>(</span> <span class='hs-conid'>Integral</span><span class='hs-layout'>,</span><span class='hs-conid'>Eq</span><span class='hs-layout'>,</span><span class='hs-conid'>IO</span><span class='hs-layout'>,</span><span class='hs-conid'>Int</span><span class='hs-layout'>,</span><span class='hs-conid'>Integer</span><span class='hs-layout'>,</span><span class='hs-conid'>Maybe</span><span class='hs-layout'>(</span><span class='hs-conid'>Just</span><span class='hs-layout'>,</span><span class='hs-conid'>Nothing</span><span class='hs-layout'>)</span><span class='hs-layout'>,</span><span class='hs-conid'>Num</span><span class='hs-layout'>(</span><span class='hs-layout'>(</span><span class='hs-varop'>+</span><span class='hs-layout'>)</span><span class='hs-layout'>,</span><span class='hs-layout'>(</span><span class='hs-comment'>-</span><span class='hs-layout'>)</span><span class='hs-layout'>)</span><span class='hs-layout'>,</span><span class='hs-conid'>Bool</span><span class='hs-layout'>(</span><span class='hs-conid'>False</span><span class='hs-layout'>,</span><span class='hs-conid'>True</span><span class='hs-layout'>)</span>
<a name="line-39"></a> <span class='hs-layout'>,</span> <span class='hs-varid'>return</span><span class='hs-layout'>,</span><span class='hs-varid'>id</span><span class='hs-layout'>,</span><span class='hs-varid'>const</span><span class='hs-layout'>,</span><span class='hs-varid'>fmap</span><span class='hs-layout'>,</span><span class='hs-varid'>snd</span><span class='hs-layout'>,</span><span class='hs-varid'>seq</span>
<a name="line-40"></a> <span class='hs-layout'>,</span> <span class='hs-layout'>(</span><span class='hs-varop'>.</span><span class='hs-layout'>)</span><span class='hs-layout'>,</span><span class='hs-layout'>(</span><span class='hs-varop'><=</span><span class='hs-layout'>)</span><span class='hs-layout'>,</span><span class='hs-layout'>(</span><span class='hs-varop'>$</span><span class='hs-layout'>)</span><span class='hs-layout'>,</span><span class='hs-layout'>(</span><span class='hs-varop'>$!</span><span class='hs-layout'>)</span> <span class='hs-layout'>)</span>
<a name="line-41"></a><span class='hs-keyword'>import</span> <span class='hs-conid'>Control</span><span class='hs-varop'>.</span><span class='hs-conid'>Concurrent</span><span class='hs-varop'>.</span><span class='hs-conid'>MVar</span><span class='hs-layout'>(</span> <span class='hs-conid'>MVar</span>
<a name="line-42"></a> <span class='hs-layout'>,</span> <span class='hs-varid'>withMVar</span><span class='hs-layout'>,</span><span class='hs-varid'>modifyMVar</span><span class='hs-layout'>,</span><span class='hs-varid'>newMVar</span>
<a name="line-43"></a> <span class='hs-layout'>,</span> <span class='hs-varid'>newEmptyMVar</span><span class='hs-layout'>,</span><span class='hs-varid'>tryPutMVar</span><span class='hs-layout'>,</span><span class='hs-varid'>takeMVar</span><span class='hs-layout'>,</span><span class='hs-varid'>tryTakeMVar</span> <span class='hs-layout'>)</span>
<a name="line-44"></a><span class='hs-keyword'>import</span> <span class='hs-conid'>Control</span><span class='hs-varop'>.</span><span class='hs-conid'>Exception</span><span class='hs-layout'>(</span><span class='hs-varid'>bracket</span><span class='hs-layout'>,</span><span class='hs-varid'>bracket_</span><span class='hs-layout'>,</span><span class='hs-varid'>uninterruptibleMask_</span><span class='hs-layout'>,</span><span class='hs-varid'>evaluate</span><span class='hs-layout'>,</span><span class='hs-varid'>mask_</span><span class='hs-layout'>)</span>
<a name="line-45"></a><span class='hs-keyword'>import</span> <span class='hs-conid'>Control</span><span class='hs-varop'>.</span><span class='hs-conid'>Monad</span><span class='hs-layout'>(</span><span class='hs-varid'>when</span><span class='hs-layout'>,</span><span class='hs-varid'>void</span><span class='hs-layout'>)</span>
<a name="line-46"></a><span class='hs-keyword'>import</span> <span class='hs-conid'>Data</span><span class='hs-varop'>.</span><span class='hs-conid'>Maybe</span><span class='hs-layout'>(</span><span class='hs-varid'>fromMaybe</span><span class='hs-layout'>)</span>
<a name="line-47"></a><span class='hs-keyword'>import</span> <span class='hs-conid'>Data</span><span class='hs-varop'>.</span><span class='hs-conid'>Typeable</span><span class='hs-layout'>(</span><span class='hs-conid'>Typeable</span><span class='hs-layout'>)</span>
<a name="line-48"></a><span class='hs-keyword'>import</span> <span class='hs-conid'>Data</span><span class='hs-varop'>.</span><span class='hs-conid'>Word</span><span class='hs-layout'>(</span><span class='hs-conid'>Word</span><span class='hs-layout'>)</span>
<a name="line-49"></a>
<a name="line-50"></a><span class='hs-comment'>{-
<a name="line-51"></a>
<a name="line-52"></a>The only MVars allocated are the three created be 'new'. Their three roles are
<a name="line-53"></a>1) to have a FIFO queue of waiters
<a name="line-54"></a>2) for the head waiter to block on
<a name="line-55"></a>3) to protect the quantity state of the semaphore and the head waiter
<a name="line-56"></a>
<a name="line-57"></a>-}</span>
<a name="line-58"></a>
<a name="line-59"></a><a name="MS"></a><span class='hs-comment'>-- MS has an invariant that "maybe True (> avail) headWants" is always True.</span>
<a name="line-60"></a><a name="MS"></a><span class='hs-keyword'>data</span> <span class='hs-conid'>MS</span> <span class='hs-varid'>i</span> <span class='hs-keyglyph'>=</span> <span class='hs-conid'>MS</span> <span class='hs-layout'>{</span> <span class='hs-varid'>avail</span> <span class='hs-keyglyph'>::</span> <span class='hs-varop'>!</span><span class='hs-varid'>i</span> <span class='hs-comment'>-- ^ This is the quantity available to be taken from the semaphore.</span>
<a name="line-61"></a> <span class='hs-layout'>,</span> <span class='hs-varid'>headWants</span> <span class='hs-keyglyph'>::</span> <span class='hs-varop'>!</span><span class='hs-layout'>(</span><span class='hs-conid'>Maybe</span> <span class='hs-varid'>i</span><span class='hs-layout'>)</span> <span class='hs-comment'>-- ^ If there is waiter then this is Just the amount being waited for.</span>
<a name="line-62"></a> <span class='hs-layout'>}</span>
<a name="line-63"></a> <span class='hs-keyword'>deriving</span> <span class='hs-layout'>(</span><span class='hs-conid'>Eq</span><span class='hs-layout'>,</span><span class='hs-conid'>Typeable</span><span class='hs-layout'>)</span>
<a name="line-64"></a>
<a name="line-65"></a><a name="MSemN"></a><span class='hs-comment'>-- | A 'MSemN' is a quantity semaphore, in which the available quantity may be signalled or</span>
<a name="line-66"></a><a name="MSemN"></a><span class='hs-comment'>-- waited for in arbitrary amounts.</span>
<a name="line-67"></a><a name="MSemN"></a><span class='hs-keyword'>data</span> <span class='hs-conid'>MSemN</span> <span class='hs-varid'>i</span> <span class='hs-keyglyph'>=</span> <span class='hs-conid'>MSemN</span> <span class='hs-layout'>{</span> <span class='hs-varid'>quantityStore</span> <span class='hs-keyglyph'>::</span> <span class='hs-varop'>!</span><span class='hs-layout'>(</span><span class='hs-conid'>MVar</span> <span class='hs-layout'>(</span><span class='hs-conid'>MS</span> <span class='hs-varid'>i</span><span class='hs-layout'>)</span><span class='hs-layout'>)</span> <span class='hs-comment'>-- ^ Used to lock access to state of semaphore quantity.</span>
<a name="line-68"></a> <span class='hs-layout'>,</span> <span class='hs-varid'>queueWait</span> <span class='hs-keyglyph'>::</span> <span class='hs-varop'>!</span><span class='hs-layout'>(</span><span class='hs-conid'>MVar</span> <span class='hs-conid'>()</span><span class='hs-layout'>)</span> <span class='hs-comment'>-- ^ Used as FIFO queue for waiter, held by head of queue.</span>
<a name="line-69"></a> <span class='hs-layout'>,</span> <span class='hs-varid'>headWait</span> <span class='hs-keyglyph'>::</span> <span class='hs-varop'>!</span><span class='hs-layout'>(</span><span class='hs-conid'>MVar</span> <span class='hs-varid'>i</span><span class='hs-layout'>)</span> <span class='hs-comment'>-- ^ The head of the waiter queue blocks on headWait.</span>
<a name="line-70"></a> <span class='hs-layout'>}</span>
<a name="line-71"></a> <span class='hs-keyword'>deriving</span> <span class='hs-layout'>(</span><span class='hs-conid'>Eq</span><span class='hs-layout'>,</span><span class='hs-conid'>Typeable</span><span class='hs-layout'>)</span>
<a name="line-72"></a>
<a name="line-73"></a><a name="new"></a><span class='hs-comment'>-- |'new' allows positive, zero, and negative initial values. The initial value is forced here to</span>
<a name="line-74"></a><span class='hs-comment'>-- better localize errors.</span>
<a name="line-75"></a><span class='hs-definition'>new</span> <span class='hs-keyglyph'>::</span> <span class='hs-conid'>Integral</span> <span class='hs-varid'>i</span> <span class='hs-keyglyph'>=></span> <span class='hs-varid'>i</span> <span class='hs-keyglyph'>-></span> <span class='hs-conid'>IO</span> <span class='hs-layout'>(</span><span class='hs-conid'>MSemN</span> <span class='hs-varid'>i</span><span class='hs-layout'>)</span>
<a name="line-76"></a><span class='hs-comment'>{-# SPECIALIZE new :: Int -> IO (MSemN Int) #-}</span>
<a name="line-77"></a><span class='hs-comment'>{-# SPECIALIZE new :: Word -> IO (MSemN Word) #-}</span>
<a name="line-78"></a><span class='hs-comment'>{-# SPECIALIZE new :: Integer -> IO (MSemN Integer) #-}</span>
<a name="line-79"></a><span class='hs-definition'>new</span> <span class='hs-varid'>initial</span> <span class='hs-keyglyph'>=</span> <span class='hs-keyword'>do</span>
<a name="line-80"></a> <span class='hs-varid'>newMS</span> <span class='hs-keyglyph'><-</span> <span class='hs-varid'>newMVar</span> <span class='hs-varop'>$!</span> <span class='hs-layout'>(</span><span class='hs-conid'>MS</span> <span class='hs-layout'>{</span> <span class='hs-varid'>avail</span> <span class='hs-keyglyph'>=</span> <span class='hs-varid'>initial</span> <span class='hs-comment'>-- this forces 'initial'</span>
<a name="line-81"></a> <span class='hs-layout'>,</span> <span class='hs-varid'>headWants</span> <span class='hs-keyglyph'>=</span> <span class='hs-conid'>Nothing</span> <span class='hs-layout'>}</span><span class='hs-layout'>)</span>
<a name="line-82"></a> <span class='hs-varid'>newQueueWait</span> <span class='hs-keyglyph'><-</span> <span class='hs-varid'>newMVar</span> <span class='hs-conid'>()</span>
<a name="line-83"></a> <span class='hs-varid'>newHeadWait</span> <span class='hs-keyglyph'><-</span> <span class='hs-varid'>newEmptyMVar</span>
<a name="line-84"></a> <span class='hs-varid'>return</span> <span class='hs-layout'>(</span><span class='hs-conid'>MSemN</span> <span class='hs-layout'>{</span> <span class='hs-varid'>quantityStore</span> <span class='hs-keyglyph'>=</span> <span class='hs-varid'>newMS</span>
<a name="line-85"></a> <span class='hs-layout'>,</span> <span class='hs-varid'>queueWait</span> <span class='hs-keyglyph'>=</span> <span class='hs-varid'>newQueueWait</span>
<a name="line-86"></a> <span class='hs-layout'>,</span> <span class='hs-varid'>headWait</span> <span class='hs-keyglyph'>=</span> <span class='hs-varid'>newHeadWait</span> <span class='hs-layout'>}</span><span class='hs-layout'>)</span>
<a name="line-87"></a>
<a name="line-88"></a><a name="with"></a><span class='hs-comment'>-- | 'with' takes a quantity of the semaphore to take and hold while performing the provided</span>
<a name="line-89"></a><span class='hs-comment'>-- operation. 'with' ensures the quantity of the sempahore cannot be lost if there are exceptions.</span>
<a name="line-90"></a><span class='hs-comment'>-- This uses 'bracket' to ensure 'wait' and 'signal' get called correctly.</span>
<a name="line-91"></a><span class='hs-definition'>with</span> <span class='hs-keyglyph'>::</span> <span class='hs-conid'>Integral</span> <span class='hs-varid'>i</span> <span class='hs-keyglyph'>=></span> <span class='hs-conid'>MSemN</span> <span class='hs-varid'>i</span> <span class='hs-keyglyph'>-></span> <span class='hs-varid'>i</span> <span class='hs-keyglyph'>-></span> <span class='hs-conid'>IO</span> <span class='hs-varid'>a</span> <span class='hs-keyglyph'>-></span> <span class='hs-conid'>IO</span> <span class='hs-varid'>a</span>
<a name="line-92"></a><span class='hs-comment'>{-# SPECIALIZE with :: MSemN Int -> Int -> IO a -> IO a #-}</span>
<a name="line-93"></a><span class='hs-comment'>{-# SPECIALIZE with :: MSemN Word -> Word -> IO a -> IO a #-}</span>
<a name="line-94"></a><span class='hs-comment'>{-# SPECIALIZE with :: MSemN Integer -> Integer -> IO a -> IO a #-}</span>
<a name="line-95"></a><span class='hs-definition'>with</span> <span class='hs-varid'>m</span> <span class='hs-varid'>wanted</span> <span class='hs-keyglyph'>=</span> <span class='hs-varid'>seq</span> <span class='hs-varid'>wanted</span> <span class='hs-varop'>$</span> <span class='hs-varid'>bracket_</span> <span class='hs-layout'>(</span><span class='hs-varid'>wait</span> <span class='hs-varid'>m</span> <span class='hs-varid'>wanted</span><span class='hs-layout'>)</span> <span class='hs-layout'>(</span><span class='hs-varid'>uninterruptibleMask_</span> <span class='hs-varop'>$</span> <span class='hs-varid'>signal</span> <span class='hs-varid'>m</span> <span class='hs-varid'>wanted</span><span class='hs-layout'>)</span>
<a name="line-96"></a>
<a name="line-97"></a><a name="withF"></a><span class='hs-comment'>-- | 'withF' takes a pure function and an operation. The pure function converts the available</span>
<a name="line-98"></a><span class='hs-comment'>-- quantity to a pair of the wanted quantity and a returned value. The operation takes the result</span>
<a name="line-99"></a><span class='hs-comment'>-- of the pure function. 'withF' ensures the quantity of the sempahore cannot be lost if there</span>
<a name="line-100"></a><span class='hs-comment'>-- are exceptions. This uses 'bracket' to ensure 'waitF' and 'signal' get called correctly.</span>
<a name="line-101"></a><span class='hs-comment'>--</span>
<a name="line-102"></a><span class='hs-comment'>-- Note: A long running pure function will block all other access to the 'MSemN' while it is</span>
<a name="line-103"></a><span class='hs-comment'>-- evaluated.</span>
<a name="line-104"></a><span class='hs-definition'>withF</span> <span class='hs-keyglyph'>::</span> <span class='hs-conid'>Integral</span> <span class='hs-varid'>i</span>
<a name="line-105"></a> <span class='hs-keyglyph'>=></span> <span class='hs-conid'>MSemN</span> <span class='hs-varid'>i</span>
<a name="line-106"></a> <span class='hs-keyglyph'>-></span> <span class='hs-layout'>(</span><span class='hs-varid'>i</span> <span class='hs-keyglyph'>-></span> <span class='hs-layout'>(</span><span class='hs-varid'>i</span><span class='hs-layout'>,</span><span class='hs-varid'>b</span><span class='hs-layout'>)</span><span class='hs-layout'>)</span>
<a name="line-107"></a> <span class='hs-keyglyph'>-></span> <span class='hs-layout'>(</span><span class='hs-layout'>(</span><span class='hs-varid'>i</span><span class='hs-layout'>,</span><span class='hs-varid'>b</span><span class='hs-layout'>)</span> <span class='hs-keyglyph'>-></span> <span class='hs-conid'>IO</span> <span class='hs-varid'>a</span><span class='hs-layout'>)</span>
<a name="line-108"></a> <span class='hs-keyglyph'>-></span> <span class='hs-conid'>IO</span> <span class='hs-varid'>a</span>
<a name="line-109"></a><span class='hs-comment'>{-# SPECIALIZE withF :: MSemN Int -> (Int -> (Int,b)) -> ((Int,b) -> IO a) -> IO a #-}</span>
<a name="line-110"></a><span class='hs-comment'>{-# SPECIALIZE withF :: MSemN Word -> (Word -> (Word,b)) -> ((Word,b) -> IO a) -> IO a #-}</span>
<a name="line-111"></a><span class='hs-comment'>{-# SPECIALIZE withF :: MSemN Integer -> (Integer -> (Integer,b)) -> ((Integer,b) -> IO a) -> IO a #-}</span>
<a name="line-112"></a><span class='hs-definition'>withF</span> <span class='hs-varid'>m</span> <span class='hs-varid'>f</span> <span class='hs-keyglyph'>=</span> <span class='hs-varid'>bracket</span> <span class='hs-layout'>(</span><span class='hs-varid'>waitF</span> <span class='hs-varid'>m</span> <span class='hs-varid'>f</span><span class='hs-layout'>)</span> <span class='hs-layout'>(</span><span class='hs-keyglyph'>\</span><span class='hs-layout'>(</span><span class='hs-varid'>wanted</span><span class='hs-layout'>,</span><span class='hs-keyword'>_</span><span class='hs-layout'>)</span> <span class='hs-keyglyph'>-></span> <span class='hs-varid'>uninterruptibleMask_</span> <span class='hs-varop'>$</span> <span class='hs-varid'>signal</span> <span class='hs-varid'>m</span> <span class='hs-varid'>wanted</span><span class='hs-layout'>)</span>
<a name="line-113"></a>
<a name="line-114"></a><a name="wait"></a><span class='hs-comment'>-- |'wait' allow positive, zero, and negative wanted values. Waiters may block, and will be handled</span>
<a name="line-115"></a><span class='hs-comment'>-- fairly in FIFO order.</span>
<a name="line-116"></a><span class='hs-comment'>--</span>
<a name="line-117"></a><span class='hs-comment'>-- If 'wait' returns without interruption then it left the 'MSemN' with a remaining quantity that was</span>
<a name="line-118"></a><span class='hs-comment'>-- greater than or equal to zero. If 'wait' is interrupted then no quantity is lost. If 'wait'</span>
<a name="line-119"></a><span class='hs-comment'>-- returns without interruption then it is known that each earlier waiter has definitely either been</span>
<a name="line-120"></a><span class='hs-comment'>-- interrupted or has retured without interruption.</span>
<a name="line-121"></a><span class='hs-definition'>wait</span> <span class='hs-keyglyph'>::</span> <span class='hs-conid'>Integral</span> <span class='hs-varid'>i</span> <span class='hs-keyglyph'>=></span> <span class='hs-conid'>MSemN</span> <span class='hs-varid'>i</span> <span class='hs-keyglyph'>-></span> <span class='hs-varid'>i</span> <span class='hs-keyglyph'>-></span> <span class='hs-conid'>IO</span> <span class='hs-conid'>()</span>
<a name="line-122"></a><span class='hs-comment'>{-# SPECIALIZE wait :: MSemN Int -> Int -> IO () #-}</span>
<a name="line-123"></a><span class='hs-comment'>{-# SPECIALIZE wait :: MSemN Word -> Word -> IO () #-}</span>
<a name="line-124"></a><span class='hs-comment'>{-# SPECIALIZE wait :: MSemN Integer -> Integer -> IO () #-}</span>
<a name="line-125"></a><span class='hs-definition'>wait</span> <span class='hs-varid'>m</span> <span class='hs-varid'>wanted</span> <span class='hs-keyglyph'>=</span> <span class='hs-varid'>seq</span> <span class='hs-varid'>wanted</span> <span class='hs-varop'>$</span> <span class='hs-varid'>fmap</span> <span class='hs-varid'>snd</span> <span class='hs-varop'>$</span> <span class='hs-varid'>waitF</span> <span class='hs-varid'>m</span> <span class='hs-layout'>(</span><span class='hs-varid'>const</span> <span class='hs-layout'>(</span><span class='hs-varid'>wanted</span><span class='hs-layout'>,</span><span class='hs-conid'>()</span><span class='hs-layout'>)</span><span class='hs-layout'>)</span>
<a name="line-126"></a>
<a name="line-127"></a><a name="waitF"></a><span class='hs-comment'>-- | 'waitWith' takes the 'MSemN' and a pure function that takes the available quantity and computes the</span>
<a name="line-128"></a><span class='hs-comment'>-- amount wanted and a second value. The value wanted is stricly evaluated but the second value is</span>
<a name="line-129"></a><span class='hs-comment'>-- returned lazily.</span>
<a name="line-130"></a><span class='hs-comment'>--</span>
<a name="line-131"></a><span class='hs-comment'>-- 'waitF' allow positive, zero, and negative wanted values. Waiters may block, and will be handled</span>
<a name="line-132"></a><span class='hs-comment'>-- fairly in FIFO order.</span>
<a name="line-133"></a><span class='hs-comment'>--</span>
<a name="line-134"></a><span class='hs-comment'>-- If 'waitF' returns without interruption then it left the 'MSemN' with a remaining quantity that was</span>
<a name="line-135"></a><span class='hs-comment'>-- greater than or equal to zero. If 'waitF' or the provided function are interrupted then no</span>
<a name="line-136"></a><span class='hs-comment'>-- quantity is lost. If 'waitF' returns without interruption then it is known that each previous</span>
<a name="line-137"></a><span class='hs-comment'>-- waiter has each definitely either been interrupted or has retured without interruption.</span>
<a name="line-138"></a><span class='hs-comment'>--</span>
<a name="line-139"></a><span class='hs-comment'>-- Note: A long running pure function will block all other access to the 'MSemN' while it is</span>
<a name="line-140"></a><span class='hs-comment'>-- evaluated.</span>
<a name="line-141"></a><span class='hs-definition'>waitF</span> <span class='hs-keyglyph'>::</span> <span class='hs-conid'>Integral</span> <span class='hs-varid'>i</span> <span class='hs-keyglyph'>=></span> <span class='hs-conid'>MSemN</span> <span class='hs-varid'>i</span> <span class='hs-keyglyph'>-></span> <span class='hs-layout'>(</span><span class='hs-varid'>i</span> <span class='hs-keyglyph'>-></span> <span class='hs-layout'>(</span><span class='hs-varid'>i</span><span class='hs-layout'>,</span><span class='hs-varid'>b</span><span class='hs-layout'>)</span><span class='hs-layout'>)</span> <span class='hs-keyglyph'>-></span> <span class='hs-conid'>IO</span> <span class='hs-layout'>(</span><span class='hs-varid'>i</span><span class='hs-layout'>,</span><span class='hs-varid'>b</span><span class='hs-layout'>)</span>
<a name="line-142"></a><span class='hs-comment'>{-# SPECIALIZE waitF :: MSemN Int -> (Int -> (Int,b)) -> IO (Int,b) #-}</span>
<a name="line-143"></a><span class='hs-comment'>{-# SPECIALIZE waitF :: MSemN Word -> (Word -> (Word,b)) -> IO (Word,b) #-}</span>
<a name="line-144"></a><span class='hs-comment'>{-# SPECIALIZE waitF :: MSemN Integer -> (Integer -> (Integer,b)) -> IO (Integer,b) #-}</span>
<a name="line-145"></a><span class='hs-definition'>waitF</span> <span class='hs-varid'>m</span> <span class='hs-varid'>f</span> <span class='hs-keyglyph'>=</span> <span class='hs-varid'>seq</span> <span class='hs-varid'>f</span> <span class='hs-varop'>$</span> <span class='hs-varid'>mask_</span> <span class='hs-varop'>.</span> <span class='hs-varid'>withMVar</span> <span class='hs-layout'>(</span><span class='hs-varid'>queueWait</span> <span class='hs-varid'>m</span><span class='hs-layout'>)</span> <span class='hs-varop'>$</span> <span class='hs-keyglyph'>\</span> <span class='hs-conid'>()</span> <span class='hs-keyglyph'>-></span> <span class='hs-keyword'>do</span>
<a name="line-146"></a> <span class='hs-layout'>(</span><span class='hs-varid'>out</span><span class='hs-layout'>,</span><span class='hs-varid'>mustWait</span><span class='hs-layout'>)</span> <span class='hs-keyglyph'><-</span> <span class='hs-varid'>modifyMVar</span> <span class='hs-layout'>(</span><span class='hs-varid'>quantityStore</span> <span class='hs-varid'>m</span><span class='hs-layout'>)</span> <span class='hs-varop'>$</span> <span class='hs-keyglyph'>\</span> <span class='hs-varid'>ms</span> <span class='hs-keyglyph'>-></span> <span class='hs-keyword'>do</span>
<a name="line-147"></a> <span class='hs-comment'>-- Assume: ((headWait is empty) OR (headWants is Nothing))</span>
<a name="line-148"></a> <span class='hs-comment'>-- Nothing in this scope can block</span>
<a name="line-149"></a> <span class='hs-comment'>--</span>
<a name="line-150"></a> <span class='hs-comment'>-- headWait might be full here if the predecessor waitF blocked and died and signal (tried to)</span>
<a name="line-151"></a> <span class='hs-comment'>-- feed it.</span>
<a name="line-152"></a> <span class='hs-varid'>recovered</span> <span class='hs-keyglyph'><-</span> <span class='hs-varid'>fmap</span> <span class='hs-layout'>(</span><span class='hs-varid'>fromMaybe</span> <span class='hs-num'>0</span><span class='hs-layout'>)</span> <span class='hs-layout'>(</span><span class='hs-varid'>tryTakeMVar</span> <span class='hs-layout'>(</span><span class='hs-varid'>headWait</span> <span class='hs-varid'>m</span><span class='hs-layout'>)</span><span class='hs-layout'>)</span>
<a name="line-153"></a> <span class='hs-keyword'>let</span> <span class='hs-varid'>total</span> <span class='hs-keyglyph'>=</span> <span class='hs-varid'>avail</span> <span class='hs-varid'>ms</span> <span class='hs-varop'>+</span> <span class='hs-varid'>recovered</span>
<a name="line-154"></a> <span class='hs-varid'>outVal</span><span class='hs-keyglyph'>@</span><span class='hs-layout'>(</span><span class='hs-varid'>wantedVal</span><span class='hs-layout'>,</span><span class='hs-keyword'>_</span><span class='hs-layout'>)</span> <span class='hs-keyglyph'>=</span> <span class='hs-varid'>f</span> <span class='hs-varid'>total</span>
<a name="line-155"></a> <span class='hs-keyword'>if</span> <span class='hs-varid'>wantedVal</span> <span class='hs-varop'><=</span> <span class='hs-varid'>total</span> <span class='hs-comment'>-- forces wantedVal</span>
<a name="line-156"></a> <span class='hs-keyword'>then</span> <span class='hs-keyword'>do</span>
<a name="line-157"></a> <span class='hs-varid'>ms'</span> <span class='hs-keyglyph'><-</span> <span class='hs-varid'>evaluate</span> <span class='hs-conid'>MS</span> <span class='hs-layout'>{</span> <span class='hs-varid'>avail</span> <span class='hs-keyglyph'>=</span> <span class='hs-varid'>total</span> <span class='hs-comment'>-</span> <span class='hs-varid'>wantedVal</span><span class='hs-layout'>,</span> <span class='hs-varid'>headWants</span> <span class='hs-keyglyph'>=</span> <span class='hs-conid'>Nothing</span> <span class='hs-layout'>}</span>
<a name="line-158"></a> <span class='hs-varid'>return</span> <span class='hs-layout'>(</span><span class='hs-varid'>ms'</span><span class='hs-layout'>,</span> <span class='hs-layout'>(</span><span class='hs-varid'>outVal</span><span class='hs-layout'>,</span><span class='hs-conid'>False</span><span class='hs-layout'>)</span><span class='hs-layout'>)</span>
<a name="line-159"></a> <span class='hs-keyword'>else</span> <span class='hs-keyword'>do</span>
<a name="line-160"></a> <span class='hs-varid'>ms'</span> <span class='hs-keyglyph'><-</span> <span class='hs-varid'>evaluate</span> <span class='hs-conid'>MS</span> <span class='hs-layout'>{</span> <span class='hs-varid'>avail</span> <span class='hs-keyglyph'>=</span> <span class='hs-varid'>total</span><span class='hs-layout'>,</span> <span class='hs-varid'>headWants</span> <span class='hs-keyglyph'>=</span> <span class='hs-conid'>Just</span> <span class='hs-varid'>wantedVal</span> <span class='hs-layout'>}</span>
<a name="line-161"></a> <span class='hs-varid'>return</span> <span class='hs-layout'>(</span><span class='hs-varid'>ms'</span><span class='hs-layout'>,</span> <span class='hs-layout'>(</span><span class='hs-varid'>outVal</span><span class='hs-layout'>,</span><span class='hs-conid'>True</span><span class='hs-layout'>)</span><span class='hs-layout'>)</span>
<a name="line-162"></a> <span class='hs-comment'>-- quantityStore is now released, queueWait is still held, race with signal now possible</span>
<a name="line-163"></a> <span class='hs-comment'>-- Assert: (headWait is empty) AND (mustWait == (headWants is Just)) at release</span>
<a name="line-164"></a> <span class='hs-comment'>-- Proof: tryTakeMVar forced (headWait is empty), and</span>
<a name="line-165"></a> <span class='hs-comment'>-- the if-then-else branches ensured (mustWait == (headWants is Just))</span>
<a name="line-166"></a> <span class='hs-comment'>-- This assertion implies ((headWait is empty) OR (headWants is Nothing)) invariant holds (point X)</span>
<a name="line-167"></a> <span class='hs-varid'>when</span> <span class='hs-varid'>mustWait</span> <span class='hs-layout'>(</span><span class='hs-varid'>void</span> <span class='hs-layout'>(</span><span class='hs-varid'>takeMVar</span> <span class='hs-layout'>(</span><span class='hs-varid'>headWait</span> <span class='hs-varid'>m</span><span class='hs-layout'>)</span><span class='hs-layout'>)</span><span class='hs-layout'>)</span>
<a name="line-168"></a> <span class='hs-varid'>return</span> <span class='hs-varid'>out</span>
<a name="line-169"></a> <span class='hs-comment'>-- Invariant: ((headWait is empty) OR (headWants is Nothing))</span>
<a name="line-170"></a> <span class='hs-comment'>-- Proof: 1) mustWait was false</span>
<a name="line-171"></a> <span class='hs-comment'>-- nothing happened since (point X) except perhaps race with signal</span>
<a name="line-172"></a> <span class='hs-comment'>-- signal maintained invariant</span>
<a name="line-173"></a> <span class='hs-comment'>-- 2) mustWait was true</span>
<a name="line-174"></a> <span class='hs-comment'>-- 2a) takeMVar succeeded so headWait became full since (point X)</span>
<a name="line-175"></a> <span class='hs-comment'>-- this implies signal filled headWait and thus signal ended with (headWait is full)</span>
<a name="line-176"></a> <span class='hs-comment'>-- signal invariant ((headWait is empty) OR (headWants is Nothing)) implies (headWants is Nothing) was set</span>
<a name="line-177"></a> <span class='hs-comment'>-- (headWait is empty) by takeMVar and (headWants is Nothing) by implication</span>
<a name="line-178"></a> <span class='hs-comment'>-- 2b) takeMVar was interrupted and thus did nothing</span>
<a name="line-179"></a> <span class='hs-comment'>-- nothing happened since (point X) except perhaps race with signal</span>
<a name="line-180"></a> <span class='hs-comment'>-- signal maintained invariant</span>
<a name="line-181"></a>
<a name="line-182"></a><a name="signal"></a><span class='hs-comment'>-- |'signal' allows positive, zero, and negative values, thus this is also way to remove quantity</span>
<a name="line-183"></a><span class='hs-comment'>-- that skips any threads in the 'wait'/'waitF' queue. If the new total is greater than the next</span>
<a name="line-184"></a><span class='hs-comment'>-- value being waited for (if present) then the first waiter is woken. If there are queued waiters</span>
<a name="line-185"></a><span class='hs-comment'>-- then the next one will wake after a waiter has proceeded and notice the remaining value; thus a</span>
<a name="line-186"></a><span class='hs-comment'>-- single 'signal' may result in several waiters obtaining values. Waking waiting threads is</span>
<a name="line-187"></a><span class='hs-comment'>-- asynchronous.</span>
<a name="line-188"></a><span class='hs-comment'>--</span>
<a name="line-189"></a><span class='hs-comment'>-- 'signal' may block, but it cannot be interrupted, which allows it to dependably restore value to</span>
<a name="line-190"></a><span class='hs-comment'>-- the 'MSemN'. All 'signal', 'signalF', 'peekAvail', and the head waiter may momentarily block in a</span>
<a name="line-191"></a><span class='hs-comment'>-- fair FIFO manner.</span>
<a name="line-192"></a><span class='hs-definition'>signal</span> <span class='hs-keyglyph'>::</span> <span class='hs-conid'>Integral</span> <span class='hs-varid'>i</span> <span class='hs-keyglyph'>=></span> <span class='hs-conid'>MSemN</span> <span class='hs-varid'>i</span> <span class='hs-keyglyph'>-></span> <span class='hs-varid'>i</span> <span class='hs-keyglyph'>-></span> <span class='hs-conid'>IO</span> <span class='hs-conid'>()</span>
<a name="line-193"></a><span class='hs-comment'>{-# SPECIALIZE signal :: MSemN Int -> Int -> IO () #-}</span>
<a name="line-194"></a><span class='hs-comment'>{-# SPECIALIZE signal :: MSemN Word -> Word -> IO () #-}</span>
<a name="line-195"></a><span class='hs-comment'>{-# SPECIALIZE signal :: MSemN Integer -> Integer -> IO () #-}</span>
<a name="line-196"></a><span class='hs-definition'>signal</span> <span class='hs-keyword'>_</span> <span class='hs-num'>0</span> <span class='hs-keyglyph'>=</span> <span class='hs-varid'>return</span> <span class='hs-conid'>()</span> <span class='hs-comment'>-- this case forces 'size'</span>
<a name="line-197"></a><span class='hs-definition'>signal</span> <span class='hs-varid'>m</span> <span class='hs-varid'>size</span> <span class='hs-keyglyph'>=</span> <span class='hs-varid'>fmap</span> <span class='hs-varid'>snd</span> <span class='hs-varop'>$</span> <span class='hs-varid'>signalF</span> <span class='hs-varid'>m</span> <span class='hs-layout'>(</span><span class='hs-varid'>const</span> <span class='hs-layout'>(</span><span class='hs-varid'>size</span><span class='hs-layout'>,</span><span class='hs-conid'>()</span><span class='hs-layout'>)</span><span class='hs-layout'>)</span>
<a name="line-198"></a>
<a name="line-199"></a><a name="signalF"></a><span class='hs-comment'>-- | Instead of providing a fixed change to the available quantity, 'signalF' applies a provided</span>
<a name="line-200"></a><span class='hs-comment'>-- pure function to the available quantity to compute the change and a second value. The</span>
<a name="line-201"></a><span class='hs-comment'>-- requested change is stricly evaluated but the second value is returned lazily. If the new total is</span>
<a name="line-202"></a><span class='hs-comment'>-- greater than the next value being waited for then the first waiter is woken. If there are queued</span>
<a name="line-203"></a><span class='hs-comment'>-- waiters then the next one will wake after a waiter has proceeded and notice the remaining value;</span>
<a name="line-204"></a><span class='hs-comment'>-- thus a single 'signalF' may result in several waiters obtaining values. Waking waiting threads</span>
<a name="line-205"></a><span class='hs-comment'>-- is asynchronous.</span>
<a name="line-206"></a><span class='hs-comment'>--</span>
<a name="line-207"></a><span class='hs-comment'>-- 'signalF' may block, and it can be safely interrupted. If the provided function throws an error</span>
<a name="line-208"></a><span class='hs-comment'>-- or is interrupted then it leaves the 'MSemN' unchanged. All 'signal', 'signalF', 'peekAvail', and</span>
<a name="line-209"></a><span class='hs-comment'>-- the head waiter may momentarily block in a fair FIFO manner.</span>
<a name="line-210"></a><span class='hs-comment'>--</span>
<a name="line-211"></a><span class='hs-comment'>-- Note: A long running pure function will block all other access to the 'MSemN' while it is</span>
<a name="line-212"></a><span class='hs-comment'>-- evaluated.</span>
<a name="line-213"></a><span class='hs-definition'>signalF</span> <span class='hs-keyglyph'>::</span> <span class='hs-conid'>Integral</span> <span class='hs-varid'>i</span>
<a name="line-214"></a> <span class='hs-keyglyph'>=></span> <span class='hs-conid'>MSemN</span> <span class='hs-varid'>i</span>
<a name="line-215"></a> <span class='hs-keyglyph'>-></span> <span class='hs-layout'>(</span><span class='hs-varid'>i</span> <span class='hs-keyglyph'>-></span> <span class='hs-layout'>(</span><span class='hs-varid'>i</span><span class='hs-layout'>,</span><span class='hs-varid'>b</span><span class='hs-layout'>)</span><span class='hs-layout'>)</span>
<a name="line-216"></a> <span class='hs-keyglyph'>-></span> <span class='hs-conid'>IO</span> <span class='hs-layout'>(</span><span class='hs-varid'>i</span><span class='hs-layout'>,</span><span class='hs-varid'>b</span><span class='hs-layout'>)</span>
<a name="line-217"></a><span class='hs-comment'>{-# SPECIALIZE signalF :: MSemN Int -> (Int -> (Int,b)) -> IO (Int,b) #-}</span>
<a name="line-218"></a><span class='hs-comment'>{-# SPECIALIZE signalF :: MSemN Word -> (Word -> (Word,b)) -> IO (Word,b) #-}</span>
<a name="line-219"></a><span class='hs-comment'>{-# SPECIALIZE signalF :: MSemN Integer -> (Integer -> (Integer,b)) -> IO (Integer,b) #-}</span>
<a name="line-220"></a><span class='hs-definition'>signalF</span> <span class='hs-varid'>m</span> <span class='hs-varid'>f</span> <span class='hs-keyglyph'>=</span> <span class='hs-varid'>seq</span> <span class='hs-varid'>f</span> <span class='hs-varop'>$</span> <span class='hs-varid'>mask_</span> <span class='hs-varop'>.</span> <span class='hs-varid'>modifyMVar</span> <span class='hs-layout'>(</span><span class='hs-varid'>quantityStore</span> <span class='hs-varid'>m</span><span class='hs-layout'>)</span> <span class='hs-varop'>$</span> <span class='hs-keyglyph'>\</span> <span class='hs-varid'>ms</span> <span class='hs-keyglyph'>-></span> <span class='hs-keyword'>do</span>
<a name="line-221"></a> <span class='hs-comment'>-- Assume: ((headWait is empty) OR (headWants is Nothing))</span>
<a name="line-222"></a> <span class='hs-comment'>-- Nothing in this scope can block</span>
<a name="line-223"></a> <span class='hs-keyword'>let</span> <span class='hs-varid'>out</span><span class='hs-keyglyph'>@</span><span class='hs-layout'>(</span><span class='hs-varid'>size</span><span class='hs-layout'>,</span><span class='hs-keyword'>_</span><span class='hs-layout'>)</span> <span class='hs-keyglyph'>=</span> <span class='hs-varid'>f</span> <span class='hs-layout'>(</span><span class='hs-varid'>avail</span> <span class='hs-varid'>ms</span><span class='hs-layout'>)</span>
<a name="line-224"></a> <span class='hs-varid'>ms'</span> <span class='hs-keyglyph'><-</span> <span class='hs-keyword'>case</span> <span class='hs-varid'>headWants</span> <span class='hs-varid'>ms</span> <span class='hs-keyword'>of</span>
<a name="line-225"></a> <span class='hs-conid'>Nothing</span> <span class='hs-keyglyph'>-></span> <span class='hs-varid'>evaluate</span> <span class='hs-varid'>ms</span> <span class='hs-layout'>{</span> <span class='hs-varid'>avail</span> <span class='hs-keyglyph'>=</span> <span class='hs-varid'>avail</span> <span class='hs-varid'>ms</span> <span class='hs-varop'>+</span> <span class='hs-varid'>size</span> <span class='hs-layout'>}</span>
<a name="line-226"></a> <span class='hs-conid'>Just</span> <span class='hs-varid'>wantedVal</span> <span class='hs-keyglyph'>-></span> <span class='hs-keyword'>do</span>
<a name="line-227"></a> <span class='hs-comment'>-- Because headWants is Just _ the assumption implies headWait is empty</span>
<a name="line-228"></a> <span class='hs-keyword'>let</span> <span class='hs-varid'>total</span> <span class='hs-keyglyph'>=</span> <span class='hs-varid'>avail</span> <span class='hs-varid'>ms</span> <span class='hs-varop'>+</span> <span class='hs-varid'>size</span>
<a name="line-229"></a> <span class='hs-keyword'>if</span> <span class='hs-varid'>wantedVal</span> <span class='hs-varop'><=</span> <span class='hs-varid'>total</span>
<a name="line-230"></a> <span class='hs-keyword'>then</span> <span class='hs-keyword'>do</span>
<a name="line-231"></a> <span class='hs-sel'>_didPlace</span> <span class='hs-keyglyph'><-</span> <span class='hs-varid'>tryPutMVar</span> <span class='hs-layout'>(</span><span class='hs-varid'>headWait</span> <span class='hs-varid'>m</span><span class='hs-layout'>)</span> <span class='hs-varid'>wantedVal</span> <span class='hs-comment'>-- _didPlace is always True</span>
<a name="line-232"></a> <span class='hs-varid'>evaluate</span> <span class='hs-conid'>MS</span> <span class='hs-layout'>{</span> <span class='hs-varid'>avail</span> <span class='hs-keyglyph'>=</span> <span class='hs-varid'>total</span> <span class='hs-comment'>-</span> <span class='hs-varid'>wantedVal</span><span class='hs-layout'>,</span> <span class='hs-varid'>headWants</span> <span class='hs-keyglyph'>=</span> <span class='hs-conid'>Nothing</span> <span class='hs-layout'>}</span>
<a name="line-233"></a> <span class='hs-keyword'>else</span> <span class='hs-keyword'>do</span>
<a name="line-234"></a> <span class='hs-varid'>evaluate</span> <span class='hs-varid'>ms</span> <span class='hs-layout'>{</span> <span class='hs-varid'>avail</span> <span class='hs-keyglyph'>=</span> <span class='hs-varid'>total</span> <span class='hs-layout'>}</span>
<a name="line-235"></a> <span class='hs-varid'>return</span> <span class='hs-layout'>(</span><span class='hs-varid'>ms'</span><span class='hs-layout'>,</span><span class='hs-varid'>out</span><span class='hs-layout'>)</span>
<a name="line-236"></a> <span class='hs-comment'>-- Invariant: ((headWait is empty) OR (headWants is Nothing))</span>
<a name="line-237"></a> <span class='hs-comment'>-- Proof: Assume invariant originally holds when taking quantityStore</span>
<a name="line-238"></a> <span class='hs-comment'>-- 1) headWants originally Nothing, headWants and headWait unchanged, invariant still holds</span>
<a name="line-239"></a> <span class='hs-comment'>-- 2) headWants originally Just _ implies, by assumption, that (headWait is empty)</span>
<a name="line-240"></a> <span class='hs-comment'>-- if-then-branch: headWants changed to Nothing and headWait changed to filled, invariant satisfied</span>
<a name="line-241"></a> <span class='hs-comment'>-- if-else-branch: headWants and headWait unchanged, invariant still holds</span>
<a name="line-242"></a>
<a name="line-243"></a><a name="peekAvail"></a><span class='hs-comment'>-- | 'peekAvail' skips the queue of any blocked 'wait' and 'waitF' threads, but may momentarily</span>
<a name="line-244"></a><span class='hs-comment'>-- block on 'signal', 'signalF', other 'peekAvail', and the head waiter. This returns the amount of</span>
<a name="line-245"></a><span class='hs-comment'>-- value available to be taken. Using this value without producing unwanted race conditions is left</span>
<a name="line-246"></a><span class='hs-comment'>-- up to the programmer.</span>
<a name="line-247"></a><span class='hs-comment'>--</span>
<a name="line-248"></a><span class='hs-comment'>-- 'peekAvail' is an optimized form of \"signalF m (\x -> (0,x))\".</span>
<a name="line-249"></a><span class='hs-comment'>--</span>
<a name="line-250"></a><span class='hs-comment'>-- Quantity that has been passed to a blocked waiter but not picked up is not counted. If the</span>
<a name="line-251"></a><span class='hs-comment'>-- blocked waiter is killed before picking it up then the passed quantity will be recovered by the</span>
<a name="line-252"></a><span class='hs-comment'>-- next waiter. In this exceptional case this next waiter may see an available total that is</span>
<a name="line-253"></a><span class='hs-comment'>-- different than returned by peekAvail.</span>
<a name="line-254"></a><span class='hs-comment'>--</span>
<a name="line-255"></a><span class='hs-comment'>-- A version of 'peekAvail' that joins the FIFO queue of 'wait' and 'waitF' can be acheived by</span>
<a name="line-256"></a><span class='hs-comment'>-- \"waitF m (\x -> (0,x))\" but this will block if x is negative. On the other hand this method</span>
<a name="line-257"></a><span class='hs-comment'>-- will see the total including any recovered quantity.</span>
<a name="line-258"></a><span class='hs-definition'>peekAvail</span> <span class='hs-keyglyph'>::</span> <span class='hs-conid'>Integral</span> <span class='hs-varid'>i</span> <span class='hs-keyglyph'>=></span> <span class='hs-conid'>MSemN</span> <span class='hs-varid'>i</span> <span class='hs-keyglyph'>-></span> <span class='hs-conid'>IO</span> <span class='hs-varid'>i</span>
<a name="line-259"></a><span class='hs-comment'>{-# SPECIALIZE peekAvail :: MSemN Int -> IO Int #-}</span>
<a name="line-260"></a><span class='hs-comment'>{-# SPECIALIZE peekAvail :: MSemN Word -> IO Word #-}</span>
<a name="line-261"></a><span class='hs-comment'>{-# SPECIALIZE peekAvail :: MSemN Integer -> IO Integer #-}</span>
<a name="line-262"></a><span class='hs-definition'>peekAvail</span> <span class='hs-varid'>m</span> <span class='hs-keyglyph'>=</span> <span class='hs-varid'>withMVar</span> <span class='hs-layout'>(</span><span class='hs-varid'>quantityStore</span> <span class='hs-varid'>m</span><span class='hs-layout'>)</span> <span class='hs-layout'>(</span><span class='hs-varid'>return</span> <span class='hs-varop'>.</span> <span class='hs-varid'>avail</span><span class='hs-layout'>)</span>
</pre></body>
</html>
