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.

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.

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.

Retrieve the underlying name of a client-side semaphore.

Retrieve the client-side semaphore corresponding to a server-side semaphore.

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

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.

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.