<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Control.Concurrent.MSemN</title><link href="ocean.css" rel="stylesheet" type="text/css" title="Ocean" /><script src="haddock-util.js" type="text/javascript"></script><script type="text/javascript">//<![CDATA[
window.onload = function () {pageLoad();setSynopsis("mini_Control-Concurrent-MSemN.html");};
//]]>
</script></head><body><div id="package-header"><ul class="links" id="page-menu"><li><a href="src/Control-Concurrent-MSemN.html">Source</a></li><li><a href="index.html">Contents</a></li><li><a href="doc-index.html">Index</a></li></ul><p class="caption">SafeSemaphore-0.9.0: Much safer replacement for QSemN, QSem, and SampleVar</p></div><div id="content"><div id="module-header"><table class="info"><tr><th>Portability</th><td>non-portable (concurrency)</td></tr><tr><th>Stability</th><td>experimental</td></tr><tr><th>Maintainer</th><td>haskell@list.mightyreason.com</td></tr><tr><th>Safe Haskell</th><td>Safe-Infered</td></tr></table><p class="caption">Control.Concurrent.MSemN</p></div><div id="description"><p class="caption">Description</p><div class="doc"><p>Quantity semaphores in which each thread may wait for an arbitrary amount. This modules is
intended to improve on <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/Control-Concurrent-QSemN.html">Control.Concurrent.QSemN</a>.
</p><p>This semaphore gracefully handles threads which die while blocked waiting for quantity. The
fairness guarantee is that blocked threads are FIFO. An early thread waiting for a large
quantity will prevent a later thread waiting for a small quantity from jumping the queue.
</p><p>If <code><a href="Control-Concurrent-MSemN.html#v:with">with</a></code> is used to guard a critical section then no quantity of the semaphore will be lost
if the activity throws an exception.
</p><p>The functions below are generic in (Integral i) with specialization to Int and Integer.
</p><p>Overflow warning: These operations do not check for overflow errors. If the Integral type is too
small to accept the new total then the behavior of these operations is undefined. Using (MSem
Integer) prevents the possibility of an overflow error.
</p></div></div><div id="synopsis"><p id="control.syn" class="caption expander" onclick="toggleSection('syn')">Synopsis</p><ul id="section.syn" class="hide" onclick="toggleSection('syn')"><li class="src short"><span class="keyword">data</span> <a href="#t:MSemN">MSemN</a> i</li><li class="src short"><a href="#v:new">new</a> :: <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/Prelude.html#t:Integral">Integral</a> i => i -> <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/System-IO.html#t:IO">IO</a> (<a href="Control-Concurrent-MSemN.html#t:MSemN">MSemN</a> i)</li><li class="src short"><a href="#v:with">with</a> :: <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/Prelude.html#t:Integral">Integral</a> i => <a href="Control-Concurrent-MSemN.html#t:MSemN">MSemN</a> i -> i -> <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/System-IO.html#t:IO">IO</a> a -> <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/System-IO.html#t:IO">IO</a> a</li><li class="src short"><a href="#v:wait">wait</a> :: <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/Prelude.html#t:Integral">Integral</a> i => <a href="Control-Concurrent-MSemN.html#t:MSemN">MSemN</a> i -> i -> <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/System-IO.html#t:IO">IO</a> <a href="/usr/share/doc/ghc/html/libraries/ghc-prim-0.2.0.0/GHC-Tuple.html#t:-40--41-">()</a></li><li class="src short"><a href="#v:signal">signal</a> :: <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/Prelude.html#t:Integral">Integral</a> i => <a href="Control-Concurrent-MSemN.html#t:MSemN">MSemN</a> i -> i -> <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/System-IO.html#t:IO">IO</a> <a href="/usr/share/doc/ghc/html/libraries/ghc-prim-0.2.0.0/GHC-Tuple.html#t:-40--41-">()</a></li><li class="src short"><a href="#v:withF">withF</a> :: <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/Prelude.html#t:Integral">Integral</a> i => <a href="Control-Concurrent-MSemN.html#t:MSemN">MSemN</a> i -> (i -> (i, b)) -> ((i, b) -> <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/System-IO.html#t:IO">IO</a> a) -> <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/System-IO.html#t:IO">IO</a> a</li><li class="src short"><a href="#v:waitF">waitF</a> :: <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/Prelude.html#t:Integral">Integral</a> i => <a href="Control-Concurrent-MSemN.html#t:MSemN">MSemN</a> i -> (i -> (i, b)) -> <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/System-IO.html#t:IO">IO</a> (i, b)</li><li class="src short"><a href="#v:signalF">signalF</a> :: <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/Prelude.html#t:Integral">Integral</a> i => <a href="Control-Concurrent-MSemN.html#t:MSemN">MSemN</a> i -> (i -> (i, b)) -> <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/System-IO.html#t:IO">IO</a> (i, b)</li><li class="src short"><a href="#v:peekAvail">peekAvail</a> :: <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/Prelude.html#t:Integral">Integral</a> i => <a href="Control-Concurrent-MSemN.html#t:MSemN">MSemN</a> i -> <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/System-IO.html#t:IO">IO</a> i</li></ul></div><div id="interface"><h1>Documentation</h1><div class="top"><p class="src"><span class="keyword">data</span> <a name="t:MSemN" class="def">MSemN</a> i <a href="src/Control-Concurrent-MSemN.html#MSemN" class="link">Source</a></p><div class="doc"><p>A <code><a href="Control-Concurrent-MSemN.html#t:MSemN">MSemN</a></code> is a quantity semaphore, in which the available quantity may be signalled or
waited for in arbitrary amounts.
</p></div><div class="subs instances"><p id="control.i:MSemN" class="caption collapser" onclick="toggleSection('i:MSemN')">Instances</p><div id="section.i:MSemN" class="show"><table><tr><td class="src"><a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/Data-Typeable-Internal.html#t:Typeable1">Typeable1</a> <a href="Control-Concurrent-MSemN.html#t:MSemN">MSemN</a></td><td class="doc empty"> </td></tr><tr><td class="src"><a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/Data-Eq.html#t:Eq">Eq</a> (<a href="Control-Concurrent-MSemN.html#t:MSemN">MSemN</a> i)</td><td class="doc empty"> </td></tr></table></div></div></div><div class="top"><p class="src"><a name="v:new" class="def">new</a> :: <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/Prelude.html#t:Integral">Integral</a> i => i -> <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/System-IO.html#t:IO">IO</a> (<a href="Control-Concurrent-MSemN.html#t:MSemN">MSemN</a> i)<a href="src/Control-Concurrent-MSemN.html#new" class="link">Source</a></p><div class="doc"><p><code><a href="Control-Concurrent-MSemN.html#v:new">new</a></code> allows positive, zero, and negative initial values. The initial value is forced here to
better localize errors.
</p></div></div><div class="top"><p class="src"><a name="v:with" class="def">with</a> :: <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/Prelude.html#t:Integral">Integral</a> i => <a href="Control-Concurrent-MSemN.html#t:MSemN">MSemN</a> i -> i -> <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/System-IO.html#t:IO">IO</a> a -> <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/System-IO.html#t:IO">IO</a> a<a href="src/Control-Concurrent-MSemN.html#with" class="link">Source</a></p><div class="doc"><p><code><a href="Control-Concurrent-MSemN.html#v:with">with</a></code> takes a quantity of the semaphore to take and hold while performing the provided
operation. <code><a href="Control-Concurrent-MSemN.html#v:with">with</a></code> ensures the quantity of the sempahore cannot be lost if there are exceptions.
This uses <code><a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/Control-Exception-Base.html#v:bracket">bracket</a></code> to ensure <code><a href="Control-Concurrent-MSemN.html#v:wait">wait</a></code> and <code><a href="Control-Concurrent-MSemN.html#v:signal">signal</a></code> get called correctly.
</p></div></div><div class="top"><p class="src"><a name="v:wait" class="def">wait</a> :: <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/Prelude.html#t:Integral">Integral</a> i => <a href="Control-Concurrent-MSemN.html#t:MSemN">MSemN</a> i -> i -> <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/System-IO.html#t:IO">IO</a> <a href="/usr/share/doc/ghc/html/libraries/ghc-prim-0.2.0.0/GHC-Tuple.html#t:-40--41-">()</a><a href="src/Control-Concurrent-MSemN.html#wait" class="link">Source</a></p><div class="doc"><p><code><a href="Control-Concurrent-MSemN.html#v:wait">wait</a></code> allow positive, zero, and negative wanted values. Waiters may block, and will be handled
fairly in FIFO order. Waiters will succeed when the wanted value is less than or equal to the
available value. The FIFO order means that a <code><a href="Control-Concurrent-MSemN.html#v:wait">wait</a></code> for a large quantity that blocks will prevent later
requests from being considered even if the later requests would be for a small quantity that could be fulfilled.
</p><p>If <code><a href="Control-Concurrent-MSemN.html#v:wait">wait</a></code> returns without interruption then it left the <code><a href="Control-Concurrent-MSemN.html#t:MSemN">MSemN</a></code> with a remaining quantity that was
greater than or equal to zero. If <code><a href="Control-Concurrent-MSemN.html#v:wait">wait</a></code> is interrupted then no quantity is lost. If <code><a href="Control-Concurrent-MSemN.html#v:wait">wait</a></code>
returns without interruption then it is known that each earlier waiter has definitely either been
interrupted or has retured without interruption.
</p></div></div><div class="top"><p class="src"><a name="v:signal" class="def">signal</a> :: <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/Prelude.html#t:Integral">Integral</a> i => <a href="Control-Concurrent-MSemN.html#t:MSemN">MSemN</a> i -> i -> <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/System-IO.html#t:IO">IO</a> <a href="/usr/share/doc/ghc/html/libraries/ghc-prim-0.2.0.0/GHC-Tuple.html#t:-40--41-">()</a><a href="src/Control-Concurrent-MSemN.html#signal" class="link">Source</a></p><div class="doc"><p><code><a href="Control-Concurrent-MSemN.html#v:signal">signal</a></code> allows positive, zero, and negative values, thus this is also way to remove quantity
that skips any threads in the 'wait'/'waitF' queue. If the new total is greater than the next
value being waited for (if present) then the first waiter is woken. If there are queued waiters
then the next one will wake after a waiter has proceeded and notice the remaining value; thus a
single <code><a href="Control-Concurrent-MSemN.html#v:signal">signal</a></code> may result in several waiters obtaining values. Waking waiting threads is
asynchronous.
</p><p><code><a href="Control-Concurrent-MSemN.html#v:signal">signal</a></code> may block, but it cannot be interrupted, which allows it to dependably restore value to
the <code><a href="Control-Concurrent-MSemN.html#t:MSemN">MSemN</a></code>. All <code><a href="Control-Concurrent-MSemN.html#v:signal">signal</a></code>, <code><a href="Control-Concurrent-MSemN.html#v:signalF">signalF</a></code>, <code><a href="Control-Concurrent-MSemN.html#v:peekAvail">peekAvail</a></code>, and the head waiter may momentarily block in a
fair FIFO manner.
</p></div></div><div class="top"><p class="src"><a name="v:withF" class="def">withF</a> :: <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/Prelude.html#t:Integral">Integral</a> i => <a href="Control-Concurrent-MSemN.html#t:MSemN">MSemN</a> i -> (i -> (i, b)) -> ((i, b) -> <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/System-IO.html#t:IO">IO</a> a) -> <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/System-IO.html#t:IO">IO</a> a<a href="src/Control-Concurrent-MSemN.html#withF" class="link">Source</a></p><div class="doc"><p><code><a href="Control-Concurrent-MSemN.html#v:withF">withF</a></code> takes a pure function and an operation. The pure function converts the available
quantity to a pair of the wanted quantity and a returned value. The operation takes the result
of the pure function. <code><a href="Control-Concurrent-MSemN.html#v:withF">withF</a></code> ensures the quantity of the sempahore cannot be lost if there
are exceptions. This uses <code><a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/Control-Exception-Base.html#v:bracket">bracket</a></code> to ensure <code><a href="Control-Concurrent-MSemN.html#v:waitF">waitF</a></code> and <code><a href="Control-Concurrent-MSemN.html#v:signal">signal</a></code> get called correctly.
</p><p>Note: A long running pure function will block all other access to the <code><a href="Control-Concurrent-MSemN.html#t:MSemN">MSemN</a></code> while it is
evaluated.
</p></div></div><div class="top"><p class="src"><a name="v:waitF" class="def">waitF</a> :: <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/Prelude.html#t:Integral">Integral</a> i => <a href="Control-Concurrent-MSemN.html#t:MSemN">MSemN</a> i -> (i -> (i, b)) -> <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/System-IO.html#t:IO">IO</a> (i, b)<a href="src/Control-Concurrent-MSemN.html#waitF" class="link">Source</a></p><div class="doc"><p><code>waitWith</code> takes the <code><a href="Control-Concurrent-MSemN.html#t:MSemN">MSemN</a></code> and a pure function that takes the available quantity and computes the
amount wanted and a second value. The value wanted is stricly evaluated but the second value is
returned lazily.
</p><p><code><a href="Control-Concurrent-MSemN.html#v:waitF">waitF</a></code> allow positive, zero, and negative wanted values. Waiters may block, and will be handled
fairly in FIFO order. Waiters will succeed when the wanted value is less than or equal to the
available value. The FIFO order means that a <code><a href="Control-Concurrent-MSemN.html#v:waitF">waitF</a></code> for a large quantity that blocks will prevent later
requests from being considered even if the later requests would be for a small quantity that could be fulfilled.
</p><p>If <code><a href="Control-Concurrent-MSemN.html#v:waitF">waitF</a></code> returns without interruption then it left the <code><a href="Control-Concurrent-MSemN.html#t:MSemN">MSemN</a></code> with a remaining quantity that was
greater than or equal to zero. If <code><a href="Control-Concurrent-MSemN.html#v:waitF">waitF</a></code> or the provided function are interrupted then no
quantity is lost. If <code><a href="Control-Concurrent-MSemN.html#v:waitF">waitF</a></code> returns without interruption then it is known that each previous
waiter has each definitely either been interrupted or has retured without interruption.
</p><p>Note: A long running pure function will block all other access to the <code><a href="Control-Concurrent-MSemN.html#t:MSemN">MSemN</a></code> while it is
evaluated.
</p></div></div><div class="top"><p class="src"><a name="v:signalF" class="def">signalF</a> :: <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/Prelude.html#t:Integral">Integral</a> i => <a href="Control-Concurrent-MSemN.html#t:MSemN">MSemN</a> i -> (i -> (i, b)) -> <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/System-IO.html#t:IO">IO</a> (i, b)<a href="src/Control-Concurrent-MSemN.html#signalF" class="link">Source</a></p><div class="doc"><p>Instead of providing a fixed change to the available quantity, <code><a href="Control-Concurrent-MSemN.html#v:signalF">signalF</a></code> applies a provided
pure function to the available quantity to compute the change and a second value. The
requested change is stricly evaluated but the second value is returned lazily. If the new total is
greater than the next value being waited for then the first waiter is woken. If there are queued
waiters then the next one will wake after a waiter has proceeded and notice the remaining value;
thus a single <code><a href="Control-Concurrent-MSemN.html#v:signalF">signalF</a></code> may result in several waiters obtaining values. Waking waiting threads
is asynchronous.
</p><p><code><a href="Control-Concurrent-MSemN.html#v:signalF">signalF</a></code> may block, and it can be safely interrupted. If the provided function throws an error
or is interrupted then it leaves the <code><a href="Control-Concurrent-MSemN.html#t:MSemN">MSemN</a></code> unchanged. All <code><a href="Control-Concurrent-MSemN.html#v:signal">signal</a></code>, <code><a href="Control-Concurrent-MSemN.html#v:signalF">signalF</a></code>, <code><a href="Control-Concurrent-MSemN.html#v:peekAvail">peekAvail</a></code>, and
the head waiter may momentarily block in a fair FIFO manner.
</p><p>Note: A long running pure function will block all other access to the <code><a href="Control-Concurrent-MSemN.html#t:MSemN">MSemN</a></code> while it is
evaluated.
</p></div></div><div class="top"><p class="src"><a name="v:peekAvail" class="def">peekAvail</a> :: <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/Prelude.html#t:Integral">Integral</a> i => <a href="Control-Concurrent-MSemN.html#t:MSemN">MSemN</a> i -> <a href="/usr/share/doc/ghc/html/libraries/base-4.5.0.0/System-IO.html#t:IO">IO</a> i<a href="src/Control-Concurrent-MSemN.html#peekAvail" class="link">Source</a></p><div class="doc"><p><code><a href="Control-Concurrent-MSemN.html#v:peekAvail">peekAvail</a></code> skips the queue of any blocked <code><a href="Control-Concurrent-MSemN.html#v:wait">wait</a></code> and <code><a href="Control-Concurrent-MSemN.html#v:waitF">waitF</a></code> threads, but may momentarily
block on <code><a href="Control-Concurrent-MSemN.html#v:signal">signal</a></code>, <code><a href="Control-Concurrent-MSemN.html#v:signalF">signalF</a></code>, other <code><a href="Control-Concurrent-MSemN.html#v:peekAvail">peekAvail</a></code>, and the head waiter. This returns the amount of
value available to be taken. Using this value without producing unwanted race conditions is left
up to the programmer.
</p><p><code><a href="Control-Concurrent-MSemN.html#v:peekAvail">peekAvail</a></code> is an optimized form of "signalF m (x -> (0,x))".
</p><p>A version of <code><a href="Control-Concurrent-MSemN.html#v:peekAvail">peekAvail</a></code> that joins the FIFO queue of <code><a href="Control-Concurrent-MSemN.html#v:wait">wait</a></code> and <code><a href="Control-Concurrent-MSemN.html#v:waitF">waitF</a></code> can be acheived by
"waitF m (x -> (0,x))"
</p></div></div></div></div><div id="footer"><p>Produced by <a href="http://www.haskell.org/haddock/">Haddock</a> version 2.10.0</p></div></body></html>
