A client-side semaphore: the handle a jobclient uses to acquire and release tokens from a semaphore created by a jobserver.
Retrieve the underlying name with clientSemaphoreName.
Modulesemaphore-compat-2.0.1Haskell2010
System.Semaphore
This library provides a cross-platform implementation of semaphores.
Its main role is to provide a cross-platform notion of semaphore that can be used to implement the jobserver/jobclient model of GHC proposal #540.
Typical usage:
The jobserver creates a ServerSemaphore, e.g. using createSemaphore/freshSemaphore.
The jobserver retrieves the serialisable SemaphoreIdentifier of this ServerSemaphore by using serverClientSemaphore, clientSemaphoreName and semaphoreIdentifier.
The jobserver passes the SemaphoreIdentifier to the jobclient via IPC.
The jobclient uses openSemaphore to obtain the ClientSemaphore corresponding to the SemaphoreIdentifier it has been given.
The jobclient can then request resources from the semaphore using waitOnSemaphore (and return them using releaseSemaphoreToken), or by using the withAbstractSem bracket pattern.
Once the jobclient is done, it uses destroyClientSemaphore to ensure all resources are released (including any remaining tokens).
Once the jobserver is done, it cleans up the resources underlying the semaphore using destroyServerSemaphore.
NB: the above usage outline deliberately omits any mention of implicit semaphore tokens: such a notion does not exist in this library, as they are purely an abstraction layer used by the jobserver implementation. See destroyClientSemaphore for more details.
- 8 types
- 17 values
- Packagesemaphore-compat-2.0.1
- Exports25
- LanguageHaskell2010
- LicenceBSD-3-Clause
- SourceSemaphore.hs
System semaphores
7 declarationsSince version 2 of semaphore-compat, the library distinguishes between two
kinds of semaphores:
When a jobserver creates a semaphore via createSemaphore, it obtains a ServerSemaphore.
Jobclients, which are passed the SemaphoreIdentifier of a pre-existing semaphore, obtain a ClientSemaphore via openSemaphore.
When the jobserver wants to also act as a jobclient, it can use serverClientSemaphore to obtain the ClientSemaphore corresponding to its ServerSemaphore.
This architecture allows the jobserver to keep full accounting of semaphore resources held by all clients.
A server-side semaphore: a ClientSemaphore together with the book-keeping needed to track resource usage by all clients.
Retrieve the corresponding client semaphore with serverClientSemaphore.
Retrieve the client-side semaphore corresponding to a server-side semaphore.
A semaphore name: a protocol version and an unversioned name string.
Instances2Eq, Show
Eq SemaphoreNameDefined in semaphore-compat-2.0.1 · System.Semaphore.Internal.VersionShow SemaphoreNameDefined in semaphore-compat-2.0.1 · System.Semaphore.Internal.Version
Retrieve the underlying name of a client-side semaphore.
The identifier string of a semaphore: a serialised SemaphoreName used for inter-process communication (e.g. as a command line argument).
The specific format of this name string depends on the protocol version:
For version 1, this is the unadorned semaphore name.
For version
N >= 2, the semaphore name is prefixed withv<N>-.
The serialised identifier of a SemaphoreName for inter-process communication.
See SemaphoreIdentifier for more information.
Creating a semaphore
value
createSemaphore :: Stringlabel
-> Intnumber of tokens on the semaphore
-> IO (Either SemaphoreError ServerSemaphore)
Create a new semaphore with the given label and initial token count.
value
freshSemaphore :: Stringlabel prefix
-> Intnumber of tokens on the semaphore
-> IO (Either SemaphoreError ServerSemaphore)
Create a fresh semaphore with a unique name and the given token count.
The name is derived from the given prefix with a random suffix.
Opening a semaphore
A held semaphore token: evidence of one unit of resource acquired from a semaphore.
Use releaseSemaphoreToken or withSemaphoreToken to ensure prompt release
of semaphore tokens.
Platform-dependent behaviour:
On POSIX, if all references to a SemaphoreToken are dropped without being released, a finalizer returns the token to the semaphore.
On Windows, tokens held by a crashed client are permanently lost.
Open a pre-existing semaphore.
Returns Left SemaphoreIncompatibleVersion if the semaphore protocol
version is not compatible with the current version of semaphore-compat.
Parse a SemaphoreIdentifier into a SemaphoreName.
Returns Nothing for unversioned strings (which should be treated as
v1 by the caller's compatibility logic).
The semaphore protocol version currently being used.
The version tracks the IPC mechanism, not the library version:
POSIX: 2 (domain sockets, replacing v1 system semaphores).
Windows: 1 (Win32 named semaphores, unchanged from v1).
Unsupported platforms: 0 (no compatible IPC backend).
Constructors
Instances3Eq, Ord, Show
Eq SemaphoreProtocolVersionDefined in semaphore-compat-2.0.1 · System.Semaphore.Internal.VersionOrd SemaphoreProtocolVersionDefined in semaphore-compat-2.0.1 · System.Semaphore.Internal.VersionShow SemaphoreProtocolVersionDefined in semaphore-compat-2.0.1 · System.Semaphore.Internal.Version
The protocol version used on this host platform with this version of
semaphore-compat.
Check whether two semaphore protocol versions are compatible.
Errors that can occur when creating or opening a semaphore.
Constructors
SemaphoreAlreadyExistsCan't create a semaphore: a semaphore with this name already exists.
SemaphoreDoesNotExistCan't open a semaphore: no semaphore with this name exists.
SemaphoreIncompatibleVersionProtocol version incompatibility: the semaphore identifier uses a different protocol version than the library is currently using.
SemaphoreOtherErrorAn IOException was raised when creating or opening the semaphore.
Instances3Eq, Show, Exception
Eq SemaphoreErrorDefined in semaphore-compat-2.0.1 · System.Semaphore.Internal.VersionShow SemaphoreErrorDefined in semaphore-compat-2.0.1 · System.Semaphore.Internal.VersionException SemaphoreErrorDefined in semaphore-compat-2.0.1 · System.Semaphore.Internal.Version
Requesting a token
Acquire a token from the semaphore, blocking until one is available.
The returned SemaphoreToken must be released with releaseSemaphoreToken. For prompt and predictable release of resources, callers should use withSemaphoreToken or releaseSemaphoreToken.
This operation is interruptible: it can be cancelled by
Control.Concurrent.throwTo, killThread, etc.
If interrupted, any transiently acquired token is automatically returned.
Try to acquire a token from the semaphore without blocking.
Returns Just token if a token was available, Nothing otherwise.
This is not an interruptible operation, but that should not be a problem: this function is not expected to block for long, as the server is supposed to respond immediately.
Acquire a token, run an action, then release the token. Exception safe.
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.
Releasing resources
Release a semaphore token, returning it to the pool.
Idempotent: a second call on the same token is a safe no-op.
Destroy a client-side semaphore.
This is an idempotent operation: double calls to destroyClientSemaphore do not cause any problems.
Destroy a server-side semaphore.
Idempotent. Not interruptible.
The GHC jobserver protocol described in GHC proposal #540 specifies the notion of implicit semaphore tokens.
To invoke a jobclient, the jobserver must be in possession of at least one semaphore token. We consider that the jobserver passes on ownership of this token to the jobclient, even though no interaction with the semaphore takes place. This is the implicit token.
Each jobclient thus starts with one available token (the implicit token), and can request more tokens by waiting on the semaphore.
A jobclient calling destroyClientSemaphore signals to the jobserver that the client is done doing work. The jobserver thus regains control of the implicit token, which it can now use to spawn other jobclients.
Implicit tokens are purely an accounting abstraction that we superimpose on top of semaphore token ownership for the purposes of implementing the jobserver protocol. They are not part of this library.
Abstract semaphores
2 declarationsAbstraction over the operations of a semaphore.
Constructors
AbstractSemacquireSem :: IO ()releaseSem :: IO ()
Acquire/release bracket pattern: acquire a token, perform an action, and release the token.
Guarantees that the token is released in case that the inner action throws an exception.