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


-- | Cross-platform abstraction for system semaphores
--   
--   This package provides a cross-platform implementation of system
--   semaphores that abstracts over the <a>unix</a> and <a>Win32</a>
--   libraries.
@package semaphore-compat
@version 1.0.0

module System.Semaphore

-- | A system semaphore (POSIX or Win32).
data Semaphore
Semaphore :: !SemaphoreName -> !Semaphore -> Semaphore
[semaphoreName] :: Semaphore -> !SemaphoreName
[semaphore] :: Semaphore -> !Semaphore
newtype SemaphoreName
SemaphoreName :: String -> SemaphoreName
[getSemaphoreName] :: SemaphoreName -> String

-- | Create a new semaphore with the given name and initial amount of
--   available resources.
--   
--   Throws an error if a semaphore by this name already exists.
createSemaphore :: SemaphoreName -> Int -> IO Semaphore

-- | Create a fresh semaphore with the given amount of tokens.
--   
--   Its name will start with the given prefix, but will have a random
--   suffix appended to it.
freshSemaphore :: String -> Int -> IO Semaphore

-- | Open a semaphore with the given name.
--   
--   If no such semaphore exists, throws an error.
openSemaphore :: SemaphoreName -> IO Semaphore

-- | Indefinitely wait on a semaphore.
--   
--   If you want to be able to cancel a wait operation, use
--   <a>forkWaitOnSemaphoreInterruptible</a> instead.
waitOnSemaphore :: Semaphore -> IO ()

-- | Try to obtain a token from the semaphore, without blocking.
--   
--   Immediately returns <a>False</a> if no resources are available.
tryWaitOnSemaphore :: Semaphore -> IO Bool

-- | <a>WaitId</a> stores the information we need to cancel a thread which
--   is waiting on a semaphore.
--   
--   See <a>forkWaitOnSemaphoreInterruptible</a> and
--   <a>interruptWaitOnSemaphore</a>.
data WaitId
WaitId :: ThreadId -> WaitId
[waitingThreadId] :: WaitId -> ThreadId

-- | Spawn a thread that waits on the given semaphore.
--   
--   In this thread, asynchronous exceptions will be masked.
--   
--   The waiting operation can be interrupted using the
--   <a>interruptWaitOnSemaphore</a> function.
--   
--   This implements a similar pattern to the <tt>forkFinally</tt>
--   function.
forkWaitOnSemaphoreInterruptible :: Semaphore -> (Either SomeException Bool -> IO ()) -> IO WaitId

-- | Interrupt a semaphore wait operation initiated by
--   <a>forkWaitOnSemaphoreInterruptible</a>.
interruptWaitOnSemaphore :: WaitId -> IO ()

-- | Query the current semaphore value (how many tokens it has available).
--   
--   This is mainly for debugging use, as it is easy to introduce race
--   conditions when nontrivial program logic depends on the value returned
--   by this function.
getSemaphoreValue :: Semaphore -> IO Int

-- | Release a semaphore: add <tt>n</tt> to its internal counter.
--   
--   No-op when `n &lt;= 0`.
releaseSemaphore :: Semaphore -> Int -> IO ()

-- | Destroy the given semaphore.
destroySemaphore :: Semaphore -> IO ()

-- | Abstraction over the operations of a semaphore.
data AbstractSem
AbstractSem :: IO () -> IO () -> AbstractSem
[acquireSem] :: AbstractSem -> IO ()
[releaseSem] :: AbstractSem -> IO ()
withAbstractSem :: AbstractSem -> IO b -> IO b
instance GHC.Classes.Eq System.Semaphore.SemaphoreName
