<commit_before>#lang scribble/doc
@(require scribble/struct "mz.rkt")

@(define-syntax-rule (ResultItself x)
   (make-element #f (list "The "
                          (tech "synchronization result")
                          " of " @racket[x] " is " @racket[x] " itself")))

@title[#:tag "sync"]{Events}

@section-index["select"]
@section-index["poll"]

A @deftech{synchronizable event} (or just @defterm{event} for short)
works with the @racket[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 @defterm{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
@deftech{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 @racket[semaphore-wait]. For most kinds of
events, however (such as a port), synchronizing does not modify the
event's state.

The following act as events in Racket.  An extension or embedding
application can extend the set of primitive events --- in particular,
an eventspace in GRacket is an event --- and new structure types can
generate events (see @racket[prop:evt]).

@itemize[

 @item{@racket[_semaphore] --- a semaphore is ready when
 @racket[semaphore-wait] would not block.  @ResultItself[_semaphore].}

 @item{@racket[_semaphore-peek] --- a semaphore-peek event returned by
 @racket[semaphore-peek-evt] applied to @racket[_semaphore] is ready
 exactly when @racket[_semaphore] is
 ready. @ResultItself[_semaphore-peek].}

 @item{@racket[_channel] --- a channel returned by
 @racket[make-channel] is ready when @racket[channel-get] would not
 block. The channel's result as an event is the same as the
 @racket[channel-get] result.}

 @item{@racket[_channel-put] --- an event returned by
 @racket[channel-put-evt] applied to @racket[_channel] is ready when
 @racket[channel-put] would not block on
 @racket[_channel]. @ResultItself[_channel-put].}

 @item{@racket[_input-port] --- an input port is ready as an event when
 @racket[read-byte] would not block. @ResultItself[_input-port].}

 @item{@racket[_output-port] --- an output port is ready when
 @racket[write-bytes-avail] would not block or
 when the port contains buffered characters and
 @racket[write-bytes-avail*] can flush part of the buffer (although
 @racket[write-bytes-avail] might block). @ResultItself[_output-port].}

 @item{@racket[_progress] --- an event produced by
 @racket[port-progress-evt] applied to @racket[_input-port] is ready after
 any subsequent read from @racket[_input-port]. @ResultItself[_progress].}

 @item{@racket[_tcp-listener] --- a TCP listener is ready when
 @racket[tcp-accept] would not block.  @ResultItself[_listener].}

 @item{@racket[_thd] --- a thread is ready when @racket[thread-wait]
 would not block. @ResultItself[_thread].}

 @item{@racket[_thread-dead] --- an event returned by
 @racket[thread-dead-evt] applied to @racket[thd] is ready when
 @racket[thd] has terminated.  @ResultItself[_thread-dead].}

 @item{@racket[_thread-resume] --- an event returned by
 @racket[thread-resume-evt] applied to @racket[thd] is ready when
 @racket[thd] subsequently resumes execution (if it was not already
 running). The event's result is @racket[thd].}

 @item{@racket[_thread-suspend] --- an event returned by
 @racket[thread-suspend-evt] applied to @racket[thd] is ready when
 @racket[thd] subsequently suspends execution (if it was not already
 suspended).  The event's result is @racket[thd].}

 @item{@racket[_alarm] --- an event returned by @racket[alarm-evt] is
 ready after a particular date and time.  @ResultItself[_alarm].}

 @item{@racket[_subprocess] --- a subprocess is ready when
 @racket[subprocess-wait] would not block.
 @ResultItself[_subprocess].}

 @item{@racket[_will-executor] --- a @tech{will executor} is ready when
 @racket[will-execute] would not block.
 @ResultItself[_will-executor].}

 @item{@racket[_custodian-box] --- a @tech{custodian box} is ready when
 its custodian is shut down. @ResultItself[_custodian-box].}

 @item{@racket[_udp] --- an event returned by @racket[udp-send-evt] or
 @racket[udp-receive!-evt] is ready when a send or receive on the
 original socket would block, respectively. @ResultItself[_udp].}

 @item{@racket[_log-receiver] --- a @tech{log receiver} as produced by
 @racket[make-log-receiver] is ready when a logged message is<commit_msg>Add more elements to the list of things that are events.<commit_after>#lang scribble/doc
@(require scribble/struct "mz.rkt" (for-label racket/async-channel))

@(define-syntax-rule (ResultItself x)
   (make-element #f (list "The "
                          (tech "synchronization result")
                          " of " @racket[x] " is " @racket[x] " itself")))

@title[#:tag "sync"]{Events}

@section-index["select"]
@section-index["poll"]

A @deftech{synchronizable event} (or just @defterm{event} for short)
works with the @racket[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 @defterm{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
@deftech{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 @racket[semaphore-wait]. For most kinds of
events, however (such as a port), synchronizing does not modify the
event's state.

The following act as events in Racket.  An extension or embedding
application can extend the set of primitive events --- in particular,
an eventspace in GRacket is an event --- and new structure types can
generate events (see @racket[prop:evt]).

@itemize[

 @item{@racket[_semaphore] --- a semaphore is ready when
 @racket[semaphore-wait] would not block.  @ResultItself[_semaphore].}

 @item{@racket[_semaphore-peek] --- a semaphore-peek event returned by
 @racket[semaphore-peek-evt] applied to @racket[_semaphore] is ready
 exactly when @racket[_semaphore] is
 ready. @ResultItself[_semaphore-peek].}

 @item{@racket[_channel] --- a channel returned by
 @racket[make-channel] is ready when @racket[channel-get] would not
 block. The channel's result as an event is the same as the
 @racket[channel-get] result.}

 @item{@racket[_channel-put] --- an event returned by
 @racket[channel-put-evt] applied to @racket[_channel] is ready when
 @racket[channel-put] would not block on
 @racket[_channel]. @ResultItself[_channel-put].}

 @item{@racket[_async-channel] --- a channel returned by
 @racket[make-async-channel] is ready when @racket[async-channel-get] would not
 block. The channel's result as an event is the same as the
 @racket[async-channel-get] result.}

 @item{@racket[_async-channel-put] --- an event returned by
 @racket[async-channel-put-evt] applied to @racket[_async-channel] is ready when
 @racket[async-channel-put] would not block on
 @racket[_async-channel]. @ResultItself[_async-channel-put].}

 @item{@racket[_input-port] --- an input port is ready as an event when
 @racket[read-byte] would not block. @ResultItself[_input-port].}

 @item{@racket[_output-port] --- an output port is ready when
 @racket[write-bytes-avail] would not block or
 when the port contains buffered characters and
 @racket[write-bytes-avail*] can flush part of the buffer (although
 @racket[write-bytes-avail] might block). @ResultItself[_output-port].}

 @item{@racket[_progress] --- an event produced by
 @racket[port-progress-evt] applied to @racket[_input-port] is ready after
 any subsequent read from @racket[_input-port]. @ResultItself[_progress].}

 @item{@racket[_tcp-listener] --- a TCP listener is ready when
 @racket[tcp-accept] would not block.  @ResultItself[_listener].}

 @item{@racket[_thd] --- a thread is ready when @racket[thread-wait]
 would not block. @ResultItself[_thread].}

 @item{@racket[_thread-dead] --- an event returned by
 @racket[thread-dead-evt] applied to @racket[thd] is ready when
 @racket[thd] has terminated.  @ResultItself[_thread-dead].}

 @item{@racket[_thread-resume] --- an event returned by
 @racket[thread-resume-evt] applied to @racket[thd] is ready when
 @racket[thd] subsequently resumes execution (if it was not already
 running). The event's result is @racket[thd].}

 @item{@racket[_thread-suspend] --- an event returned by
 @racket[thread-suspend-evt] applied to @racket[thd] is ready when
 @racket[thd] subsequently suspends execution (if it was not already
 suspended).  The event's result is @racket[thd].}

 @item{@racket[_thread-receive] --- an event returned by
 @racket[thread-receive-evt] is ready
 when the synchronizing thread has a message to
 receive. @ResultItself[_thread-receive].}

 @item{@racket[_alarm] --- an event returned by @racket[alarm-evt] is
 ready after a particular date and time.  @ResultItself[_alarm].}

 @item{@racket[_subprocess] --- a subprocess is ready when
 @racket[subprocess-wait] would not block.
 @ResultItself[_subprocess].}

 @item{@racket[_will-executor] --- a @tech{will executor} is ready when
 @racket[will-execute] would not block.
 @ResultItself[_will-executor].}

 @item{@racket[_custodian-box] --- a @tech{custodian box} is ready when
 its custodian is shut down. @ResultItself[_custodian-box].}

 @item{@racket[_udp] --- an event returned by @racket[udp-send-evt] or
 @racket[udp-receive!-evt] is ready when a send or receive on the
 original socket would block, respectively. @ResultItself[_udp].}

 @item{@racket[_log-receiver] --- a @tech{log receiver} as produced by
 @racket[make-log-receiver] is ready when a logged message is
{'fraction_non_alphanumeric': 0.11650296606048818, 'fraction_numerical': 0.0, 'mean_word_length': 4.514209115281501, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5438378', 'n_tokens_mistral': 3256, 'n_tokens_neox': 3211, 'n_words': 1132}