suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

reference: doc clarifications on `guard-evt'

Browse Source
This commit is contained in:
Matthew Flatt 2013-03-28 21:48:30 -06:00
parent 5afd1b4118
commit 3f7fcdf1b7
1 changed files with 32 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
collects/scribblings/reference/evts.scrbl
View File

@ -127,63 +127,54 @@ Like @racket[wrap], except that @racket[handle] is called in @tech{tail
position} with respect to the synchronization request, and without position} with respect to the synchronization request, and without
breaks explicitly disabled.} breaks explicitly disabled.}
@defproc[(guard-evt [generator (-> evt?)]) evt?]{
@defproc[(guard-evt [maker (-> evt?)]) evt?]{
Creates a value that behaves as an event, but that is actually an Creates a value that behaves as an event, but that is actually an
event generator. event maker.
An event @racket[_guard] returned by @racket[guard-evt] generates a An event @racket[_guard] returned by @racket[guard-evt] generates an
new event every time that @racket[_guard] is used with @racket[sync] event when @racket[_guard] is used with @racket[sync]
(or whenever it is part of a choice event used with @racket[sync], (or whenever it is part of a choice event used with @racket[sync],
etc.). The generated event is the result of calling etc.), where the generated event is the result of calling
@racket[_generator] when the synchronization begins; if @racket[maker]. The @racket[maker] procedure may be called by
@racket[_generator] returns a non-event, then @racket[_generator]'s @racket[sync] at most once for a given call to @racket[sync], but
@racket[maker] may not be called if a ready event is chosen before
@racket[_guard] is even considered.
If @racket[maker] returns a non-event, then @racket[maker]'s
result is replaced with an event that is @tech{ready for result is replaced with an event that is @tech{ready for
synchronization} and whose @tech{synchronization result} is synchronization} and whose @tech{synchronization result} is
@racket[_guard].} @racket[_guard].}
@defproc[(nack-guard-evt [generator (evt? . -> . evt?)]) evt?]{
Creates a value that behaves as an event, but that is actually an @defproc[(nack-guard-evt [maker (evt? . -> . evt?)]) evt?]{
event generator.
An event @racket[_nack-guard] returned by @racket[nack-guard-evt] Like @racket[guard-evt], but when @racket[maker] is called, it is
applied to @racket[_proc] generates a new event every time that given a NACK (``negative acknowledgment'') event. After starting the
@racket[_nack-guard] is used with @racket[sync] (or whenever it is call to @racket[maker], if the event from @racket[maker] is not
part of a choice event used with @racket[sync], etc.). The generated ultimately chosen as the ready event, then the NACK event supplied to
event is the result of calling @racket[_generator] with a NACK (``negative @racket[maker] becomes @tech{ready for synchronization} with a
acknowledgment'') event when the synchronization begins; if @|void-const| value.
@racket[_generator] returns a non-event, then @racket[_generator]'s result is
replaced with an event that is ready and whose result is
@racket[_nack-guard].
If the event from @racket[_generator] is not ultimately chosen as the The NACK event becomes @tech{ready for synchronization} when the event
unblocked event, then the NACK event supplied to @racket[_generator] is abandoned when either some other event is chosen, the synchronizing
becomes @tech{ready for synchronization} with a @|void-const| value. thread is dead, or control escapes from the call to @racket[sync]
This NACK event becomes @tech{ready for synchronization} when the (even if @racket[_nack-guard]'s @racket[maker] has not yet returned a
event is abandoned when either some other event is chosen, the value). If the event returned by @racket[maker] is chosen, then the
synchronizing thread is dead, or control escapes from the call to NACK event never becomes @tech{ready for synchronization}.}
@racket[sync] (even if @racket[_nack-guard]'s @racket[_generator] has
not yet returned a value). If the event returned by
@racket[_generator] is chosen, then the NACK event never becomes
@tech{ready for synchronization}.}
@defproc[(poll-guard-evt [generator (boolean? . -> . evt?)]) evt?]{ @defproc[(poll-guard-evt [maker (boolean? . -> . evt?)]) evt?]{
Creates a value that behaves as an event, but that is actually an Like @racket[guard-evt], but when @racket[maker] is called, it is
event generator. provided a boolean value that indicates whether the event will be used
for a poll, @racket[#t], or for a blocking synchronization,
@racket[#f].
An event @racket[_poll-guard]returned by @racket[poll-guard-evt] If @racket[#t] is supplied to @racket[maker], if breaks are
generates a new event every time that @racket[_poll-guard] is used
with @racket[sync] (or whenever it is part of a choice event used with
@racket[sync], etc.). The generated event is the result of calling
@racket[_generator] with a boolean: @racket[#t] if the event will be
used for a poll, @racket[#f] for a blocking synchronization.
If @racket[#t] is supplied to @racket[_generator], if breaks are
disabled, if the polling thread is not terminated, and if polling the disabled, if the polling thread is not terminated, and if polling the
resulting event produces a @tech{synchronization result}, the event resulting event produces a @tech{synchronization result}, then the event
will certainly be chosen for its result.} will certainly be chosen for its result.}