11.2.3 Semaphores (original) (raw)

11.2.3 Semaphores🔗ℹ

A semaphore has an internal counter; when this counter is zero, the semaphore can block a thread’s execution (throughsemaphore-wait) until another thread increments the counter (using semaphore-post). The maximum value for a semaphore’s internal counter is platform-specific, but always at least10000.

A semaphore’s counter is updated in a single-threaded manner, so that semaphores can be used for reliable synchronization. Semaphore waiting is fair: if a thread is blocked on a semaphore and the semaphore’s internal value is non-zero infinitely often, then the thread is eventually unblocked.

In addition to its use with semaphore-specific procedures, a semaphore can be used as a synchronizable event (see Events). A semaphore is ready for synchronization whensemaphore-wait would not block. Upon synchronization, the semaphore’s counter is decremented, and the synchronization result of a semaphore is the semaphore itself.

Returns #t if v is a semaphore,#f otherwise.

Creates and returns a new semaphore with the counter initially set toinit. If init is larger than a semaphore’s maximum internal counter value, the exn:fail exception is raised.

Increments the semaphore’s internal counter and returns #. If the semaphore’s internal counter has already reached its maximum value, the exn:fail exception is raised.

Blocks until the internal counter for semaphore sema is non-zero. When the counter is non-zero, it is decremented and semaphore-waitreturns #.

Likesemaphore-wait, but semaphore-try-wait? never blocks execution. If sema’s internal counter is zero,semaphore-try-wait? returns #f immediately without decrementing the counter. If sema’s counter is positive, it is decremented and #t is returned.

Likesemaphore-wait, but breaking is enabled (seeBreaks) while waiting on sema. If breaking is disabled when semaphore-wait/enable-break is called, then either the semaphore’s counter is decremented or theexn:break exception is raised, but not both.

Creates and returns a new synchronizable event (for use with sync, for example) that is ready for synchronization when sema is ready, but synchronizing the event does not decrement sema’s internal count. The synchronization result of a semaphore-peek event is the semaphore-peek event itself.

Returns #t if v is a semaphore wrapper produced bysemaphore-peek-evt, #f otherwise.

Waits on sema using semaphore-wait, callsproc with all args, and then posts tosema. A continuation barrier blocks full continuation jumps into or out of proc (see Prompts, Delimited Continuations, and Barriers), but escape jumps are allowed, and sema is posted on escape. Iftry-fail-thunk is provided and is not #f, thensemaphore-try-wait? is called on sema instead ofsemaphore-wait, and try-fail-thunk is called if the wait fails.

Like call-with-semaphore, except thatsemaphore-wait/enable-break is used with sema in non-try mode. When try-fail-thunk is provided and not#f, then breaks are enabled around the use ofsemaphore-try-wait? on sema.