10.2.1 Events

A synchronizable event (or just event for short) works with the sync procedure to coordinate synchronization among threads. Certain kinds of objects double as events, including ports and threads. Other kinds of objects exist only for their use as events.

At any point in time, an event is either ready for synchronization, or it is not; depending on the kind of event and how it is used by other threads, an event can switch from not ready to ready (or back), at any time. If a thread synchronizes on an event when it is ready, then the event produces a particular synchronization result.

Synchronizing an event may affect the state of the event. For example, when synchronizing a semaphore, then the semaphore’s internal count is decremented, just as with semaphore-wait. For most kinds of events, however (such as a port), synchronizing does not modify the event’s state.

Racket values that act as synchronizable events include semaphores, channels, asynchronous channels, ports, TCP listeners, threads, subprocesses, will executors, and custodian boxes. Libraries can define new synchronizable events, especially though prop:evt.

When at least one evt is ready, its synchronization result (often evt itself) is returned. If multiple evts are ready, one of the evts is chosen pseudo-randomly for the result; the current-evt-pseudo-random-generator parameter sets the random-number generator that controls this choice.

A zero value for timeout is equivalent to (lambda () #f). In either case, each evt is checked at least once before returning #f or calling timeout.

See also alarm-evt for an alternative timeout mechanism.

That is, an event returned by choice-evt is ready for synchronization when one or more of the evts supplied to choice-evt are ready for synchronization. If the choice event is chosen, one of its ready evts is chosen pseudo-randomly, and the synchronization result is the chosen evt’s synchronization result.

The call to wrap is parameterize-breaked to disable breaks initially. The evt cannot be an event created by handle-evt or any combination of choice-evt involving an event from handle-evt.

An event guard returned by guard-evt generates a new event every time that guard is used with sync (or whenever it is part of a choice event used with sync, etc.). The generated event is the result of calling generator when the synchronization begins; if generator returns a non-event, then generator’s result is replaced with an event that is ready for synchronization and whose synchronization result is guard.

An event nack-guard returned by nack-guard-evt applied to proc generates a new event every time that nack-guard is used with sync (or whenever it is part of a choice event used with sync, etc.). The generated event is the result of calling generator with a NACK (“negative acknowledgment”) event when the synchronization begins; if generator returns a non-event, then generator’s result is replaced with an event that is ready and whose result is nack-guard.

If the event from generator is not ultimately chosen as the unblocked event, then the NACK event supplied to generator becomes ready for synchronization with a #<void> value. This NACK event becomes ready for synchronization when the event is abandoned when either some other event is chosen, the synchronizing thread is dead, or control escapes from the call to sync (even if nack-guard’s generator has not yet returned a value). If the event returned by generator is chosen, then the NACK event never becomes ready for synchronization.

An event poll-guardreturned by poll-guard-evt generates a new event every time that poll-guard is used with sync (or whenever it is part of a choice event used with sync, etc.). The generated event is the result of calling generator with a boolean: #t if the event will be used for a poll, #f for a blocking synchronization.

If #t is supplied to generator, if breaks are disabled, if the polling thread is not terminated, and if polling the resulting event produces a synchronization result, the event will certainly be chosen for its result.

• An event evt: In this case, using the structure as an event is equivalent to using evt.

• A procedure proc of one argument: In this case, the structure is similar to an event generated by guard-evt, except that the would-be guard procedure proc receives the structure as an argument, instead of no arguments.

• An exact, non-negative integer between 0 (inclusive) and the number of non-automatic fields in the structure type (exclusive, not counting supertype fields): The integer identifies a field in the structure, and the field must be designated as immutable. If the field contains an object or an event-generating procedure of one argument, the event or procedure is used as above. Otherwise, the structure acts as an event that is never ready.

Instances of a structure type with the prop:input-port or prop:output-port property are also synchronizable events by virtue of being a port. If the structure type has more than one of prop:evt, prop:input-port, and prop:output-port, then the prop:evt value (if any) takes precedence for determining the instance’s behavior as an event, and the prop:input-port property takes precedence over prop:output-port for synchronization.