A semaphore identity (name + socket path). Each operation that needs a connection opens one internally.

A server-side semaphore (owns the server thread, listen socket, and token pool).

A semaphore name: a protocol version and an unversioned name string.

The serialised identifier of a SemaphoreName for transport between processes.

For version 1 this is the bare name; for version N (N >= 2) the name is prefixed with v<N>-.

Create a new semaphore with the given label and initial token count.

On POSIX, crash recovery is automatic: disconnected clients' tokens are returned to the pool. On Windows, tokens held by a crashed client are permanently lost.

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.

A held semaphore token, bound to one acquired resource.

If all references to the SemaphoreToken are dropped without being released, a finalizer closes the underlying connection and the server returns the token to the pool. Use releaseSemaphoreToken or withSemaphoreToken for prompt release rather than relying on GC timing.

The fd is held in an internal MVar so releaseSemaphoreToken takes ownership atomically: a second (erroneous) release is a safe no-op.

Open a semaphore from its SemaphoreIdentifier.

The identifier should normally begin with a version prefix v<N>-. An unversioned identifier is treated as v1 for backwards compatibility. Returns Left SemaphoreIncompatibleVersion if the identifier's protocol version is not compatible with this build of semaphore-compat.

The identifier string of a semaphore, as serialised for transport between processes (e.g. on a command line via -jsem).

For version 1 this is a bare name; for version N (with N >= 2) this is "v<N>-<name>".

Parse a SemaphoreIdentifier into a SemaphoreName.

Returns Nothing for unversioned strings (which should be treated as v1 by the caller's compatibility logic).

The protocol version of a semaphore.

The protocol version on this platform.

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).

Because the version is 1 on Windows, semaphoreIdentifier produces a bare name (no v<N>- prefix), matching the v1 format.

Check whether two semaphore protocol versions are compatible. Only identical versions are compatible.

Errors that can occur when creating or opening a semaphore.

Acquire a token from the semaphore, blocking until one is available.

This operation is interruptible: it can be cancelled by throwTo, killThread, etc. If interrupted, any transiently acquired token is automatically returned to the pool.

For prompt and predictable release of resources, callers should use withSemaphoreToken or releaseSemaphoreToken.

Try to acquire a token from the semaphore without blocking.

Returns Just token if a token was available, Nothing otherwise.

Not interruptible, but this shouldn't 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.

Release a semaphore token, returning it to the pool.

Sends a release command on the token's connection, then closes it. Idempotent: a second call on the same token is a safe no-op.

Not interruptible; only returns when the release has succeeded.

Destroy a client-side semaphore.

On POSIX this is a no-op: ClientSemaphore holds no live connection.

Destroy a server-side semaphore.

Idempotent. Subsequent calls after the first one are no-ops Not interruptible. Only returns when the server and all resources have been cleaned up

Abstraction over the operations of a semaphore.