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

Merge branch 'master' of git.racket-lang.org:plt

Browse Source
This commit is contained in:
Jay McCarthy 2010-04-27 09:45:35 -06:00
commit bed4bcf093
33 changed files with 1860 additions and 1833 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

135
collects/racket/promise.rkt
View File

@ -90,20 +90,24 @@
(provide (rename-out [delay/thread* delay/thread])) (provide (rename-out [delay/thread* delay/thread]))
(define (delay/thread thunk group) (define (delay/thread thunk group)
(define (run) (unless (or (not group)
(call-with-exception-handler (thread-group? group))
(lambda (e) (pset! p (make-reraise e)) (kill-thread (current-thread))) (raise-type-error 'delay/thread "thread group" group))
(lambda () (pset! p (call-with-values thunk list))))) (let ()
(define p (define (run)
(make-promise/thread (call-with-exception-handler
(make-running-thread (lambda (e) (pset! p (make-reraise e)) (kill-thread (current-thread)))
(object-name thunk) (lambda () (pset! p (call-with-values thunk list)))))
(if group (define p
(parameterize ([current-thread-group (make-thread-group)]) (thread run)) (make-promise/thread
(thread run))))) (make-running-thread
p) (object-name thunk)
(if group
(parameterize ([current-thread-group group]) (thread run))
(thread run)))))
p))
(define-syntax delay/thread* (define-syntax delay/thread*
(let ([kwds (list (cons '#:group #'#t))]) (let ([kwds (list (cons '#:group #'(make-thread-group)))])
(lambda (stx) (make-delayer stx #'delay/thread kwds)))) (lambda (stx) (make-delayer stx #'delay/thread kwds))))
(define-struct (promise/idle promise/thread) () (define-struct (promise/idle promise/thread) ()
@ -122,54 +126,63 @@
(provide (rename-out [delay/idle* delay/idle])) (provide (rename-out [delay/idle* delay/idle]))
(define (delay/idle thunk wait-for work-while tick use*) (define (delay/idle thunk wait-for work-while tick use*)
(define use (cond [(use* . <= . 0) 0] [(use* . >= . 1) 1] [else use*])) (unless (evt? wait-for)
(define work-time (* tick use)) (raise-type-error 'delay/idle "evt" wait-for))
(define rest-time (- tick work-time)) (unless (evt? work-while)
(define (work) (raise-type-error 'delay/idle "evt" work-while))
(call-with-exception-handler (unless (and (real? tick) (not (negative? tick)))
(lambda (e) (pset! p (make-reraise e)) (kill-thread (current-thread))) (raise-type-error 'delay/idle "nonnegative real" tick))
(lambda () (pset! p (call-with-values thunk list))))) (unless (real? use*)
(define (run) (raise-type-error 'delay/idle "real" use*))
;; this thread is dedicated to controlling the worker thread, so it's (let ()
;; possible to dedicate messages to signaling a `force'. (define use (cond [(use* . <= . 0) 0] [(use* . >= . 1) 1] [else use*]))
(define force-evt (thread-receive-evt)) (define work-time (* tick use))
(sync wait-for force-evt) (define rest-time (- tick work-time))
(pset! p (make-running-thread (object-name thunk) controller-thread)) (define (work)
(let ([worker (parameterize ([current-thread-group (make-thread-group)]) (call-with-exception-handler
(thread work))]) (lambda (e) (pset! p (make-reraise e)) (kill-thread (current-thread)))
(cond (lambda () (pset! p (call-with-values thunk list)))))
[(and (use . >= . 1) (equal? work-while always-evt)) (define (run)
;; as if it was pre-forced ;; this thread is dedicated to controlling the worker thread, so it's
(thread-wait worker)] ;; possible to dedicate messages to signaling a `force'.
[(use . <= . 0) (define force-evt (thread-receive-evt))
;; work only when explicitly forced (sync wait-for force-evt)
(thread-suspend worker) (pset! p (make-running-thread (object-name thunk) controller-thread))
(sync force-evt) (let ([worker (parameterize ([current-thread-group (make-thread-group)])
(thread-wait worker)] (thread work))])
[else (cond
(thread-suspend worker) [(and (use . >= . 1) (equal? work-while always-evt))
(let loop () ;; as if it was pre-forced
;; rest, then wait for idle time, then resume working (thread-wait worker)]
(if (eq? (begin0 (or (sync/timeout rest-time force-evt) [(use . <= . 0)
(sync work-while force-evt)) ;; work only when explicitly forced
(thread-resume worker)) (thread-suspend worker)
force-evt) (sync force-evt)
;; forced during one of these => let it run to completion (thread-wait worker)]
(thread-wait worker) [else
;; not forced (thread-suspend worker)
(unless (sync/timeout work-time worker) (let loop ()
(thread-suspend worker) ;; rest, then wait for idle time, then resume working
(loop))))]))) (if (eq? (begin0 (or (sync/timeout rest-time force-evt)
;; I don't think that a thread-group here is needed, but it doesn't hurt (sync work-while force-evt))
(define controller-thread (thread-resume worker))
(parameterize ([current-thread-group (make-thread-group)]) force-evt)
(thread run))) ;; forced during one of these => let it run to completion
;; the thunk is not really used in the above, make it a function that returns (thread-wait worker)
;; the controller thread so it can be forced (used in the `prop:force') ;; not forced
(define p (make-promise/idle (unless (sync/timeout work-time worker)
(procedure-rename (lambda () controller-thread) (thread-suspend worker)
(or (object-name thunk) 'idle-thread)))) (loop))))])))
p) ;; I don't think that a thread-group here is needed, but it doesn't hurt
(define controller-thread
(parameterize ([current-thread-group (make-thread-group)])
(thread run)))
;; the thunk is not really used in the above, make it a function that returns
;; the controller thread so it can be forced (used in the `prop:force')
(define p (make-promise/idle
(procedure-rename (lambda () controller-thread)
(or (object-name thunk) 'idle-thread))))
p))
(define-syntax delay/idle* (define-syntax delay/idle*
(let ([kwds (list (cons '#:wait-for #'(system-idle-evt)) (let ([kwds (list (cons '#:wait-for #'(system-idle-evt))
(cons '#:work-while #'(system-idle-evt)) (cons '#:work-while #'(system-idle-evt))

5
collects/scribblings/reference/async-channels.scrbl
View File

@ -90,9 +90,10 @@ the event itself. See also @scheme[sync].}
(async-channel-put to-server 'add) (async-channel-put to-server 'add)
(async-channel-put to-server 4) (async-channel-put to-server 4)
(printf "Result is ~a\n" (async-channel-get from-server)) (printf "Result is ~a\n" (async-channel-get from-server))
(printf "Ask server to do a long computation that might take a while\n") (printf "Ask server to do a long computation\n")
(async-channel-put to-server 'long) (async-channel-put to-server 'long)
(printf "I can do other stuff\n") (printf "I can do other stuff\n")
(printf "Ok, computation from server is ~a\n" (async-channel-get from-server)) (printf "Ok, computation from server is ~a\n"
(async-channel-get from-server))
(async-channel-put to-server 'quit) (async-channel-put to-server 'quit)
] ]

88
collects/scribblings/reference/breaks.scrbl
View File

@ -7,47 +7,47 @@
A @deftech{break} is an asynchronous exception, usually triggered A @deftech{break} is an asynchronous exception, usually triggered
through an external source controlled by the user, or through the through an external source controlled by the user, or through the
@scheme[break-thread] procedure. A break exception can only occur in a @racket[break-thread] procedure. A break exception can only occur in a
thread while breaks are enabled. When a break is detected and enabled, thread while breaks are enabled. When a break is detected and enabled,
the @exnraise[exn:break] in the thread sometime afterward; if breaking the @exnraise[exn:break] in the thread sometime afterward; if breaking
is disabled when @scheme[break-thread] is called, the break is is disabled when @racket[break-thread] is called, the break is
suspended until breaking is again enabled for the thread. While a suspended until breaking is again enabled for the thread. While a
thread has a suspended break, additional breaks are ignored. thread has a suspended break, additional breaks are ignored.
Breaks are enabled through the @scheme[break-enabled] parameter-like Breaks are enabled through the @racket[break-enabled] parameter-like
procedure, and through the @scheme[parameterize-break] form, which is procedure, and through the @racket[parameterize-break] form, which is
analogous to @scheme[parameterize]. The @scheme[break-enabled] analogous to @racket[parameterize]. The @racket[break-enabled]
procedure does not represent a parameter to be used with procedure does not represent a parameter to be used with
@scheme[parameterize], because changing the break-enabled state of a @racket[parameterize], because changing the break-enabled state of a
thread requires an explicit check for breaks, and this check is thread requires an explicit check for breaks, and this check is
incompatible with the tail evaluation of a @scheme[parameterize] incompatible with the tail evaluation of a @racket[parameterize]
expression's body. expression's body.
Certain procedures, such as @scheme[semaphore-wait/enable-break], Certain procedures, such as @racket[semaphore-wait/enable-break],
enable breaks temporarily while performing a blocking action. If enable breaks temporarily while performing a blocking action. If
breaks are enabled for a thread, and if a break is triggered for the breaks are enabled for a thread, and if a break is triggered for the
thread but not yet delivered as an @scheme[exn:break] exception, then thread but not yet delivered as an @racket[exn:break] exception, then
the break is guaranteed to be delivered before breaks can be disabled the break is guaranteed to be delivered before breaks can be disabled
in the thread. The timing of @scheme[exn:break] exceptions is not in the thread. The timing of @racket[exn:break] exceptions is not
guaranteed in any other way. guaranteed in any other way.
Before calling a @scheme[with-handlers] predicate or handler, an Before calling a @racket[with-handlers] predicate or handler, an
exception handler, an error display handler, an error escape handler, exception handler, an error display handler, an error escape handler,
an error value conversion handler, or a @scheme[pre-thunk] or an error value conversion handler, or a @racket[pre-thunk] or
@scheme[post-thunk] for a @scheme[dynamic-wind], the call is @racket[post-thunk] for a @racket[dynamic-wind], the call is
@scheme[parameterize-break]ed to disable breaks. Furthermore, breaks @racket[parameterize-break]ed to disable breaks. Furthermore, breaks
are disabled during the transitions among handlers related to are disabled during the transitions among handlers related to
exceptions, during the transitions between @scheme[pre-thunk]s and exceptions, during the transitions between @racket[pre-thunk]s and
@scheme[post-thunk]s for @scheme[dynamic-wind], and during other @racket[post-thunk]s for @racket[dynamic-wind], and during other
transitions for a continuation jump. For example, if breaks are transitions for a continuation jump. For example, if breaks are
disabled when a continuation is invoked, and if breaks are also disabled when a continuation is invoked, and if breaks are also
disabled in the target continuation, then breaks will remain disabled disabled in the target continuation, then breaks will remain disabled
until from the time of the invocation until the target continuation until from the time of the invocation until the target continuation
executes unless a relevant @scheme[dynamic-wind] @scheme[pre-thunk] or executes unless a relevant @racket[dynamic-wind] @racket[pre-thunk] or
@scheme[post-thunk] explicitly enables breaks. @racket[post-thunk] explicitly enables breaks.
If a break is triggered for a thread that is blocked on a nested If a break is triggered for a thread that is blocked on a nested
thread (see @scheme[call-in-nested-thread]), and if breaks are enabled thread (see @racket[call-in-nested-thread]), and if breaks are enabled
in the blocked thread, the break is implicitly handled by transferring in the blocked thread, the break is implicitly handled by transferring
it to the nested thread. it to the nested thread.
@ -55,7 +55,7 @@ When breaks are enabled, they can occur at any point within execution,
which makes certain implementation tasks subtle. For example, assuming which makes certain implementation tasks subtle. For example, assuming
breaks are enabled when the following code is executed, breaks are enabled when the following code is executed,
@schemeblock[ @racketblock[
(with-handlers ([exn:break? (lambda (x) (void))]) (with-handlers ([exn:break? (lambda (x) (void))])
(semaphore-wait s)) (semaphore-wait s))
] ]
@ -64,18 +64,18 @@ then it is @italic{not} the case that a @|void-const| result means the
semaphore was decremented or a break was received, exclusively. It is semaphore was decremented or a break was received, exclusively. It is
possible that @italic{both} occur: the break may occur after the possible that @italic{both} occur: the break may occur after the
semaphore is successfully decremented but before a @|void-const| semaphore is successfully decremented but before a @|void-const|
result is returned by @scheme[semaphore-wait]. A break exception will result is returned by @racket[semaphore-wait]. A break exception will
never damage a semaphore, or any other built-in construct, but many never damage a semaphore, or any other built-in construct, but many
built-in procedures (including @scheme[semaphore-wait]) contain built-in procedures (including @racket[semaphore-wait]) contain
internal sub-expressions that can be interrupted by a break. internal sub-expressions that can be interrupted by a break.
In general, it is impossible using only @scheme[semaphore-wait] to In general, it is impossible using only @racket[semaphore-wait] to
implement the guarantee that either the semaphore is decremented or an implement the guarantee that either the semaphore is decremented or an
exception is raised, but not both. Scheme therefore supplies exception is raised, but not both. Racket therefore supplies
@scheme[semaphore-wait/enable-break] (see @secref["semaphore"]), @racket[semaphore-wait/enable-break] (see @secref["semaphore"]),
which does permit the implementation of such an exclusive guarantee: which does permit the implementation of such an exclusive guarantee:
@schemeblock[ @racketblock[
(parameterize-break #f (parameterize-break #f
(with-handlers ([exn:break? (lambda (x) (void))]) (with-handlers ([exn:break? (lambda (x) (void))])
(semaphore-wait/enable-break s))) (semaphore-wait/enable-break s)))
@ -84,13 +84,13 @@ which does permit the implementation of such an exclusive guarantee:
In the above expression, a break can occur at any point until breaks In the above expression, a break can occur at any point until breaks
are disabled, in which case a break exception is propagated to the are disabled, in which case a break exception is propagated to the
enclosing exception handler. Otherwise, the break can only occur enclosing exception handler. Otherwise, the break can only occur
within @scheme[semaphore-wait/enable-break], which guarantees that if within @racket[semaphore-wait/enable-break], which guarantees that if
a break exception is raised, the semaphore will not have been a break exception is raised, the semaphore will not have been
decremented. decremented.
To allow similar implementation patterns over blocking port To allow similar implementation patterns over blocking port
operations, MzScheme provides @scheme[read-bytes-avail!/enable-break], operations, Racket provides @racket[read-bytes-avail!/enable-break],
@scheme[write-bytes-avail/enable-break], and other procedures. @racket[write-bytes-avail/enable-break], and other procedures.
@;------------------------------------------------------------------------ @;------------------------------------------------------------------------
@ -99,26 +99,26 @@ operations, MzScheme provides @scheme[read-bytes-avail!/enable-break],
[(break-enabled [on? any/c]) void?])]{ [(break-enabled [on? any/c]) void?])]{
Gets or sets the break enabled state of the current thread. If Gets or sets the break enabled state of the current thread. If
@scheme[on?] is not supplied, the result is @scheme[#t] if breaks are @racket[on?] is not supplied, the result is @racket[#t] if breaks are
currently enabled, @scheme[#f] otherwise. If @scheme[on?] is supplied currently enabled, @racket[#f] otherwise. If @racket[on?] is supplied
as @scheme[#f], breaks are disabled, and if @scheme[on?] is a true as @racket[#f], breaks are disabled, and if @racket[on?] is a true
value, breaks are enabled.} value, breaks are enabled.}
@defform[(parameterize-break boolean-expr body ...+)]{Evaluates @defform[(parameterize-break boolean-expr body ...+)]{Evaluates
@scheme[boolean-expr] to determine whether breaks are initially @racket[boolean-expr] to determine whether breaks are initially
enabled in while evaluating the @scheme[body]s in sequence. The result enabled in while evaluating the @racket[body]s in sequence. The result
of the @scheme[parameter-break] expression is the result of the last of the @racket[parameter-break] expression is the result of the last
@scheme[expr]. @racket[expr].
Like @scheme[parameterize] (see @secref["parameters"]), a fresh Like @racket[parameterize] (see @secref["parameters"]), a fresh
@tech{thread cell} (see @secref["threadcells"]) is allocated to @tech{thread cell} (see @secref["threadcells"]) is allocated to
hold the break-enabled state of the continuation, and calls to hold the break-enabled state of the continuation, and calls to
@scheme[break-enabled] within the continuation access or modify the @racket[break-enabled] within the continuation access or modify the
new cell. Unlike parameters, the break setting is not inherited by new new cell. Unlike parameters, the break setting is not inherited by new
threads.} threads.}
@defproc[(current-break-parameterization) break-parameterization?]{ @defproc[(current-break-parameterization) break-parameterization?]{
Analogous to @scheme[(current-parameterization)] (see Analogous to @racket[(current-parameterization)] (see
@secref["parameters"]); it returns a break-parameterization @secref["parameters"]); it returns a break-parameterization
(effectively a thread cell) that holds the current continuation's (effectively a thread cell) that holds the current continuation's
break-enable state.} break-enable state.}
@ -127,8 +127,8 @@ break-enable state.}
[break-param break-parameterization?] [break-param break-parameterization?]
[thunk (-> any)]) [thunk (-> any)])
any]{ any]{
Analogous to @scheme[(call-with-parameterization parameterization Analogous to @racket[(call-with-parameterization parameterization
thunk)] (see @secref["parameters"]), calls @scheme[thunk] in a thunk)] (see @secref["parameters"]), calls @racket[thunk] in a
continuation whose break-enabled state is in @scheme[break-param]. The continuation whose break-enabled state is in @racket[break-param]. The
@scheme[thunk] is @italic{not} called in tail position with respect to @racket[thunk] is @italic{not} called in tail position with respect to
the @scheme[call-with-break-parameterization] call.} the @racket[call-with-break-parameterization] call.}

2
collects/scribblings/reference/bytes.scrbl
View File

@ -459,7 +459,7 @@ guaranteed combinations not involving @scheme[""] under Unix, or if it
is any of the guaranteed combinations (including @scheme[""]) under is any of the guaranteed combinations (including @scheme[""]) under
Windows and Mac OS X. Windows and Mac OS X.
@margin-note{In PLT's software distributions for Windows, a suitable @margin-note{In the Racket software distributions for Windows, a suitable
@filepath{iconv.dll} is included with @filepath{libmzsch@italic{VERS}.dll}.} @filepath{iconv.dll} is included with @filepath{libmzsch@italic{VERS}.dll}.}
The set of available encodings and combinations varies by platform, The set of available encodings and combinations varies by platform,

98
collects/scribblings/reference/collects.scrbl
View File

@ -3,67 +3,67 @@
@title[#:tag "collects"]{Libraries and Collections} @title[#:tag "collects"]{Libraries and Collections}
A @deftech{library} is @scheme[module] declaration for use by multiple A @deftech{library} is @racket[module] declaration for use by multiple
programs. Scheme further groups libraries into @deftech{collections} programs. Racket further groups libraries into @deftech{collections}
that can be easily distributed and easily added to a local MzScheme that can be easily distributed and easily added to a local Racket
installation. installation.
Some collections are distributed via @|PLaneT|. Such collections are Some collections are distributed via @|PLaneT|. Such collections are
referenced through a @scheme[planet] module path (see referenced through a @racket[planet] module path (see
@scheme[require]) and are downloaded by Scheme on demand. @racket[require]) and are downloaded by Racket on demand.
Other collections are distributed with PLT Scheme, in which case each Other collections are distributed with Racket, in which case each
collection is a directory that is located in a @filepath{collects} collection is a directory that is located in a @filepath{collects}
directory relative to the @exec{mzscheme}. A collection can also be directory relative to the Racket executable. A collection can also be
installed in a user-specific directory. More generally, the search installed in a user-specific directory. More generally, the search
path for installed collections can be configured through the path for installed collections can be configured through the
@scheme[current-library-collection-paths] parameter. In all of these @racket[current-library-collection-paths] parameter. In all of these
cases, the collections are referenced through @scheme[lib] paths (see cases, the collections are referenced through @racket[lib] paths (see
@scheme[require]). @racket[require]).
For example, the following module uses the @filepath{getinfo.ss} For example, the following module uses the @filepath{getinfo.rkt}
library module from the @filepath{setup} collection, and the library module from the @filepath{setup} collection, and the
@filepath{cards.ss} library module from the @filepath{games} @filepath{cards.rkt} library module from the @filepath{games}
collection's @filepath{cards} subcollection: collection's @filepath{cards} subcollection:
@schememod[ @racketmod[
scheme racket
(require (lib "setup/getinfo.ss") (require (lib "setup/getinfo.rkt")
(lib "games/cards/cards.ss")) (lib "games/cards/cards.rkt"))
.... ....
] ]
This example is more compactly and more commonly written as This example is more compactly and more commonly written as
@schememod[ @racketmod[
scheme racket
(require setup/getinfo (require setup/getinfo
games/cards/cards) games/cards/cards)
.... ....
] ]
When an identifier @scheme[_id] is used in a @scheme[require] form, it When an identifier @racket[_id] is used in a @racket[require] form, it
is converted to @scheme[(lib _rel-string)] where @scheme[_rel-string] is converted to @racket[(lib _rel-string)] where @racket[_rel-string]
is the string form of @scheme[_id]. is the string form of @racket[_id].
A @scheme[_rel-string] in @scheme[(lib _rel-string)] consists of one A @racket[_rel-string] in @racket[(lib _rel-string)] consists of one
or more path elements that name collections, and then a final path or more path elements that name collections, and then a final path
element that names a library file; the path elements are separated by element that names a library file; the path elements are separated by
@litchar{/}. If @scheme[_rel-string] contains no @litchar{/}s, then @litchar{/}. If @racket[_rel-string] contains no @litchar{/}s, then
then @litchar{/main.ss} is implicitly appended to the path. If then @litchar{/main.rkt} is implicitly appended to the path. If
@scheme[_rel-string] contains @litchar{/} but does not end with a file @racket[_rel-string] contains @litchar{/} but does not end with a file
suffix, then @litchar{.ss} is implicitly appended to the path. suffix, then @litchar{.rkt} is implicitly appended to the path.
The translation of a @scheme[planet] or @scheme[lib] path to a The translation of a @racket[planet] or @racket[lib] path to a
@scheme[module] declaration is determined by the @tech{module name @racket[module] declaration is determined by the @tech{module name
resolver}, as specified by the @scheme[current-module-name-resolver] resolver}, as specified by the @racket[current-module-name-resolver]
parameter. parameter.
For the default @tech{module name resolver}, The search path for For the default @tech{module name resolver}, The search path for
collections is determined by the collections is determined by the
@scheme[current-library-collection-paths] parameter. The list of paths @racket[current-library-collection-paths] parameter. The list of paths
in @scheme[current-library-collection-paths] is searched from first to in @racket[current-library-collection-paths] is searched from first to
last to locate the first collection in a @scheme[_rel-string]. To find last to locate the first collection in a @racket[_rel-string]. To find
a sub-collection, the enclosing collection is first found; if the a sub-collection, the enclosing collection is first found; if the
sub-collection is not present in the found enclosing collection, then sub-collection is not present in the found enclosing collection, then
the search continues by looking for another instance of the enclosing the search continues by looking for another instance of the enclosing
@ -73,9 +73,9 @@ trees of other path elements. (The ``splicing'' of tress applies only
to directories; a file within a collection is found only within the to directories; a file within a collection is found only within the
first instance of the collection.) first instance of the collection.)
The value of the @scheme[current-library-collection-paths] parameter The value of the @racket[current-library-collection-paths] parameter
is initialized in @exec{mzscheme} to the result of is initialized in the Racket executable to the result of
@scheme[(find-library-collection-paths)]. @racket[(find-library-collection-paths)].
@defproc[(find-library-collection-paths [pre-extras (listof path-string?) null] @defproc[(find-library-collection-paths [pre-extras (listof path-string?) null]
@ -86,37 +86,37 @@ Produces a list of paths as follows:
@itemize[ @itemize[
@item{The path produced by @scheme[(build-path (find-system-path @item{The path produced by @racket[(build-path (find-system-path
'addon-dir) (version) "collects")] is the first element of the 'addon-dir) (version) "collects")] is the first element of the
default collection path list, unless the value of the default collection path list, unless the value of the
@scheme[use-user-specific-search-paths] parameter is @scheme[#f].} @racket[use-user-specific-search-paths] parameter is @racket[#f].}
@item{Extra directories provided in @scheme[pre-extras] are included @item{Extra directories provided in @racket[pre-extras] are included
next to the default collection path list, converted to complete next to the default collection path list, converted to complete
paths relative to the executable.} paths relative to the executable.}
@item{If the directory specified by @scheme[(find-system-path @item{If the directory specified by @racket[(find-system-path
'collects-dir)] is absolute, or if it is relative (to the 'collects-dir)] is absolute, or if it is relative (to the
executable) and it exists, then it is added to the end of the executable) and it exists, then it is added to the end of the
default collection path list.} default collection path list.}
@item{Extra directories provided in @scheme[post-extras] are included @item{Extra directories provided in @racket[post-extras] are included
last in the default collection path list, converted to complete last in the default collection path list, converted to complete
paths relative to the executable.} paths relative to the executable.}
@item{If the @indexed-envvar{PLTCOLLECTS} environment variable is @item{If the @indexed-envvar{PLTCOLLECTS} environment variable is
defined, it is combined with the default list using defined, it is combined with the default list using
@scheme[path-list-string->path-list]. If it is not defined, the @racket[path-list-string->path-list]. If it is not defined, the
default collection path list (as constructed by the first three default collection path list (as constructed by the first three
bullets above) is used directly. bullets above) is used directly.
Note that under @|AllUnix|, paths are separated by @litchar{:}, and Note that under @|AllUnix|, paths are separated by @litchar{:}, and
under Windows by @litchar{;}. Also, under Windows by @litchar{;}. Also,
@scheme[path-list-string->path-list] splices the default paths at an @racket[path-list-string->path-list] splices the default paths at an
empty path, for example, with many Unix shells you can set empty path, for example, with many Unix shells you can set
@envvar{PLTCOLLECTS} to @tt{":`pwd`"}, @tt{"`pwd`:"}, or @envvar{PLTCOLLECTS} to @tt{":`pwd`"}, @tt{"`pwd`:"}, or
@tt{"`pwd`"} to specify search the current directory after, before, @tt{"`pwd`"} to specify search the current directory after, before,
or instead of the default paths respectively.} or instead of the default paths, respectively.}
]} ]}
@ -124,22 +124,22 @@ Produces a list of paths as follows:
@defproc[(collection-path [collection string?] ...+) path?]{ @defproc[(collection-path [collection string?] ...+) path?]{
Returns the path to a directory containing the libraries of the Returns the path to a directory containing the libraries of the
collection indicated by @scheme[collection]s, where the second collection indicated by @racket[collection]s, where the second
@scheme[collection] (if any) names a sub-collection, and so on. If the @racket[collection] (if any) names a sub-collection, and so on. If the
collection is not found, the @exnraise[exn:fail:filesystem].} collection is not found, the @exnraise[exn:fail:filesystem].}
@defparam[current-library-collection-paths paths (listof (and/c path? complete-path?))]{ @defparam[current-library-collection-paths paths (listof (and/c path? complete-path?))]{
Parameter that determines a list of complete directory paths for Parameter that determines a list of complete directory paths for
library collections used by @scheme[require]. See library collections used by @racket[require]. See
@secref["collects"] for more information.} @secref["collects"] for more information.}
@defboolparam[use-user-specific-search-paths on?]{ @defboolparam[use-user-specific-search-paths on?]{
Parameter that determines whether user-specific paths, which are in Parameter that determines whether user-specific paths, which are in
the directory produced by @scheme[(find-system-path 'addon-dir)], are the directory produced by @racket[(find-system-path 'addon-dir)], are
included in search paths for collections and other files. For example, included in search paths for collections and other files. For example,
@scheme[find-library-collection-paths] omits the user-specific @racket[find-library-collection-paths] omits the user-specific
collection directory when this parameter's value is @scheme[#f].} collection directory when this parameter's value is @racket[#f].}

2
collects/scribblings/reference/concurrency.scrbl
View File

@ -3,7 +3,7 @@
@title[#:tag "concurrency" #:style 'toc]{Concurrency} @title[#:tag "concurrency" #:style 'toc]{Concurrency}
PLT Scheme supports multiple threads of control within a program, Racket supports multiple threads of control within a program,
thread-local storage, some primitive synchronization mechanisms, and a thread-local storage, some primitive synchronization mechanisms, and a
framework for composing synchronization abstractions. In addition, the framework for composing synchronization abstractions. In addition, the
@scheme[racket/future] library provides some support for parallelism @scheme[racket/future] library provides some support for parallelism

126
collects/scribblings/reference/cont-marks.scrbl
View File

@ -1,6 +1,6 @@
#lang scribble/doc #lang scribble/doc
@(require scribble/struct @(require scribble/struct
scribble/scheme scribble/racket
"mz.ss") "mz.ss")
@(define (cont n) @(define (cont n)
@ -12,65 +12,65 @@
See @secref["mark-model"] and @secref["prompt-model"] for See @secref["mark-model"] and @secref["prompt-model"] for
general information about continuation marks. general information about continuation marks.
The list of continuation marks for a key @scheme[_k] and a continuation The list of continuation marks for a key @racket[_k] and a continuation
@scheme[_C] that extends @cont[0] is defined as follows: @racket[_C] that extends @cont[0] is defined as follows:
@itemize[ @itemize[
@item{If @scheme[_C] is an empty continuation, then the mark list is @item{If @racket[_C] is an empty continuation, then the mark list is
@scheme[null].} @racket[null].}
@item{If @scheme[_C]'s first frame contains a mark @scheme[_m] for @scheme[_k], @item{If @racket[_C]'s first frame contains a mark @racket[_m] for @racket[_k],
then the mark list for @scheme[_C] is @scheme[(cons _m _lst)], then the mark list for @racket[_C] is @racket[(cons _m _lst)],
where @scheme[_lst] is the mark list for @scheme[_k] in @cont[0].} where @racket[_lst] is the mark list for @racket[_k] in @cont[0].}
@item{If @scheme[_C]'s first frame does not contain a mark keyed by @item{If @racket[_C]'s first frame does not contain a mark keyed by
@scheme[_k], then the mark list for @scheme[_C] is the mark list for @racket[_k], then the mark list for @racket[_C] is the mark list for
@cont[0].} @cont[0].}
] ]
The @scheme[with-continuation-mark] form installs a mark on the first The @racket[with-continuation-mark] form installs a mark on the first
frame of the current continuation (see @secref["wcm"]). Procedures frame of the current continuation (see @secref["wcm"]). Procedures
such as @scheme[current-continuation-marks] allow inspection of marks. such as @racket[current-continuation-marks] allow inspection of marks.
Whenever Scheme creates an exception record for a primitive exception, Whenever Racket creates an exception record for a primitive exception,
it fills the @scheme[continuation-marks] field with the value of it fills the @racket[continuation-marks] field with the value of
@scheme[(current-continuation-marks)], thus providing a snapshot of @racket[(current-continuation-marks)], thus providing a snapshot of
the continuation marks at the time of the exception. the continuation marks at the time of the exception.
When a continuation procedure returned by When a continuation procedure returned by
@scheme[call-with-current-continuation] or @racket[call-with-current-continuation] or
@scheme[call-with-composable-continuation] is invoked, it restores the @racket[call-with-composable-continuation] is invoked, it restores the
captured continuation, and also restores the marks in the captured continuation, and also restores the marks in the
continuation's frames to the marks that were present when continuation's frames to the marks that were present when
@scheme[call-with-current-continuation] or @racket[call-with-current-continuation] or
@scheme[call-with-composable-continuation] was invoked. @racket[call-with-composable-continuation] was invoked.
@defproc[(continuation-marks [cont (or/c continuation? thread?)] @defproc[(continuation-marks [cont (or/c continuation? thread?)]
[prompt-tag prompt-tag? (default-continuation-prompt-tag)]) [prompt-tag prompt-tag? (default-continuation-prompt-tag)])
continuation-mark-set?]{ continuation-mark-set?]{
Returns an opaque value containing the set of continuation marks for Returns an opaque value containing the set of continuation marks for
all keys in the continuation @scheme[cont] (or the current all keys in the continuation @racket[cont] (or the current
continuation of @scheme[cont] if it is a thread) up to the prompt continuation of @racket[cont] if it is a thread) up to the prompt
tagged by @scheme[prompt-tag]. If @scheme[cont] is an escape tagged by @racket[prompt-tag]. If @racket[cont] is an escape
continuation (see @secref["prompt-model"]), then the current continuation (see @secref["prompt-model"]), then the current
continuation must extend @scheme[cont], or the continuation must extend @racket[cont], or the
@exnraise[exn:fail:contract]. If @scheme[cont] was not captured with @exnraise[exn:fail:contract]. If @racket[cont] was not captured with
respect to @scheme[prompt-tag] and does not include a prompt for respect to @racket[prompt-tag] and does not include a prompt for
@scheme[prompt-tag], the @exnraise[exn:fail:contract]. If @racket[prompt-tag], the @exnraise[exn:fail:contract]. If
@scheme[cont] is a dead thread, the result is an empty set of @racket[cont] is a dead thread, the result is an empty set of
continuation marks.} continuation marks.}
@defproc[(current-continuation-marks [prompt-tag prompt-tag? (default-continuation-prompt-tag)]) @defproc[(current-continuation-marks [prompt-tag prompt-tag? (default-continuation-prompt-tag)])
continuation-mark-set?]{ continuation-mark-set?]{
Returns an opaque value containing the set of continuation marks for Returns an opaque value containing the set of continuation marks for
all keys in the current continuation up to @scheme[prompt-tag]. In all keys in the current continuation up to @racket[prompt-tag]. In
other words, it produces the same value as other words, it produces the same value as
@schemeblock[ @racketblock[
(call-with-current-continuation (call-with-current-continuation
(lambda (k) (lambda (k)
(continuation-marks k prompt-tag)) (continuation-marks k prompt-tag))
@ -82,11 +82,11 @@ other words, it produces the same value as
[key-v any/c] [key-v any/c]
[prompt-tag prompt-tag? (default-continuation-prompt-tag)]) [prompt-tag prompt-tag? (default-continuation-prompt-tag)])
list?]{ list?]{
Returns a newly-created list containing the marks for @scheme[key-v] Returns a newly-created list containing the marks for @racket[key-v]
in @scheme[mark-set], which is a set of marks returned by in @racket[mark-set], which is a set of marks returned by
@scheme[current-continuation-marks]. The result list is truncated at @racket[current-continuation-marks]. The result list is truncated at
the first point, if any, where continuation frames were originally the first point, if any, where continuation frames were originally
separated by a prompt tagged with @scheme[prompt-tag]..} separated by a prompt tagged with @racket[prompt-tag]..}
@defproc[(continuation-mark-set->list* @defproc[(continuation-mark-set->list*
[mark-set continuation-mark-set?] [mark-set continuation-mark-set?]
@ -95,13 +95,13 @@ separated by a prompt tagged with @scheme[prompt-tag]..}
[prompt-tag prompt-tag? (default-continuation-prompt-tag)]) [prompt-tag prompt-tag? (default-continuation-prompt-tag)])
(listof vector?)]{ (listof vector?)]{
Returns a newly-created list containing vectors of marks in Returns a newly-created list containing vectors of marks in
@scheme[mark-set] for the keys in @scheme[key-list], up to @racket[mark-set] for the keys in @racket[key-list], up to
@scheme[prompt-tag]. The length of each vector in the result list is @racket[prompt-tag]. The length of each vector in the result list is
the same as the length of @scheme[key-list], and a value in a the same as the length of @racket[key-list], and a value in a
particular vector position is the value for the corresponding key in particular vector position is the value for the corresponding key in
@scheme[key-list]. Values for multiple keys appear in a single vector @racket[key-list]. Values for multiple keys appear in a single vector
only when the marks are for the same continuation frame in only when the marks are for the same continuation frame in
@scheme[mark-set]. The @scheme[none-v] argument is used for vector @racket[mark-set]. The @racket[none-v] argument is used for vector
elements to indicate the lack of a value.} elements to indicate the lack of a value.}
@defproc[(continuation-mark-set-first @defproc[(continuation-mark-set-first
@ -110,11 +110,11 @@ elements to indicate the lack of a value.}
[prompt-tag prompt-tag? (default-continuation-prompt-tag)]) [prompt-tag prompt-tag? (default-continuation-prompt-tag)])
any]{ any]{
Returns the first element of the list that would be returned by Returns the first element of the list that would be returned by
@scheme[(continuation-mark-set->list (or mark-set @racket[(continuation-mark-set->list (or mark-set
(current-continuation-marks prompt-tag)) key-v prompt-tag)], or (current-continuation-marks prompt-tag)) key-v prompt-tag)], or
@scheme[#f] if the result would be the empty list. Typically, this @racket[#f] if the result would be the empty list. Typically, this
result can be computed more quickly using result can be computed more quickly using
@scheme[continuation-mark-set-first].} @racket[continuation-mark-set-first].}
@defproc[(call-with-immediate-continuation-mark @defproc[(call-with-immediate-continuation-mark
[key-v any/c] [key-v any/c]
@ -122,44 +122,44 @@ result can be computed more quickly using
[default-v any/c #f]) [default-v any/c #f])
any]{ any]{
Calls @scheme[proc] with the value associated with @scheme[key-v] in Calls @racket[proc] with the value associated with @racket[key-v] in
the first frame of the current continuation (i.e., a value that would the first frame of the current continuation (i.e., a value that would
be replaced if the call to be replaced if the call to
@scheme[call-with-immediate-continuation-mark] were replaced with a @racket[call-with-immediate-continuation-mark] were replaced with a
@scheme[with-continuation-mark] form using @scheme[key-v] as the key @racket[with-continuation-mark] form using @racket[key-v] as the key
expression). If no such value exists in the first frame, expression). If no such value exists in the first frame,
@scheme[default-v] is passed to @scheme[proc]. The @scheme[proc] is @racket[default-v] is passed to @racket[proc]. The @racket[proc] is
called in tail position with respect to the called in tail position with respect to the
@scheme[call-with-immediate-continuation-mark] call. @racket[call-with-immediate-continuation-mark] call.
This function could be implemented with a combination of This function could be implemented with a combination of
@scheme[with-continuation-mark], @scheme[current-continuation-marks], @racket[with-continuation-mark], @racket[current-continuation-marks],
and @scheme[continuation-mark-set->list], but and @racket[continuation-mark-set->list], but
@scheme[call-with-immediate-continuation-mark] is implemented more @racket[call-with-immediate-continuation-mark] is implemented more
efficiently; it inspects only the first frame of the current efficiently; it inspects only the first frame of the current
continuation.} continuation.}
@defproc[(continuation-mark-set? [v any/c]) boolean?]{ @defproc[(continuation-mark-set? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] is a mark set created by Returns @racket[#t] if @racket[v] is a mark set created by
@scheme[continuation-marks] or @scheme[current-continuation-marks], @racket[continuation-marks] or @racket[current-continuation-marks],
@scheme[#f] otherwise.} @racket[#f] otherwise.}
@defproc[(continuation-mark-set->context @defproc[(continuation-mark-set->context
[mark-set continuation-mark-set?]) [mark-set continuation-mark-set?])
list?]{ list?]{
Returns a list representing an approximate ``@index["stack Returns a list representing an approximate ``@index["stack
dump"]{@as-index{stack trace}}'' for @scheme[mark-set]'s dump"]{@as-index{stack trace}}'' for @racket[mark-set]'s
continuation. The list contains pairs, where the @scheme[car] of each continuation. The list contains pairs, where the @racket[car] of each
pair contains either @scheme[#f] or a symbol for a procedure name, and pair contains either @racket[#f] or a symbol for a procedure name, and
the @scheme[cdr] of each pair contains either @scheme[#f] or a the @racket[cdr] of each pair contains either @racket[#f] or a
@scheme[srcloc] value for the procedure's source location (see @racket[srcloc] value for the procedure's source location (see
@secref["linecol"]); the @scheme[car] and @scheme[cdr] are never both @secref["linecol"]); the @racket[car] and @racket[cdr] are never both
@scheme[#f]. @racket[#f].
Conceptually, the stack-trace list is the result of Conceptually, the stack-trace list is the result of
@scheme[continuation-mark-set->list] with @scheme[mark-set] and @racket[continuation-mark-set->list] with @racket[mark-set] and
Scheme's private key for procedure-call marks. The implementation may Racket's private key for procedure-call marks. The implementation may
be different, however, and the results may merely approximate the be different, however, and the results may merely approximate the
correct answer. Thus, while the result may contain useful hints to correct answer. Thus, while the result may contain useful hints to
humans about the context of an expression, it is not reliable enough humans about the context of an expression, it is not reliable enough
@ -167,8 +167,8 @@ for programmatic use.
A stack trace is extracted from an exception and displayed by the A stack trace is extracted from an exception and displayed by the
default error display handler (see default error display handler (see
@scheme[error-display-handler]) for exceptions other than @racket[error-display-handler]) for exceptions other than
@scheme[exn:fail:user] (see @scheme[raise-user-error] in @racket[exn:fail:user] (see @racket[raise-user-error] in
@secref["errorproc"]).} @secref["errorproc"]).}
@examples[ @examples[

534
collects/scribblings/reference/contracts.scrbl
View File

File diff suppressed because it is too large Load Diff

62
collects/scribblings/reference/encodings.scrbl
View File

@ -5,31 +5,31 @@
@title[#:tag "encodings"]{Encodings and Locales} @title[#:tag "encodings"]{Encodings and Locales}
When a port is provided to a character-based operation, such as When a port is provided to a character-based operation, such as
@scheme[read-char] or @scheme[read], the port's bytes are read and @racket[read-char] or @racket[read], the port's bytes are read and
interpreted as a UTF-8 encoding of characters. Thus, reading a single interpreted as a UTF-8 encoding of characters. Thus, reading a single
character may require reading multiple bytes, and a procedure like character may require reading multiple bytes, and a procedure like
@scheme[char-ready?] may need to peek several bytes into the stream to @racket[char-ready?] may need to peek several bytes into the stream to
determine whether a character is available. In the case of a byte determine whether a character is available. In the case of a byte
stream that does not correspond to a valid UTF-8 encoding, functions stream that does not correspond to a valid UTF-8 encoding, functions
such as @scheme[read-char] may need to peek one byte ahead in the such as @racket[read-char] may need to peek one byte ahead in the
stream to discover that the stream is not a valid encoding. stream to discover that the stream is not a valid encoding.
When an input port produces a sequence of bytes that is not a valid When an input port produces a sequence of bytes that is not a valid
UTF-8 encoding in a character-reading context, then bytes that UTF-8 encoding in a character-reading context, then bytes that
constitute an invalid sequence are converted to the character constitute an invalid sequence are converted to the character
@schemevalfont{#\uFFFD}. Specifically, bytes 255 and 254 are always converted @racketvalfont{#\uFFFD}. Specifically, bytes 255 and 254 are always converted
to @schemevalfont{#\uFFFD}, bytes in the range 192 to 253 produce to @racketvalfont{#\uFFFD}, bytes in the range 192 to 253 produce
@schemevalfont{#\uFFFD} when they are not followed by bytes that form a valid @racketvalfont{#\uFFFD} when they are not followed by bytes that form a valid
UTF-8 encoding, and bytes in the range 128 to 191 are converted to UTF-8 encoding, and bytes in the range 128 to 191 are converted to
@schemevalfont{#\uFFFD} when they are not part of a valid encoding that was @racketvalfont{#\uFFFD} when they are not part of a valid encoding that was
started by a preceding byte in the range 192 to 253. To put it another started by a preceding byte in the range 192 to 253. To put it another
way, when reading a sequence of bytes as characters, a minimal set of way, when reading a sequence of bytes as characters, a minimal set of
bytes are changed to the encoding of @schemevalfont{#\uFFFD} so that the bytes are changed to the encoding of @racketvalfont{#\uFFFD} so that the
entire sequence of bytes is a valid UTF-8 encoding. entire sequence of bytes is a valid UTF-8 encoding.
See @secref["bytestrings"] for procedures that facilitate See @secref["bytestrings"] for procedures that facilitate
conversions using UTF-8 or other encodings. See also conversions using UTF-8 or other encodings. See also
@scheme[reencode-input-port] and @scheme[reencode-output-port] for @racket[reencode-input-port] and @racket[reencode-output-port] for
obtaining a UTF-8-based port from one that uses a different encoding obtaining a UTF-8-based port from one that uses a different encoding
of characters. of characters.
@ -39,58 +39,58 @@ culture-specific interpretation of character sequences. In particular,
a locale determines how strings are ``alphabetized,'' how a lowercase a locale determines how strings are ``alphabetized,'' how a lowercase
character is converted to an uppercase character, and how strings are character is converted to an uppercase character, and how strings are
compared without regard to case. String operations such as compared without regard to case. String operations such as
@scheme[string-ci=?] are @italic{not} sensitive to the current locale, @racket[string-ci=?] are @italic{not} sensitive to the current locale,
but operations such as @scheme[string-locale-ci=?] (see but operations such as @racket[string-locale-ci=?] (see
@secref["strings"]) produce results consistent with the current @secref["strings"]) produce results consistent with the current
locale. locale.
A locale also designates a particular encoding of code-point sequences A locale also designates a particular encoding of code-point sequences
into byte sequences. Scheme generally ignores this aspect of the into byte sequences. Racket generally ignores this aspect of the
locale, with a few notable exceptions: command-line arguments passed locale, with a few notable exceptions: command-line arguments passed
to Scheme as byte strings are converted to character strings using the to Racket as byte strings are converted to character strings using the
locale's encoding; command-line strings passed as byte strings to locale's encoding; command-line strings passed as byte strings to
other processes (through @scheme[subprocess]) are converted to byte other processes (through @racket[subprocess]) are converted to byte
strings using the locale's encoding; environment variables are strings using the locale's encoding; environment variables are
converted to and from strings using the locale's encoding; filesystem converted to and from strings using the locale's encoding; filesystem
paths are converted to and from strings (for display purposes) using paths are converted to and from strings (for display purposes) using
the locale's encoding; and, finally, Scheme provides functions such as the locale's encoding; and, finally, Racket provides functions such as
@scheme[string->bytes/locale] to specifically invoke a locale-specific @racket[string->bytes/locale] to specifically invoke a locale-specific
encoding. encoding.
A Unix user selects a locale by setting environment variables, such as A Unix user selects a locale by setting environment variables, such as
@envvar{LC_ALL}. Under Windows and Mac OS X, the operating system @envvar{LC_ALL}. Under Windows and Mac OS X, the operating system
provides other mechanisms for setting the locale. Within Scheme, the provides other mechanisms for setting the locale. Within Racket, the
current locale can be changed by setting the @scheme[current-locale] current locale can be changed by setting the @racket[current-locale]
parameter. The locale name within Scheme is a string, and the parameter. The locale name within Racket is a string, and the
available locale names depend on the platform and its configuration, available locale names depend on the platform and its configuration,
but the @scheme[""] locale means the current user's default locale; but the @racket[""] locale means the current user's default locale;
under Windows and Mac OS X, the encoding for @scheme[""] is always under Windows and Mac OS X, the encoding for @racket[""] is always
UTF-8, and locale-sensitive operations use the operating system's UTF-8, and locale-sensitive operations use the operating system's
native interface. (In particular, setting the @envvar{LC_ALL} and native interface. (In particular, setting the @envvar{LC_ALL} and
@envvar{LC_CTYPE} environment variables do not affect the locale @envvar{LC_CTYPE} environment variables do not affect the locale
@scheme[""] under Mac OS X. Use @scheme[getenv] and @racket[""] under Mac OS X. Use @racket[getenv] and
@scheme[current-locale] to explicitly install the @racket[current-locale] to explicitly install the
environment-specified locale, if desired.) Setting the current locale environment-specified locale, if desired.) Setting the current locale
to @scheme[#f] makes locale-sensitive operations locale-insensitive, to @racket[#f] makes locale-sensitive operations locale-insensitive,
which means using the Unicode mapping for case operations and using which means using the Unicode mapping for case operations and using
UTF-8 for encoding. UTF-8 for encoding.
@defparam[current-locale locale (or/c string? #f)]{ @defparam[current-locale locale (or/c string? #f)]{
A parameter that determines the current @tech{locale} for A parameter that determines the current @tech{locale} for
procedures such as @scheme[string-locale-ci=?]. procedures such as @racket[string-locale-ci=?].
When locale sensitivity is disabled by setting the parameter to When locale sensitivity is disabled by setting the parameter to
@scheme[#f], strings are compared (etc.) in a fully portable manner, @racket[#f], strings are compared (etc.) in a fully portable manner,
which is the same as the standard procedures. Otherwise, strings are which is the same as the standard procedures. Otherwise, strings are
interpreted according to a locale setting (in the sense of the C interpreted according to a locale setting (in the sense of the C
library's @tt{setlocale}). The @scheme[""] locale is always a synonym library's @tt{setlocale}). The @racket[""] locale is always a synonym
for the current machine's default locale, and it is the default. The for the current machine's default locale, and it is the default. The
@scheme["C"] locale is also always available; setting the locale to @racket["C"] locale is also always available; setting the locale to
@scheme["C"] is the same as disabling locale sensitivity with @racket["C"] is the same as disabling locale sensitivity with
@scheme[#f] only when string operations are restricted to the first @racket[#f] only when string operations are restricted to the first
128 characters. Other locale names are platform-specific. 128 characters. Other locale names are platform-specific.
String or character printing with @scheme[write] is not affected by String or character printing with @racket[write] is not affected by
the parameter, and neither are symbol case or regular expressions (see the parameter, and neither are symbol case or regular expressions (see
@secref["regexp"]).} @secref["regexp"]).}

262
collects/scribblings/reference/eval.scrbl
View File

@ -8,23 +8,23 @@
A parameter that determines the current @deftech{evaluation handler}. A parameter that determines the current @deftech{evaluation handler}.
The evaluation handler is a procedure that takes a top-level form and The evaluation handler is a procedure that takes a top-level form and
evaluates it, returning the resulting values. The @tech{evaluation evaluates it, returning the resulting values. The @tech{evaluation
handler} is called by @scheme[eval], @scheme[eval-syntax], the default handler} is called by @racket[eval], @racket[eval-syntax], the default
@tech{load handler}, and @scheme[read-eval-print-loop] to evaluate a @tech{load handler}, and @racket[read-eval-print-loop] to evaluate a
top-level form. The handler should evaluate its argument in tail top-level form. The handler should evaluate its argument in tail
position. position.
The @scheme[_top-level-form] provided to the handler can be a The @racket[_top-level-form] provided to the handler can be a
@tech{syntax object}, a compiled form, a compiled form wrapped as a @tech{syntax object}, a compiled form, a compiled form wrapped as a
syntax object, or an arbitrary datum. syntax object, or an arbitrary datum.
The default handler converts an arbitrary datum to a syntax object The default handler converts an arbitrary datum to a syntax object
using @scheme[datum->syntax], and then enriches its @tech{lexical using @racket[datum->syntax], and then enriches its @tech{lexical
information} in the same way as @scheme[eval]. (If information} in the same way as @racket[eval]. (If
@scheme[_top-level-form] is a syntax object, then its @tech{lexical @racket[_top-level-form] is a syntax object, then its @tech{lexical
information} is not enriched.) The default evaluation handler information} is not enriched.) The default evaluation handler
partially expands the form to splice the body of top-level partially expands the form to splice the body of top-level
@scheme[begin] forms into the top level (see @racket[begin] forms into the top level (see
@scheme[expand-to-top-form]), and then individually compiles and @racket[expand-to-top-form]), and then individually compiles and
evaluates each spliced form before continuing to expand, compile, and evaluates each spliced form before continuing to expand, compile, and
evaluate later forms.} evaluate later forms.}
@ -34,42 +34,42 @@ evaluate later forms.}
any]{ any]{
Calls the current @tech{evaluation handler} to evaluate Calls the current @tech{evaluation handler} to evaluate
@scheme[top-level-form]. The @tech{evaluation handler} is called in @racket[top-level-form]. The @tech{evaluation handler} is called in
tail position with respect to the @scheme[eval] call, and tail position with respect to the @racket[eval] call, and
@scheme[parameterize]d to set @scheme[current-namespace] to @racket[parameterize]d to set @racket[current-namespace] to
@scheme[namespace]. @racket[namespace].
If @scheme[top-level-form] is a syntax object whose datum is not a If @racket[top-level-form] is a syntax object whose datum is not a
compiled form, then its @tech{lexical information} is enriched before compiled form, then its @tech{lexical information} is enriched before
it is sent to the @tech{evaluation handler}: it is sent to the @tech{evaluation handler}:
@itemize[ @itemize[
@item{If @scheme[top-level-form] is a pair whose @scheme[car] is a @item{If @racket[top-level-form] is a pair whose @racket[car] is a
symbol or identifier, and if applying symbol or identifier, and if applying
@scheme[namespace-syntax-introduce] to the @racket[namespace-syntax-introduce] to the
(@scheme[datum->syntax]-converted) identifier produces an (@racket[datum->syntax]-converted) identifier produces an
identifier bound to @scheme[module] in a @tech{phase level} identifier bound to @racket[module] in a @tech{phase level}
that corresponds to @scheme[namespace]'s @tech{base phase}, that corresponds to @racket[namespace]'s @tech{base phase},
then only that identifier is enriched.} then only that identifier is enriched.}
@item{For any other @scheme[top-level-form], @item{For any other @racket[top-level-form],
@scheme[namespace-syntax-introduce] is applied to the entire @racket[namespace-syntax-introduce] is applied to the entire
syntax object.} syntax object.}
] ]
For interactive evaluation in the style of For interactive evaluation in the style of
@scheme[read-eval-print-loop] and @scheme[load], wrap each expression @racket[read-eval-print-loop] and @racket[load], wrap each expression
with @schemeidfont{#%top-interaction}, which is normally bound to with @racketidfont{#%top-interaction}, which is normally bound to
@scheme[#%top-interaction], before passing it to @scheme[eval].} @racket[#%top-interaction], before passing it to @racket[eval].}
@defproc[(eval-syntax [stx syntax?] @defproc[(eval-syntax [stx syntax?]
[namespace namespace? (current-namespace)]) [namespace namespace? (current-namespace)])
any]{ any]{
Like @scheme[eval], except that @scheme[stx] must be a syntax object, Like @racket[eval], except that @racket[stx] must be a syntax object,
and its lexical context is not enriched before it is passed to the and its lexical context is not enriched before it is passed to the
@tech{evaluation handler}.} @tech{evaluation handler}.}
@ -78,39 +78,39 @@ and its lexical context is not enriched before it is passed to the
A parameter that determines the current @deftech{load handler} to load A parameter that determines the current @deftech{load handler} to load
top-level forms from a file. The @tech{load handler} is called by top-level forms from a file. The @tech{load handler} is called by
@scheme[load], @scheme[load-relative], @scheme[load/cd], and the @racket[load], @racket[load-relative], @racket[load/cd], and the
default @tech{compiled-load handler}. default @tech{compiled-load handler}.
A load handler takes two arguments: a path (see A load handler takes two arguments: a path (see
@secref["pathutils"]) and an expected module name. The expected @secref["pathutils"]) and an expected module name. The expected
module name is a symbol when the call is to load a module declaration module name is a symbol when the call is to load a module declaration
in response to a @scheme[require] (in which case the file should in response to a @racket[require] (in which case the file should
contain a module declaration), or @scheme[#f] for any other load. contain a module declaration), or @racket[#f] for any other load.
The default load handler reads forms from the file in The default load handler reads forms from the file in
@scheme[read-syntax] mode with line-counting enabled for the file @racket[read-syntax] mode with line-counting enabled for the file
port, unless the path has a @scheme[".zo"] suffix. It also port, unless the path has a @racket[".zo"] suffix. It also
@scheme[parameterize]s each read to set both @racket[parameterize]s each read to set both
@scheme[read-accept-compiled] and @scheme[read-accept-reader] to @racket[read-accept-compiled] and @racket[read-accept-reader] to
@scheme[#t]. In addition, if @scheme[load-on-demand-enabled] is @racket[#t]. In addition, if @racket[load-on-demand-enabled] is
@scheme[#t], then @scheme[read-on-demand-source] is effectively set to @racket[#t], then @racket[read-on-demand-source] is effectively set to
the @tech{cleanse}d, absolute form of @scheme[path] during the the @tech{cleanse}d, absolute form of @racket[path] during the
@scheme[read-syntax] call. After reading a single form, the form is @racket[read-syntax] call. After reading a single form, the form is
passed to the current @tech{evaluation handler}, wrapping the passed to the current @tech{evaluation handler}, wrapping the
evaluation in a continuation prompt (see evaluation in a continuation prompt (see
@scheme[call-with-continuation-prompt]) for the default continuation @racket[call-with-continuation-prompt]) for the default continuation
prompt tag with handler that propagates the abort to the continuation prompt tag with handler that propagates the abort to the continuation
of the @scheme[load] call. of the @racket[load] call.
If the second argument to the load handler is a symbol, then: If the second argument to the load handler is a symbol, then:
@itemize[ @itemize[
@item{The @scheme[read-syntax] from the file is additionally @item{The @racket[read-syntax] from the file is additionally
@scheme[parameterize]d as follows (to provide consistent reading @racket[parameterize]d as follows (to provide consistent reading
of module source): of module source):
@schemeblock[ @racketblock[
(current-readtable #f) (current-readtable #f)
(read-case-sensitive #t) (read-case-sensitive #t)
(read-square-bracket-as-paren #t) (read-square-bracket-as-paren #t)
@ -126,59 +126,59 @@ If the second argument to the load handler is a symbol, then:
(read-accept-reader #t) (read-accept-reader #t)
]} ]}
@item{If the read result is not a @schemeidfont{module} form with the @item{If the read result is not a @racketidfont{module} form with the
expected name, or if a second @scheme[read-syntax] does not expected name, or if a second @racket[read-syntax] does not
produce an end-of-file, then the @exnraise[exn:fail] without produce an end-of-file, then the @exnraise[exn:fail] without
evaluating the form that was read from the file.} evaluating the form that was read from the file.}
@item{The @tech{lexical information} of the initial @item{The @tech{lexical information} of the initial
@schemeidfont{module} identifier is enriched with a binding for @racketidfont{module} identifier is enriched with a binding for
@scheme[module], so that the form corresponds to a module @racket[module], so that the form corresponds to a module
declaration independent of the current namespace's bindings.} declaration independent of the current namespace's bindings.}
] ]
If the second argument to the load handler is @scheme[#f], then each If the second argument to the load handler is @racket[#f], then each
expression read from the file is wrapped with expression read from the file is wrapped with
@schemeidfont{#%top-interaction}, which is normally bound to @racketidfont{#%top-interaction}, which is normally bound to
@scheme[#%top-interaction], before passing it to the @tech{evaluation @racket[#%top-interaction], before passing it to the @tech{evaluation
handler}. handler}.
The return value from the default @tech{load handler} is the value of The return value from the default @tech{load handler} is the value of
the last form from the loaded file, or @|void-const| if the file the last form from the loaded file, or @|void-const| if the file
contains no forms. If the given path is a relative path, then it is contains no forms. If the given path is a relative path, then it is
resolved using the value of @scheme[current-directory].} resolved using the value of @racket[current-directory].}
@defproc[(load [file path-string?]) any]{ @defproc[(load [file path-string?]) any]{
Calls the current @tech{load handler} in tail position. The call is Calls the current @tech{load handler} in tail position. The call is
@scheme[parameterized] to set @scheme[current-load-relative-directory] @racket[parameterized] to set @racket[current-load-relative-directory]
to the directory of @scheme[file], which is resolved relative to to the directory of @racket[file], which is resolved relative to
the value of @scheme[current-directory].} the value of @racket[current-directory].}
@defproc[(load-relative [file path-string?]) any]{ @defproc[(load-relative [file path-string?]) any]{
Like @scheme[load/use-compiled], but when @scheme[file] is a relative Like @racket[load/use-compiled], but when @racket[file] is a relative
path, it is resolved using the value of path, it is resolved using the value of
@scheme[current-load-relative-directory] instead of the value of @racket[current-load-relative-directory] instead of the value of
@scheme[current-directory] if the former is not @scheme[#f], otherwise @racket[current-directory] if the former is not @racket[#f], otherwise
@scheme[current-directory] is used.} @racket[current-directory] is used.}
@defproc[(load/cd [file path-string?]) any]{ @defproc[(load/cd [file path-string?]) any]{
Like @scheme[load], but @scheme[load/cd] sets both Like @racket[load], but @racket[load/cd] sets both
@scheme[current-directory] and @racket[current-directory] and
@scheme[current-load-relative-directory] before calling the @tech{load @racket[current-load-relative-directory] before calling the @tech{load
handler}.} handler}.}
@defparam[current-load-extension proc (path? (or/c symbol? #f) . -> . any)]{ @defparam[current-load-extension proc (path? (or/c symbol? #f) . -> . any)]{
A parameter that determines a @deftech{extension-load handler}, which is A parameter that determines a @deftech{extension-load handler}, which is
called by @scheme[load-extension] and the default @tech{compiled-load called by @racket[load-extension] and the default @tech{compiled-load
handler}. handler}.
An @tech{extension-load handler} takes the same arguments as a An @tech{extension-load handler} takes the same arguments as a
@ -193,26 +193,26 @@ primitives. See @other-manual['(lib
@defproc[(load-extension [file path-string?]) any]{ @defproc[(load-extension [file path-string?]) any]{
Sets @scheme[current-load-relative-directory] like @scheme[load], and Sets @racket[current-load-relative-directory] like @racket[load], and
calls the @tech{extension-load handler} in tail position.} calls the @tech{extension-load handler} in tail position.}
@defproc[(load-relative-extension [file path-string?]) any]{ @defproc[(load-relative-extension [file path-string?]) any]{
Like @scheme[load-exension], but resolves @scheme[file] using Like @racket[load-exension], but resolves @racket[file] using
@scheme[current-load-relative-directory] like @scheme[load-relative].} @racket[current-load-relative-directory] like @racket[load-relative].}
@defparam[current-load/use-compiled proc (path? (or/c symbol? #f) . -> . any)]{ @defparam[current-load/use-compiled proc (path? (or/c symbol? #f) . -> . any)]{
A parameter that determines the current @deftech{compiled-load A parameter that determines the current @deftech{compiled-load
handler} to load from a file that may have a compiled form. The handler} to load from a file that may have a compiled form. The
@tech{compiled-load handler} is called by @scheme[load/use-compiled]. @tech{compiled-load handler} is called by @racket[load/use-compiled].
The protocol for a @tech{compiled-load handler} is the same as for the The protocol for a @tech{compiled-load handler} is the same as for the
@tech{load handler} (see @scheme[current-load]), except that a @tech{load handler} (see @racket[current-load]), except that a
@tech{compiled-load handler} is expected to set @tech{compiled-load handler} is expected to set
@scheme[current-load-relative-directory] itself. The default @racket[current-load-relative-directory] itself. The default
@tech{compiled-load handler}, however, checks for a @filepath{.ss} @tech{compiled-load handler}, however, checks for a @filepath{.ss}
file when the given path ends with @filepath{.rkt}, no @filepath{.rkt} file when the given path ends with @filepath{.rkt}, no @filepath{.rkt}
file exists, and when the handler's second argument is a symbol. In file exists, and when the handler's second argument is a symbol. In
@ -222,39 +222,39 @@ addition, the default @tech{compiled-load handler} checks for
X) files. X) files.
The check for a compiled file occurs whenever the given path The check for a compiled file occurs whenever the given path
@scheme[_file] ends with any extension (e.g., @filepath{.rkt} or @racket[_file] ends with any extension (e.g., @filepath{.rkt} or
@filepath{.scrbl}), and the check consults the subdirectories @filepath{.scrbl}), and the check consults the subdirectories
indicated by the @scheme[use-compiled-file-paths] parameter relative indicated by the @racket[use-compiled-file-paths] parameter relative
to @scheme[_file]. The subdirectories are checked in order. A to @racket[_file]. The subdirectories are checked in order. A
@filepath{.zo} version of the file (whose name is formed by passing @filepath{.zo} version of the file (whose name is formed by passing
@scheme[_file] and @scheme[#".zo"] to @scheme[path-add-suffix]) is @racket[_file] and @racket[#".zo"] to @racket[path-add-suffix]) is
loaded if it exists directly in one of the indicated subdirectories, loaded if it exists directly in one of the indicated subdirectories,
or a @filepath{.so}/@filepath{.dll}/@filepath{.dylib} version of the or a @filepath{.so}/@filepath{.dll}/@filepath{.dylib} version of the
file is loaded if it exists within a @filepath{native} subdirectory of file is loaded if it exists within a @filepath{native} subdirectory of
a @scheme[use-compiled-file-paths] directory, in an even deeper a @racket[use-compiled-file-paths] directory, in an even deeper
subdirectory as named by @scheme[system-library-subpath]. A compiled subdirectory as named by @racket[system-library-subpath]. A compiled
file is loaded only if its modification date is not older than the file is loaded only if its modification date is not older than the
date for @scheme[_file]. If both @filepath{.zo} and date for @racket[_file]. If both @filepath{.zo} and
@filepath{.so}/@filepath{.dll}/@filepath{.dylib} files are available, @filepath{.so}/@filepath{.dll}/@filepath{.dylib} files are available,
the @filepath{.so}/@filepath{.dll}/@filepath{.dylib} file is used. If the @filepath{.so}/@filepath{.dll}/@filepath{.dylib} file is used. If
@scheme[_file] ends with @filepath{.rkt}, no such file exists, the @racket[_file] ends with @filepath{.rkt}, no such file exists, the
handler's second argument is a symbol, and a @filepath{.ss} file handler's second argument is a symbol, and a @filepath{.ss} file
exists, then @filepath{.zo} and exists, then @filepath{.zo} and
@filepath{.so}/@filepath{.dll}/@filepath{.dylib} files are used only @filepath{.so}/@filepath{.dll}/@filepath{.dylib} files are used only
with names based on @scheme[_file] with its suffixed replaced by with names based on @racket[_file] with its suffixed replaced by
@filepath{.ss}. @filepath{.ss}.
While a @filepath{.zo}, @filepath{.so}, @filepath{.dll}, or While a @filepath{.zo}, @filepath{.so}, @filepath{.dll}, or
@filepath{.dylib} file is loaded, the current @scheme[load-relative] @filepath{.dylib} file is loaded, the current @racket[load-relative]
directory is set to the directory of the original @scheme[_file]. If directory is set to the directory of the original @racket[_file]. If
the file to be loaded has the suffix @filepath{.ss} while the the file to be loaded has the suffix @filepath{.ss} while the
requested file has the suffix @filepath{.rkt}, then the requested file has the suffix @filepath{.rkt}, then the
@scheme[current-module-declare-source] parameter is set to the full @racket[current-module-declare-source] parameter is set to the full
path of the loaded file, otherwise the path of the loaded file, otherwise the
@scheme[current-module-declare-source] parameter is set to @racket[current-module-declare-source] parameter is set to
@scheme[#f]. @racket[#f].
If the original @scheme[_file] is loaded or a @filepath{.zo} variant is If the original @racket[_file] is loaded or a @filepath{.zo} variant is
loaded, the @tech{load handler} is called to load the file. If any loaded, the @tech{load handler} is called to load the file. If any
other kind of file is loaded, the @tech{extension-load handler} is other kind of file is loaded, the @tech{extension-load handler} is
called.} called.}
@ -268,10 +268,10 @@ Calls the current @tech{compiled-load handler} in tail position.}
@defparam[current-load-relative-directory path @defparam[current-load-relative-directory path
(or/c (and/c path-string? complete-path?) #f)]{ (or/c (and/c path-string? complete-path?) #f)]{
A parameter that is set by @scheme[load], @scheme[load-relative], A parameter that is set by @racket[load], @racket[load-relative],
@scheme[load-extension], @scheme[load-relative-extension], and the @racket[load-extension], @racket[load-relative-extension], and the
default @tech{compiled-load handler}, and used by default @tech{compiled-load handler}, and used by
@scheme[load-relative], @scheme[load-relative-extension], and the @racket[load-relative], @racket[load-relative-extension], and the
default @tech{compiled-load handler}. default @tech{compiled-load handler}.
When a new path or string is provided as the parameter's value, it is When a new path or string is provided as the parameter's value, it is
@ -281,27 +281,27 @@ path. (The directory need not exist.)}
@defparam*[use-compiled-file-paths paths (listof path-string?) (listof path?)]{ @defparam*[use-compiled-file-paths paths (listof path-string?) (listof path?)]{
A list of relative paths, which defaults to @scheme[(list A list of relative paths, which defaults to @racket[(list
(string->path "compiled"))]. It is used by the @tech{compiled-load (string->path "compiled"))]. It is used by the @tech{compiled-load
handler} (see @scheme[current-load/use-compiled]).} handler} (see @racket[current-load/use-compiled]).}
@defproc[(read-eval-print-loop) any]{ @defproc[(read-eval-print-loop) any]{
Starts a new @deftech{REPL} using the current input, output, and error Starts a new @deftech{REPL} using the current input, output, and error
ports. The REPL wraps each expression to evaluate with ports. The REPL wraps each expression to evaluate with
@schemeidfont{#%top-interaction}, which is normally bound to @racketidfont{#%top-interaction}, which is normally bound to
@scheme[#%top-interaction], and it wraps each evaluation with a @racket[#%top-interaction], and it wraps each evaluation with a
continuation prompt using the default continuation prompt tag and continuation prompt using the default continuation prompt tag and
prompt handler (see @scheme[call-with-continuation-prompt]). The REPL prompt handler (see @racket[call-with-continuation-prompt]). The REPL
also wraps the read and print operations with a prompt for the default also wraps the read and print operations with a prompt for the default
tag whose handler ignores abort arguments and continues the loop. The tag whose handler ignores abort arguments and continues the loop. The
@scheme[read-eval-print-loop] procedure does not return until @racket[read-eval-print-loop] procedure does not return until
@scheme[eof] is read, at which point it returns @|void-const|. @racket[eof] is read, at which point it returns @|void-const|.
The @scheme[read-eval-print-loop] procedure can be configured through The @racket[read-eval-print-loop] procedure can be configured through
the @scheme[current-prompt-read], @scheme[current-eval], and the @racket[current-prompt-read], @racket[current-eval], and
@scheme[current-print] parameters.} @racket[current-print] parameters.}
@defparam[current-prompt-read proc (-> any)]{ @defparam[current-prompt-read proc (-> any)]{
@ -309,14 +309,14 @@ the @scheme[current-prompt-read], @scheme[current-eval], and
A parameter that determines a @deftech{prompt read handler}, which is A parameter that determines a @deftech{prompt read handler}, which is
a procedure that takes no arguments, displays a prompt string, and a procedure that takes no arguments, displays a prompt string, and
returns a top-level form to evaluate. The prompt read handler is returns a top-level form to evaluate. The prompt read handler is
called by @scheme[read-eval-print-loop], and the handler typically called by @racket[read-eval-print-loop], and the handler typically
should call the @tech{read interaction handler} (as determined by the should call the @tech{read interaction handler} (as determined by the
@scheme[current-read-interaction] parameter) after printing a prompt. @racket[current-read-interaction] parameter) after printing a prompt.
The default prompt read handler prints @litchar{> } and returns the The default prompt read handler prints @litchar{> } and returns the
result of result of
@schemeblock[ @racketblock[
(let ([in (current-input-port)]) (let ([in (current-input-port)])
((current-read-interaction) (object-name in) in)) ((current-read-interaction) (object-name in) in))
]} ]}
@ -328,10 +328,10 @@ A parameter that determines the current @deftech{read interaction
handler}, which is procedure that takes an arbitrary value and an handler}, which is procedure that takes an arbitrary value and an
input port and returns an expression read from the input port. input port and returns an expression read from the input port.
The default read interaction handler accepts @scheme[_src] and The default read interaction handler accepts @racket[_src] and
@scheme[_in] and returns @racket[_in] and returns
@schemeblock[ @racketblock[
(parameterize ([read-accept-reader #t]) (parameterize ([read-accept-reader #t])
(read-syntax _src _in)) (read-syntax _src _in))
]} ]}
@ -340,12 +340,12 @@ The default read interaction handler accepts @scheme[_src] and
@defparam[current-print proc (any/c -> any)]{ @defparam[current-print proc (any/c -> any)]{
A parameter that determines the @deftech{print handler} that is called A parameter that determines the @deftech{print handler} that is called
by @scheme[read-eval-print-loop] to print the result of an evaluation by @racket[read-eval-print-loop] to print the result of an evaluation
(and the result is ignored). (and the result is ignored).
The default @tech{print handler} @scheme[print]s the value to the The default @tech{print handler} @racket[print]s the value to the
current output port (as determined by the current output port (as determined by the
@scheme[current-output-port] parameter) and then outputs a newline, @racket[current-output-port] parameter) and then outputs a newline,
except that it prints nothing when the value is @|void-const|.} except that it prints nothing when the value is @|void-const|.}
@ -356,20 +356,20 @@ The @tech{compilation handler} is a procedure that takes a top-level form and
returns a compiled form; see see @secref["compilation-model"] for returns a compiled form; see see @secref["compilation-model"] for
more information on compilation. more information on compilation.
The @tech{compilation handler} is called by @scheme[compile], and The @tech{compilation handler} is called by @racket[compile], and
indirectly by the default @tech{evaluation handler} and the default indirectly by the default @tech{evaluation handler} and the default
@tech{load handler}. @tech{load handler}.
The handler's second argument is @scheme[#t] if the compiled form will The handler's second argument is @racket[#t] if the compiled form will
be used only for immediate evaluation, or @scheme[#f] if the compiled be used only for immediate evaluation, or @racket[#f] if the compiled
form may be saved for later use; the default compilation handler is form may be saved for later use; the default compilation handler is
optimized for the special case of immediate evaluation. optimized for the special case of immediate evaluation.
When a compiled form is written to an output port, the written form When a compiled form is written to an output port, the written form
starts with @litchar{#~}. These forms are essentially assembly code starts with @litchar{#~}. These forms are essentially assembly code
for PLT Scheme, and reading such an form produces a compiled form (as for Racket, and reading such an form produces a compiled form (as
long as the @scheme[read-accept-compiled] parameter is set to long as the @racket[read-accept-compiled] parameter is set to
@scheme[#t]). @racket[#t]).
When a compiled form contains syntax object constants, the When a compiled form contains syntax object constants, the
@litchar{#~}-marshaled form drops source-location information and @litchar{#~}-marshaled form drops source-location information and
@ -378,13 +378,13 @@ properties (@secref["stxprops"]) for the @tech{syntax objects}.
Compiled code parsed from @litchar{#~} may contain references to Compiled code parsed from @litchar{#~} may contain references to
unexported or protected bindings from a module. At read time, such unexported or protected bindings from a module. At read time, such
references are associated with the current code inspector (see references are associated with the current code inspector (see
@scheme[current-code-inspector]), and the code will only execute if @racket[current-code-inspector]), and the code will only execute if
that inspector controls the relevant module invocation (see that inspector controls the relevant module invocation (see
@secref["modprotect"]). @secref["modprotect"]).
A compiled-form object may contain @tech{uninterned} symbols (see A compiled-form object may contain @tech{uninterned} symbols (see
@secref["symbols"]) that were created by @scheme[gensym] or @secref["symbols"]) that were created by @racket[gensym] or
@scheme[string->uninterned-symbol]. When the compiled object is read @racket[string->uninterned-symbol]. When the compiled object is read
via @litchar{#~}, each uninterned symbol in the original form is via @litchar{#~}, each uninterned symbol in the original form is
mapped to a new uninterned symbol, where multiple instances of a mapped to a new uninterned symbol, where multiple instances of a
single symbol are consistently mapped to the same new symbol. The single symbol are consistently mapped to the same new symbol. The
@ -394,30 +394,30 @@ generated indirectly during expansion and compilation, are saved and
restored consistently through @litchar{#~}. restored consistently through @litchar{#~}.
Due to the restrictions on @tech{uninterned} symbols in @litchar{#~}, Due to the restrictions on @tech{uninterned} symbols in @litchar{#~},
do not use @scheme[gensym] or @scheme[string->uninterned-symbol] to do not use @racket[gensym] or @racket[string->uninterned-symbol] to
construct an identifier for a top-level or module binding. Instead, construct an identifier for a top-level or module binding. Instead,
generate distinct identifiers either with generate distinct identifiers either with
@scheme[generate-temporaries] or by applying the result of @racket[generate-temporaries] or by applying the result of
@scheme[make-syntax-introducer] to an existing identifier; those @racket[make-syntax-introducer] to an existing identifier; those
functions will lead to top-level and module bindings with functions will lead to top-level and module bindings with
@tech{unreadable symbol}ic names.} @tech{unreadable symbol}ic names.}
@defproc[(compile [top-level-form any/c]) compiled-expression?]{ @defproc[(compile [top-level-form any/c]) compiled-expression?]{
Like @scheme[eval], but calls the current @tech{compilation handler} in Like @racket[eval], but calls the current @tech{compilation handler} in
tail position with @scheme[top-level-form].} tail position with @racket[top-level-form].}
@defproc[(compile-syntax [stx syntax?]) compiled-expression?]{ @defproc[(compile-syntax [stx syntax?]) compiled-expression?]{
Like @scheme[eval-syntax], but calls the current @tech{compilation Like @racket[eval-syntax], but calls the current @tech{compilation
handler} in tail position with @scheme[stx].} handler} in tail position with @racket[stx].}
@defproc[(compiled-expression? [v any/c]) boolean?]{ @defproc[(compiled-expression? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] is a compiled form, @scheme[#f] Returns @racket[#t] if @racket[v] is a compiled form, @racket[#f]
otherwise.} otherwise.}
@ -426,10 +426,10 @@ otherwise.}
A parameter that determines how a module declaration is compiled. A parameter that determines how a module declaration is compiled.
When constants are enforced, and when the macro-expanded body of a When constants are enforced, and when the macro-expanded body of a
module contains no @scheme[set!] assignment to a particular variable module contains no @racket[set!] assignment to a particular variable
defined within the module, then the variable is marked as constant defined within the module, then the variable is marked as constant
when the definition is evaluated. Afterward, the variable's value when the definition is evaluated. Afterward, the variable's value
cannot be assigned or undefined through @scheme[module->namespace], cannot be assigned or undefined through @racket[module->namespace],
and it cannot be defined by redeclaring the module. and it cannot be defined by redeclaring the module.
Enforcing constants allows the compiler to inline some variable Enforcing constants allows the compiler to inline some variable
@ -439,14 +439,14 @@ generate code that skips certain run-time checks.}
@defboolparam[compile-allow-set!-undefined allow?]{ @defboolparam[compile-allow-set!-undefined allow?]{
A parameter that determines how a @scheme[set!] expression is compiled A parameter that determines how a @racket[set!] expression is compiled
when it mutates a global variable. If the value of this parameter is a when it mutates a global variable. If the value of this parameter is a
true value, @scheme[set!] expressions for global variables are true value, @racket[set!] expressions for global variables are
compiled so that the global variable is set even if it was not compiled so that the global variable is set even if it was not
previously defined. Otherwise, @scheme[set!] expressions for global previously defined. Otherwise, @racket[set!] expressions for global
variables are compiled to raise the variables are compiled to raise the
@scheme[exn:fail:contract:variable] exception if the global variable @racket[exn:fail:contract:variable] exception if the global variable
is not defined at the time the @scheme[set!] is performed. Note that is not defined at the time the @racket[set!] is performed. Note that
this parameter is used when an expression is @italic{compiled}, not this parameter is used when an expression is @italic{compiled}, not
when it is @italic{evaluated}.} when it is @italic{evaluated}.}
@ -455,22 +455,22 @@ when it is @italic{evaluated}.}
A parameter that determines whether compilation should avoid A parameter that determines whether compilation should avoid
function-call inlining and other optimizations that may cause function-call inlining and other optimizations that may cause
information to be lost from stack traces (as reported by information to be lost from stack traces (as reported by
@scheme[continuation-mark-set->context]). The default is @scheme[#f], @racket[continuation-mark-set->context]). The default is @racket[#f],
which allows such optimizations.} which allows such optimizations.}
@defboolparam[eval-jit-enabled on?]{ @defboolparam[eval-jit-enabled on?]{
A parameter that determines whether the native-code just-in-time A parameter that determines whether the native-code just-in-time
compiler (JIT) is enabled for code (compiled or not) that is passed to compiler (JIT) is enabled for code (compiled or not) that is passed to
the default evaluation handler. The default is @scheme[#t], unless the default evaluation handler. The default is @racket[#t], unless
the JIT is disabled through the @Flag{j}/@DFlag{no-jit} command-line the JIT is disabled through the @Flag{j}/@DFlag{no-jit} command-line
flag to stand-alone MzScheme (or MrEd), or through the flag to stand-alone Racket (or GRacket), or through the
@as-index{@envvar{PLTNOMZJIT}} environment variable (set to any @as-index{@envvar{PLTNOMZJIT}} environment variable (set to any
value).} value).}
@defboolparam[load-on-demand-enabled on?]{ @defboolparam[load-on-demand-enabled on?]{
A parameter that determines whether the default @tech{load handler} A parameter that determines whether the default @tech{load handler}
sets @scheme[read-on-demand-source]. See @scheme[current-load] for sets @racket[read-on-demand-source]. See @racket[current-load] for
more information. The default is @scheme[#t], unless it is disabled more information. The default is @racket[#t], unless it is disabled
through the @Flag{d}/@DFlag{no-delay} command-line flag.} through the @Flag{d}/@DFlag{no-delay} command-line flag.}

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

@ -13,7 +13,7 @@
@section-index["poll"] @section-index["poll"]
A @deftech{synchronizable event} (or just @defterm{event} for short) A @deftech{synchronizable event} (or just @defterm{event} for short)
works with the @scheme[sync] procedure to coordinate synchronization works with the @racket[sync] procedure to coordinate synchronization
among threads. Certain kinds of objects double as events, including among threads. Certain kinds of objects double as events, including
ports and threads. Other kinds of objects exist only for their use as ports and threads. Other kinds of objects exist only for their use as
events. events.
@ -27,156 +27,156 @@ when it is ready, then the event produces a particular
Synchronizing an event may affect the state of the event. For example, Synchronizing an event may affect the state of the event. For example,
when synchronizing a semaphore, then the semaphore's internal count is when synchronizing a semaphore, then the semaphore's internal count is
decremented, just as with @scheme[semaphore-wait]. For most kinds of decremented, just as with @racket[semaphore-wait]. For most kinds of
events, however (such as a port), synchronizing does not modify the events, however (such as a port), synchronizing does not modify the
event's state. event's state.
The following act as events in stand-alone MzScheme. An extension or The following act as events in Racket. An extension or embedding
embedding application can extend the set of primitive events --- in application can extend the set of primitive events --- in particular,
particular, an eventspace in MrEd is an event --- and new structure an eventspace in GRacket is an event --- and new structure types can
types can generate events (see @scheme[prop:evt]). generate events (see @racket[prop:evt]).
@itemize[ @itemize[
@item{@scheme[_semaphore] --- a semaphore is ready when @item{@racket[_semaphore] --- a semaphore is ready when
@scheme[semaphore-wait] would not block. @ResultItself{semaphore}.} @racket[semaphore-wait] would not block. @ResultItself{semaphore}.}
@item{@scheme[_semaphore-peek] --- a semaphore-peek event returned by @item{@racket[_semaphore-peek] --- a semaphore-peek event returned by
@scheme[semaphore-peek-evt] applied to @scheme[_semaphore] is ready @racket[semaphore-peek-evt] applied to @racket[_semaphore] is ready
exactly when @scheme[_semaphore] is exactly when @racket[_semaphore] is
ready. @ResultItself{semaphore-peek}.} ready. @ResultItself{semaphore-peek}.}
@item{@scheme[_channel] --- a channel returned by @item{@racket[_channel] --- a channel returned by
@scheme[make-channel] is ready when @scheme[channel-get] would not @racket[make-channel] is ready when @racket[channel-get] would not
block. The channel's result as an event is the same as the block. The channel's result as an event is the same as the
@scheme[channel-get] result.} @racket[channel-get] result.}
@item{@scheme[_channel-put] --- an event returned by @item{@racket[_channel-put] --- an event returned by
@scheme[channel-put-evt] applied to @scheme[_channel] is ready when @racket[channel-put-evt] applied to @racket[_channel] is ready when
@scheme[channel-put] would not block on @racket[channel-put] would not block on
@scheme[_channel]. @ResultItself{channel-put}.} @racket[_channel]. @ResultItself{channel-put}.}
@item{@scheme[_input-port] --- an input port is ready as an event when @item{@racket[_input-port] --- an input port is ready as an event when
@scheme[read-byte] would not block. @ResultItself{input-port}.} @racket[read-byte] would not block. @ResultItself{input-port}.}
@item{@scheme[_output-port] --- an output port is ready when @item{@racket[_output-port] --- an output port is ready when
@scheme[write-bytes-avail] would not block or @racket[write-bytes-avail] would not block or
when the port contains buffered characters and when the port contains buffered characters and
@scheme[write-bytes-avail*] can flush part of the buffer (although @racket[write-bytes-avail*] can flush part of the buffer (although
@scheme[write-bytes-avail] might block). @ResultItself{output-port}.} @racket[write-bytes-avail] might block). @ResultItself{output-port}.}
@item{@scheme[_progress] --- an event produced by @item{@racket[_progress] --- an event produced by
@scheme[port-progress-evt] applied to @scheme[_input-port] is ready after @racket[port-progress-evt] applied to @racket[_input-port] is ready after
any subsequent read from @scheme[_input-port]. @ResultItself{progress}.} any subsequent read from @racket[_input-port]. @ResultItself{progress}.}
@item{@scheme[_tcp-listener] --- a TCP listener is ready when @item{@racket[_tcp-listener] --- a TCP listener is ready when
@scheme[tcp-accept] would not block. @ResultItself{listener}.} @racket[tcp-accept] would not block. @ResultItself{listener}.}
@item{@scheme[_thd] --- a thread is ready when @scheme[thread-wait] @item{@racket[_thd] --- a thread is ready when @racket[thread-wait]
would not block. @ResultItself{thread}.} would not block. @ResultItself{thread}.}
@item{@scheme[_thread-dead] --- an event returned by @item{@racket[_thread-dead] --- an event returned by
@scheme[thread-dead-evt] applied to @scheme[thd] is ready when @racket[thread-dead-evt] applied to @racket[thd] is ready when
@scheme[thd] has terminated. @ResultItself{thread-dead}.} @racket[thd] has terminated. @ResultItself{thread-dead}.}
@item{@scheme[_thread-resume] --- an event returned by @item{@racket[_thread-resume] --- an event returned by
@scheme[thread-resume-evt] applied to @scheme[thd] is ready when @racket[thread-resume-evt] applied to @racket[thd] is ready when
@scheme[thd] subsequently resumes execution (if it was not already @racket[thd] subsequently resumes execution (if it was not already
running). The event's result is @scheme[thd].} running). The event's result is @racket[thd].}
@item{@scheme[_thread-suspend] --- an event returned by @item{@racket[_thread-suspend] --- an event returned by
@scheme[thread-suspend-evt] applied to @scheme[thd] is ready when @racket[thread-suspend-evt] applied to @racket[thd] is ready when
@scheme[thd] subsequently suspends execution (if it was not already @racket[thd] subsequently suspends execution (if it was not already
suspended). The event's result is @scheme[thd].} suspended). The event's result is @racket[thd].}
@item{@scheme[_alarm] --- an event returned by @scheme[alarm-evt] is @item{@racket[_alarm] --- an event returned by @racket[alarm-evt] is
ready after a particular date and time. @ResultItself{alarm}.} ready after a particular date and time. @ResultItself{alarm}.}
@item{@scheme[_subprocess] --- a subprocess is ready when @item{@racket[_subprocess] --- a subprocess is ready when
@scheme[subprocess-wait] would not block. @racket[subprocess-wait] would not block.
@ResultItself{subprocess}.} @ResultItself{subprocess}.}
@item{@scheme[_will-executor] --- a will executor is ready when @item{@racket[_will-executor] --- a will executor is ready when
@scheme[will-execute] would not block. @racket[will-execute] would not block.
@ResultItself{will-executor}.} @ResultItself{will-executor}.}
@item{@scheme[_udp] --- an event returned by @scheme[udp-send-evt] or @item{@racket[_udp] --- an event returned by @racket[udp-send-evt] or
@scheme[udp-receive!-evt] is ready when a send or receive on the @racket[udp-receive!-evt] is ready when a send or receive on the
original socket would block, respectively. @ResultItself{udp}.} original socket would block, respectively. @ResultItself{udp}.}
@item{@scheme[_log-receiver] --- a @tech{log receiver} as produced by @item{@racket[_log-receiver] --- a @tech{log receiver} as produced by
@scheme[make-log-receiver] is ready when a logged message is @racket[make-log-receiver] is ready when a logged message is
available. The event's result is a vector, as described with available. The event's result is a vector, as described with
@scheme[make-log-receiver].} @racket[make-log-receiver].}
@item{@scheme[_choice] --- an event returned by @scheme[choice-evt] is @item{@racket[_choice] --- an event returned by @racket[choice-evt] is
ready when one or more of the @scheme[_evt]s supplied to ready when one or more of the @racket[_evt]s supplied to
@scheme[choice-evt] are ready. If the choice event is chosen, one of @racket[choice-evt] are ready. If the choice event is chosen, one of
its ready @scheme[_evt]s is chosen pseudo-randomly, and the result is its ready @racket[_evt]s is chosen pseudo-randomly, and the result is
the chosen @scheme[_evt]'s result.} the chosen @racket[_evt]'s result.}
@item{@scheme[_wrap] --- an event returned by @scheme[wrap-evt] @item{@racket[_wrap] --- an event returned by @racket[wrap-evt]
applied to @scheme[_evt] and @scheme[_proc] is ready when @scheme[_evt] is applied to @racket[_evt] and @racket[_proc] is ready when @racket[_evt] is
ready. The event's result is obtained by a call to @scheme[_proc] (with ready. The event's result is obtained by a call to @racket[_proc] (with
breaks disabled) on the result of @scheme[evt].} breaks disabled) on the result of @racket[evt].}
@item{@scheme[_handle] --- an event returned by @scheme[handle-evt] @item{@racket[_handle] --- an event returned by @racket[handle-evt]
applied to @scheme[_evt] and @scheme[_proc] is ready when @scheme[_evt] is applied to @racket[_evt] and @racket[_proc] is ready when @racket[_evt] is
ready. The event's result is obtained by a tail call to @scheme[_proc] on ready. The event's result is obtained by a tail call to @racket[_proc] on
the result of @scheme[_evt].} the result of @racket[_evt].}
@item{@elemtag["guard-evt"]{@scheme[_guard]} --- an event returned by @scheme[guard-evt] applied @item{@elemtag["guard-evt"]{@racket[_guard]} --- an event returned by @racket[guard-evt] applied
to @scheme[_thunk] generates a new event every time that @scheme[_guard] is to @racket[_thunk] generates a new event every time that @racket[_guard] is
used with @scheme[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 @scheme[sync], etc.); the generated event is the result of used with @racket[sync], etc.); the generated event is the result of
calling @scheme[_thunk] when the synchronization begins; if @scheme[_thunk] calling @racket[_thunk] when the synchronization begins; if @racket[_thunk]
returns a non-event, then @scheme[_thunk]'s result is replaced with an returns a non-event, then @racket[_thunk]'s result is replaced with an
event that is ready and whose result is @scheme[_guard].} event that is ready and whose result is @racket[_guard].}
@item{@elemtag["nack-guard-evt"]{@scheme[_nack-guard]} --- an event @item{@elemtag["nack-guard-evt"]{@racket[_nack-guard]} --- an event
returned by @scheme[nack-guard-evt] applied to @scheme[_proc] returned by @racket[nack-guard-evt] applied to @racket[_proc]
generates a new event every time that @scheme[_nack-guard] is used generates a new event every time that @racket[_nack-guard] is used
with @scheme[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 @scheme[sync], etc.); the generated event is the result of with @racket[sync], etc.); the generated event is the result of
calling @scheme[_proc] with a NACK (``negative acknowledgment'') event calling @racket[_proc] with a NACK (``negative acknowledgment'') event
when the synchronization begins; if @scheme[_proc] returns a when the synchronization begins; if @racket[_proc] returns a
non-event, then @scheme[_proc]'s result is replaced with an event that non-event, then @racket[_proc]'s result is replaced with an event that
is ready and whose result is @scheme[_nack-guard]. is ready and whose result is @racket[_nack-guard].
If the event from @scheme[_proc] is not ultimately chosen as the If the event from @racket[_proc] is not ultimately chosen as the
unblocked event, then the NACK event supplied to @scheme[_proc] unblocked event, then the NACK event supplied to @racket[_proc]
becomes ready with a @|void-const| value. This NACK event becomes ready becomes ready with a @|void-const| value. This NACK event becomes ready
when the event is abandoned because some other event is chosen, when the event is abandoned because some other event is chosen,
because the synchronizing thread is dead, or because control escaped because the synchronizing thread is dead, or because control escaped
from the call to @scheme[sync] (even if @scheme[_nack-guard]'s @scheme[_proc] from the call to @racket[sync] (even if @racket[_nack-guard]'s @racket[_proc]
has not yet returned a value). If the event returned by @scheme[_proc] is has not yet returned a value). If the event returned by @racket[_proc] is
chosen, then the NACK event never becomes ready.} chosen, then the NACK event never becomes ready.}
@item{@elemtag["poll-guard-evt"]{@scheme[_poll-guard]} --- an event @item{@elemtag["poll-guard-evt"]{@racket[_poll-guard]} --- an event
returned by @scheme[poll-guard-evt] applied to @scheme[_proc] returned by @racket[poll-guard-evt] applied to @racket[_proc]
generates a new event every time that @scheme[poll-guard] is used generates a new event every time that @racket[poll-guard] is used
with @scheme[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 @scheme[sync], etc.); the generated event is the result of with @racket[sync], etc.); the generated event is the result of
calling @scheme[_proc] with a boolean: @scheme[#t] if the event will calling @racket[_proc] with a boolean: @racket[#t] if the event will
be used for a poll, @scheme[#f] for a blocking synchronization. be used for a poll, @racket[#f] for a blocking synchronization.
If @scheme[#t] is supplied to @scheme[_proc], if breaks are disabled, if If @racket[#t] is supplied to @racket[_proc], if breaks are disabled, if
the polling thread is not terminated, and if polling the resulting the polling thread is not terminated, and if polling the resulting
event produces a result, the event will certainly be chosen for its event produces a result, the event will certainly be chosen for its
result.} result.}
@item{@scheme[_struct] --- a structure whose type has the @item{@racket[_struct] --- a structure whose type has the
@scheme[prop:evt] property identifies/generates an event through the @racket[prop:evt] property identifies/generates an event through the
property.} property.}
@item{@scheme[always-evt] --- a constant event that is always @item{@racket[always-evt] --- a constant event that is always
ready. @ResultItself{@scheme[always-evt]}.} ready. @ResultItself{@racket[always-evt]}.}
@item{@scheme[never-evt] --- a constant event that is never ready.} @item{@racket[never-evt] --- a constant event that is never ready.}
@item{@elemtag["system-idle-evt"]{@scheme[_idle]} --- an event @item{@elemtag["system-idle-evt"]{@racket[_idle]} --- an event
produced by @scheme[system-idle-evt] is ready when, if this event produced by @racket[system-idle-evt] is ready when, if this event
were replaced by @scheme[never-evt], no thread in the system would were replaced by @racket[never-evt], no thread in the system would
be available to run. In other words, all threads must be suspended be available to run. In other words, all threads must be suspended
or blocked on events with timeouts that have not yet expired. The or blocked on events with timeouts that have not yet expired. The
event's result is @|void-const|.} event's result is @|void-const|.}
@ -187,20 +187,20 @@ types can generate events (see @scheme[prop:evt]).
@defproc[(evt? [v any/c]) boolean?]{ @defproc[(evt? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] is a @tech{synchronizable event}, Returns @racket[#t] if @racket[v] is a @tech{synchronizable event},
@scheme[#f] otherwise.} @racket[#f] otherwise.}
@defproc[(sync [evt evt?] ...+) any]{ @defproc[(sync [evt evt?] ...+) any]{
Blocks as long as none of the @tech{synchronizable events} Blocks as long as none of the @tech{synchronizable events}
@scheme[evt]s are ready, as defined above. @racket[evt]s are ready, as defined above.
When at least one @scheme[evt] is ready, its @tech{synchronization When at least one @racket[evt] is ready, its @tech{synchronization
result} (often @scheme[evt] itself) is returned. If multiple result} (often @racket[evt] itself) is returned. If multiple
@scheme[evt]s are ready, one of the @scheme[evt]s is chosen @racket[evt]s are ready, one of the @racket[evt]s is chosen
pseudo-randomly for the result; the pseudo-randomly for the result; the
@scheme[current-evt-pseudo-random-generator] parameter sets the @racket[current-evt-pseudo-random-generator] parameter sets the
random-number generator that controls this choice.} random-number generator that controls this choice.}
@ -208,23 +208,23 @@ random-number generator that controls this choice.}
[evt evt?] ...+) [evt evt?] ...+)
any]{ any]{
Like @scheme[sync], but returns @scheme[#f] if @scheme[timeout-secs] Like @racket[sync], but returns @racket[#f] if @racket[timeout-secs]
is not @scheme[#f] and if @scheme[timeout-secs] seconds pass without a is not @racket[#f] and if @racket[timeout-secs] seconds pass without a
successful synchronization. successful synchronization.
If @scheme[timeout-secs] is @scheme[0], each @scheme[evt] is checked If @racket[timeout-secs] is @racket[0], each @racket[evt] is checked
at least once, so a @scheme[timeout-secs] value of @scheme[0] can be at least once, so a @racket[timeout-secs] value of @racket[0] can be
used for polling. used for polling.
See also @scheme[alarm-evt] for an alternative timeout mechanism.} See also @racket[alarm-evt] for an alternative timeout mechanism.}
@defproc[(sync/enable-break [evt evt?] ...+) any]{ @defproc[(sync/enable-break [evt evt?] ...+) any]{
Like @scheme[sync], but breaking is enabled (see Like @racket[sync], but breaking is enabled (see
@secref["breakhandler"]) while waiting on the @scheme[evt]s. If @secref["breakhandler"]) while waiting on the @racket[evt]s. If
breaking is disabled when @scheme[sync/enable-break] is called, then breaking is disabled when @racket[sync/enable-break] is called, then
either all @scheme[evt]s remain unchosen or the @scheme[exn:break] either all @racket[evt]s remain unchosen or the @racket[exn:break]
exception is raised, but not both.} exception is raised, but not both.}
@ -232,34 +232,34 @@ exception is raised, but not both.}
[evt evt?] ...+) [evt evt?] ...+)
any]{ any]{
Like @scheme[sync/enable-break], but with a timeout in seconds (or Like @racket[sync/enable-break], but with a timeout in seconds (or
@scheme[#f]), as for @scheme[sync/timeout].} @racket[#f]), as for @racket[sync/timeout].}
@defproc[(choice-evt [evt evt?] ...) evt?]{ @defproc[(choice-evt [evt evt?] ...) evt?]{
Creates and returns a single event that combines the Creates and returns a single event that combines the
@scheme[evt]s. Supplying the result to @scheme[sync] is the same as @racket[evt]s. Supplying the result to @racket[sync] is the same as
supplying each @scheme[evt] to the same call.} supplying each @racket[evt] to the same call.}
@defproc[(wrap-evt [evt (and/c evt? (not/c handle-evt?))] @defproc[(wrap-evt [evt (and/c evt? (not/c handle-evt?))]
[wrap (any/c . -> . any)]) [wrap (any/c . -> . any)])
evt?]{ evt?]{
Creates an event that is in a ready when @scheme[evt] is ready, but Creates an event that is in a ready when @racket[evt] is ready, but
whose result is determined by applying @scheme[wrap] to the result of whose result is determined by applying @racket[wrap] to the result of
@scheme[evt]. The call to @scheme[wrap] is @racket[evt]. The call to @racket[wrap] is
@scheme[parameterize-break]ed to disable breaks initially. The @racket[parameterize-break]ed to disable breaks initially. The
@scheme[evt] cannot be an event created by @scheme[handle-evt] or any @racket[evt] cannot be an event created by @racket[handle-evt] or any
combination of @scheme[choice-evt] involving an event from combination of @racket[choice-evt] involving an event from
@scheme[handle-evt].} @racket[handle-evt].}
@defproc[(handle-evt [evt (and/c evt? (not/c handle-evt?))] @defproc[(handle-evt [evt (and/c evt? (not/c handle-evt?))]
[handle (any/c . -> . any)]) [handle (any/c . -> . any)])
evt?]{ evt?]{
Like @scheme[wrap], except that @scheme[handle] is called in tail Like @racket[wrap], except that @racket[handle] is called in 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.}
@ -293,27 +293,27 @@ itself as its result.}
@defproc[(system-idle-evt) evt?]{Returns an event that is ready when @defproc[(system-idle-evt) evt?]{Returns an event that is ready when
the system is otherwise idle; see @elemref["system-idle-evt"]{the the system is otherwise idle; see @elemref["system-idle-evt"]{the
overview} for more information. The result of the overview} for more information. The result of the
@scheme[system-idle-evt] procedure is always the same event.} @racket[system-idle-evt] procedure is always the same event.}
@defproc[(alarm-evt [msecs nonnegative-number?]) evt]{ @defproc[(alarm-evt [msecs nonnegative-number?]) evt]{
Returns a synchronizable event that is not ready when Returns a synchronizable event that is not ready when
@scheme[(current-inexact-milliseconds)] would return a value that is @racket[(current-inexact-milliseconds)] would return a value that is
less than @scheme[msecs], and it is ready when less than @racket[msecs], and it is ready when
@scheme[(current-inexact-milliseconds)] would return a value that is @racket[(current-inexact-milliseconds)] would return a value that is
more than @scheme[msecs].} more than @racket[msecs].}
@defproc[(handle-evt? [evt evt?]) boolean?]{ @defproc[(handle-evt? [evt evt?]) boolean?]{
Returns @scheme[#t] if @scheme[evt] was created by @scheme[handle-evt] Returns @racket[#t] if @racket[evt] was created by @racket[handle-evt]
or by @scheme[choice-evt] applied to another event for which or by @racket[choice-evt] applied to another event for which
@scheme[handle-evt?] produces @scheme[#t]. Such events are illegal as @racket[handle-evt?] produces @racket[#t]. Such events are illegal as
an argument to @scheme[handle-evt] or @scheme[wrap-evt], because they an argument to @racket[handle-evt] or @racket[wrap-evt], because they
cannot be wrapped further. For any other event, @scheme[handle-evt?] cannot be wrapped further. For any other event, @racket[handle-evt?]
produces @scheme[#f], and the event is a legal argument to produces @racket[#f], and the event is a legal argument to
@scheme[handle-evt] or @scheme[wrap-evt] for further wrapping.} @racket[handle-evt] or @racket[wrap-evt] for further wrapping.}
@;------------------------------------------------------------------------ @;------------------------------------------------------------------------
@defthing[prop:evt struct-type-property?]{ @defthing[prop:evt struct-type-property?]{
@ -324,16 +324,16 @@ A @tech{structure type property} that identifies structure types whose
@itemize[ @itemize[
@item{An event @scheme[_evt]: In this case, using the structure as an @item{An event @racket[_evt]: In this case, using the structure as an
event is equivalent to using @scheme[_evt].} event is equivalent to using @racket[_evt].}
@item{A procedure @scheme[_proc] of one argument: In this case, the @item{A procedure @racket[_proc] of one argument: In this case, the
structure is similar to an event generated structure is similar to an event generated
by @scheme[guard-evt], except that the would-be guard by @racket[guard-evt], except that the would-be guard
procedure @scheme[_proc] receives the structure as an argument, instead procedure @racket[_proc] receives the structure as an argument, instead
of no arguments.} of no arguments.}
@item{An exact, non-negative integer between @scheme[0] (inclusive) @item{An exact, non-negative integer between @racket[0] (inclusive)
and the number of non-automatic fields in the structure type and the number of non-automatic fields in the structure type
(exclusive, not counting supertype fields): The integer identifies a (exclusive, not counting supertype fields): The integer identifies a
field in the structure, and the field must be designated as field in the structure, and the field must be designated as
@ -344,14 +344,14 @@ A @tech{structure type property} that identifies structure types whose
] ]
Instances of a structure type with the @scheme[prop:input-port] or Instances of a structure type with the @racket[prop:input-port] or
@scheme[prop:output-port] property are also synchronizable by virtue @racket[prop:output-port] property are also synchronizable by virtue
of being a port. If the structure type has more than one of of being a port. If the structure type has more than one of
@scheme[prop:evt], @scheme[prop:input-port], and @racket[prop:evt], @racket[prop:input-port], and
@scheme[prop:output-port], then the @scheme[prop:evt] value (if any) @racket[prop:output-port], then the @racket[prop:evt] value (if any)
takes precedence for determing the instance's behavior as an event, takes precedence for determing the instance's behavior as an event,
and the @scheme[prop:input-port] property takes precedence over and the @racket[prop:input-port] property takes precedence over
@scheme[prop:output-port] for synchronization. @racket[prop:output-port] for synchronization.
@examples[ @examples[
(define-struct wt (base val) (define-struct wt (base val)
@ -376,4 +376,4 @@ and the @scheme[prop:input-port] property takes precedence over
@defparam[current-evt-pseudo-random-generator generator pseudo-random-generator?]{ @defparam[current-evt-pseudo-random-generator generator pseudo-random-generator?]{
A parameter that determines the pseudo-random number generator used by A parameter that determines the pseudo-random number generator used by
@scheme[sync] for events created by @scheme[choice-evt].} @racket[sync] for events created by @racket[choice-evt].}

12
collects/scribblings/reference/exit.scrbl
View File

@ -5,7 +5,7 @@
@defproc[(exit [v any/c #t]) any]{ @defproc[(exit [v any/c #t]) any]{
Passes @scheme[v] to the current @tech{exit handler}. If the exit Passes @racket[v] to the current @tech{exit handler}. If the exit
handler does not escape or terminate the thread, @|void-const| is handler does not escape or terminate the thread, @|void-const| is
returned.} returned.}
@ -13,11 +13,11 @@ returned.}
@defparam[exit-handler proc (any/c . -> . any)]{ @defparam[exit-handler proc (any/c . -> . any)]{
A parameter that determines the current @deftech{exit handler}. The A parameter that determines the current @deftech{exit handler}. The
@tech{exit handler} is called by @scheme[exit]. @tech{exit handler} is called by @racket[exit].
The default @tech{exit handler} in the @exec{mzscheme} executable The default @tech{exit handler} in the Racket executable
takes any argument and shuts down the OS-level Scheme process. The takes any argument and shuts down the OS-level Racket process. The
argument is used as the OS-level exit code if it is an exact integer argument is used as the OS-level exit code if it is an exact integer
between @scheme[1] and @scheme[255] (which normally means between @racket[1] and @racket[255] (which normally means
``failure''); otherwise, the exit code is @scheme[0], (which normally ``failure''); otherwise, the exit code is @racket[0], (which normally
means ``success'').} means ``success'').}

336
collects/scribblings/reference/exns.scrbl
View File

@ -5,42 +5,42 @@
@title[#:tag "exns"]{Exceptions} @title[#:tag "exns"]{Exceptions}
See @secref["exn-model"] for information on the PLT Scheme exception See @secref["exn-model"] for information on the Racket exception
model. It is based on a proposal by Friedman, Haynes, and Dybvig model. It is based on a proposal by Friedman, Haynes, and Dybvig
@cite["Friedman95"]. @cite["Friedman95"].
Whenever a primitive error occurs in PLT Scheme, an exception is Whenever a primitive error occurs in Racket, an exception is
raised. The value that is passed to the current @tech{exception raised. The value that is passed to the current @tech{exception
handler} for a primitive error is always an instance of the handler} for a primitive error is always an instance of the
@scheme[exn] structure type. Every @scheme[exn] structure value has a @racket[exn] structure type. Every @racket[exn] structure value has a
@scheme[message] field that is a string, the primitive error message. @racket[message] field that is a string, the primitive error message.
The default exception handler recognizes exception values with the The default exception handler recognizes exception values with the
@scheme[exn?] predicate and passes the error message to the current @racket[exn?] predicate and passes the error message to the current
@tech{error display handler} (see @scheme[error-display-handler]). @tech{error display handler} (see @racket[error-display-handler]).
Primitive procedures that accept a procedure argument with a Primitive procedures that accept a procedure argument with a
particular required arity (e.g., @scheme[call-with-input-file], particular required arity (e.g., @racket[call-with-input-file],
@scheme[call/cc]) check the argument's arity immediately, raising @racket[call/cc]) check the argument's arity immediately, raising
@scheme[exn:fail:contract] if the arity is incorrect. @racket[exn:fail:contract] if the arity is incorrect.
@;------------------------------------------------------------------------ @;------------------------------------------------------------------------
@section[#:tag "errorproc"]{Raising Exceptions} @section[#:tag "errorproc"]{Raising Exceptions}
@defproc[(raise [v any/c][barrier? any/c #t]) any]{ @defproc[(raise [v any/c][barrier? any/c #t]) any]{
Raises an exception, where @scheme[v] represents the exception being Raises an exception, where @racket[v] represents the exception being
raised. The @scheme[v] argument can be anything; it is passed to the raised. The @racket[v] argument can be anything; it is passed to the
current @tech{exception handler}. current @tech{exception handler}.
If @scheme[barrier?] is true, then the call to the @tech{exception If @racket[barrier?] is true, then the call to the @tech{exception
handler} is protected by a @tech{continuation barrier}, so that handler} is protected by a @tech{continuation barrier}, so that
multiple returns/escapes are impossible. All exceptions raised by multiple returns/escapes are impossible. All exceptions raised by
@schememodname[scheme] functions effectively use @scheme[raise] with a @racketmodname[racket] functions effectively use @racket[raise] with a
@scheme[#t] value for @scheme[barrier?]. @racket[#t] value for @racket[barrier?].
Breaks are disabled from the time the exception is raised until the Breaks are disabled from the time the exception is raised until the
exception handler obtains control, and the handler itself is exception handler obtains control, and the handler itself is
@scheme[parameterize-break]ed to disable breaks initially; see @racket[parameterize-break]ed to disable breaks initially; see
@secref["breakhandler"] for more information on breaks. @secref["breakhandler"] for more information on breaks.
@examples[ @examples[
@ -60,73 +60,73 @@ exception handler obtains control, and the handler itself is
[(error [msg string?][v any/c] ...) any] [(error [msg string?][v any/c] ...) any]
[(error [src symbol?][frmat string?][v any/c] ...) any])]{ [(error [src symbol?][frmat string?][v any/c] ...) any])]{
Raises the exception @scheme[exn:fail], which contains an error Raises the exception @racket[exn:fail], which contains an error
string. The different forms produce the error string in different string. The different forms produce the error string in different
ways: ways:
@itemize[ @itemize[
@item{@scheme[(error sym)] creates a message string by concatenating @item{@racket[(error sym)] creates a message string by concatenating
@scheme["error: "] with the string form of @scheme[sym].} @racket["error: "] with the string form of @racket[sym].}
@item{@scheme[(error msg v ...)] creates a message string by @item{@racket[(error msg v ...)] creates a message string by
concatenating @scheme[msg] with string versions of the @scheme[v]s concatenating @racket[msg] with string versions of the @racket[v]s
(as produced by the current error value conversion handler; see (as produced by the current error value conversion handler; see
@scheme[error-value->string-handler]). A space is inserted before @racket[error-value->string-handler]). A space is inserted before
each @scheme[v].} each @racket[v].}
@item{@scheme[(error src frmat v ...)] creates a @item{@racket[(error src frmat v ...)] creates a
message string equivalent to the string created by message string equivalent to the string created by
@schemeblock[ @racketblock[
(format (string-append "~s: " frmat) src v ...) (format (string-append "~s: " frmat) src v ...)
]} ]}
] ]
In all cases, the constructed message string is passed to In all cases, the constructed message string is passed to
@scheme[make-exn:fail], and the resulting exception is raised. @racket[make-exn:fail], and the resulting exception is raised.
@examples[ @examples[
(error 'failed) (error 'failed)
(error "failed" 23 'pizza (list 1 2 3)) (error "failed" 23 'pizza (list 1 2 3))
(error 'failed "~a failed because ~a" 'method-a "no argument supplied") (error 'method-a "failed because ~a" "no argument supplied")
]} ]}
@defproc*[([(raise-user-error [sym symbol?]) any] @defproc*[([(raise-user-error [sym symbol?]) any]
[(raise-user-error [msg string?][v any/c] ...) any] [(raise-user-error [msg string?][v any/c] ...) any]
[(raise-user-error [src symbol?][format string?][v any/c] ...) any])]{ [(raise-user-error [src symbol?][format string?][v any/c] ...) any])]{
Like @scheme[error], but constructs an exception with Like @racket[error], but constructs an exception with
@scheme[make-exn:fail:user] instead of @scheme[make-exn:fail]. The @racket[make-exn:fail:user] instead of @racket[make-exn:fail]. The
default @tech{error display handler} does not show a ``stack trace'' for default @tech{error display handler} does not show a ``stack trace'' for
@scheme[exn:fail:user] exceptions (see @secref["contmarks"]), so @racket[exn:fail:user] exceptions (see @secref["contmarks"]), so
@scheme[raise-user-error] should be used for errors that are intended @racket[raise-user-error] should be used for errors that are intended
for end users. for end users.
@examples[ @examples[
(raise-user-error 'failed) (raise-user-error 'failed)
(raise-user-error "failed" 23 'pizza (list 1 2 3)) (raise-user-error "failed" 23 'pizza (list 1 2 3))
(raise-user-error 'failed "~a failed because ~a" 'method-a "no argument supplied") (raise-user-error 'method-a "failed because ~a" "no argument supplied")
]} ]}
@defproc*[([(raise-type-error [name symbol?][expected string?][v any/c]) any] @defproc*[([(raise-type-error [name symbol?][expected string?][v any/c]) any]
[(raise-type-error [name symbol?][expected string?][bad-pos exact-nonnegative-integer?][v any/c] ...) any])]{ [(raise-type-error [name symbol?][expected string?][bad-pos exact-nonnegative-integer?][v any/c] ...) any])]{
Creates an @scheme[exn:fail:contract] value and @scheme[raise]s it as Creates an @racket[exn:fail:contract] value and @racket[raise]s it as
an exception. The @scheme[name] argument is used as the source an exception. The @racket[name] argument is used as the source
procedure's name in the error message. The @scheme[expected] argument procedure's name in the error message. The @racket[expected] argument
is used as a description of the expected type. is used as a description of the expected type.
In the first form, @scheme[v] is the value received by the procedure In the first form, @racket[v] is the value received by the procedure
that does not have the expected type. that does not have the expected type.
In the second form, the bad argument is indicated by an index In the second form, the bad argument is indicated by an index
@scheme[bad-pos] (counting from @math{0}), and all of the original @racket[bad-pos] (counting from @math{0}), and all of the original
arguments @scheme[v] are provided (in order). The resulting error arguments @racket[v] are provided (in order). The resulting error
message names the bad argument and also lists the other arguments. If message names the bad argument and also lists the other arguments. If
@scheme[bad-pos] is not less than the number of @scheme[v]s, the @racket[bad-pos] is not less than the number of @racket[v]s, the
@exnraise[exn:fail:contract]. @exnraise[exn:fail:contract].
@examples[ @examples[
@ -144,13 +144,13 @@ message names the bad argument and also lists the other arguments. If
@defproc[(raise-mismatch-error [name symbol?][message string?][v any/c]) any]{ @defproc[(raise-mismatch-error [name symbol?][message string?][v any/c]) any]{
Creates an @scheme[exn:fail:contract] value and @scheme[raise]s it as Creates an @racket[exn:fail:contract] value and @racket[raise]s it as
an exception. The @scheme[name] is used as the source procedure's an exception. The @racket[name] is used as the source procedure's
name in the error message. The @scheme[message] is the error name in the error message. The @racket[message] is the error
message. The @scheme[v] argument is the improper argument received by message. The @racket[v] argument is the improper argument received by
the procedure. The printed form of @scheme[v] is appended to the procedure. The printed form of @racket[v] is appended to
@scheme[message] (using the error value conversion handler; see @racket[message] (using the error value conversion handler; see
@scheme[error-value->string-handler]).} @racket[error-value->string-handler]).}
@defproc[(raise-arity-error [name (or/c symbol? procedure?)] @defproc[(raise-arity-error [name (or/c symbol? procedure?)]
[arity-v (or/c exact-nonnegative-integer? [arity-v (or/c exact-nonnegative-integer?
@ -161,22 +161,22 @@ the procedure. The printed form of @scheme[v] is appended to
[arg-v any/c #f] ...) [arg-v any/c #f] ...)
any]{ any]{
Creates an @scheme[exn:fail:contract:arity] value and @scheme[raise]s Creates an @racket[exn:fail:contract:arity] value and @racket[raise]s
it as an exception. The @scheme[name] is used for the source it as an exception. The @racket[name] is used for the source
procedure's name in the error message. procedure's name in the error message.
The @scheme[arity-v] value must The @racket[arity-v] value must
be a possible result from @scheme[procedure-arity], except be a possible result from @racket[procedure-arity], except
that it does not have to be normalized (see @scheme[procedure-arity?] for that it does not have to be normalized (see @racket[procedure-arity?] for
the details of normalized arities); @scheme[raise-arity-error] the details of normalized arities); @racket[raise-arity-error]
will normalize the arity and used the normalized form in the error message. will normalize the arity and used the normalized form in the error message.
If @scheme[name-symbol-or-procedure] is a procedure, its actual arity is If @racket[name-symbol-or-procedure] is a procedure, its actual arity is
ignored. ignored.
The @scheme[arg-v] arguments are the actual supplied The @racket[arg-v] arguments are the actual supplied
arguments, which are shown in the error message (using the error value arguments, which are shown in the error message (using the error value
conversion handler; see @scheme[error-value->string-handler]); also, conversion handler; see @racket[error-value->string-handler]); also,
the number of supplied @scheme[arg-v]s is explicitly mentioned in the the number of supplied @racket[arg-v]s is explicitly mentioned in the
message.} message.}
@defproc[(raise-syntax-error [name (or/c symbol? #f)] @defproc[(raise-syntax-error [name (or/c symbol? #f)]
@ -186,50 +186,50 @@ message.}
[extra-sources (listof syntax?) null]) [extra-sources (listof syntax?) null])
any]{ any]{
Creates an @scheme[exn:fail:syntax] value and @scheme[raise]s it as an Creates an @racket[exn:fail:syntax] value and @racket[raise]s it as an
exception. Macros use this procedure to report syntax errors. exception. Macros use this procedure to report syntax errors.
The @scheme[name] argument is usually @scheme[#f] when @scheme[expr] The @racket[name] argument is usually @racket[#f] when @racket[expr]
is provided; it is described in more detail below. The is provided; it is described in more detail below. The
@scheme[message] is used as the main body of the error message. @racket[message] is used as the main body of the error message.
The optional @scheme[expr] argument is the erroneous source syntax The optional @racket[expr] argument is the erroneous source syntax
object or S-expression (but the expression @scheme[#f] cannot be object or S-expression (but the expression @racket[#f] cannot be
represented by itself; it must be wrapped as a @tech{syntax represented by itself; it must be wrapped as a @tech{syntax
object}). The optional @scheme[sub-expr] argument is a syntax object object}). The optional @racket[sub-expr] argument is a syntax object
or S-expression (again, @scheme[#f] cannot represent itself) within or S-expression (again, @racket[#f] cannot represent itself) within
@scheme[expr] that more precisely locates the error. Both may appear @racket[expr] that more precisely locates the error. Both may appear
in the generated error-message text if in the generated error-message text if
@scheme[error-print-source-location] is @scheme[#t]. Source location @racket[error-print-source-location] is @racket[#t]. Source location
information in the error-message text is similarly extracted from information in the error-message text is similarly extracted from
@scheme[sub-expr] or @scheme[expr] when at least one is a syntax @racket[sub-expr] or @racket[expr] when at least one is a syntax
object and @scheme[error-print-source-location] is @scheme[#t]. object and @racket[error-print-source-location] is @racket[#t].
If @scheme[sub-expr] is provided and not @scheme[#f], it is used (in If @racket[sub-expr] is provided and not @racket[#f], it is used (in
syntax form) for the @scheme[exprs] field of the generated exception syntax form) for the @racket[exprs] field of the generated exception
record, else the @scheme[expr] is used if provided and not record, else the @racket[expr] is used if provided and not
@scheme[#f]. In either case, the syntax object is @scheme[cons]ed onto @racket[#f]. In either case, the syntax object is @racket[cons]ed onto
@scheme[extra-sources] to produce the @scheme[exprs] field, or @racket[extra-sources] to produce the @racket[exprs] field, or
@scheme[extra-sources] is used directly for @scheme[exprs] if neither @racket[extra-sources] is used directly for @racket[exprs] if neither
@scheme[expr] nor @scheme[sub-expr] is provided and not @scheme[#f]. @racket[expr] nor @racket[sub-expr] is provided and not @racket[#f].
The form name used in the generated error message is determined The form name used in the generated error message is determined
through a combination of the @scheme[name], @scheme[expr], and through a combination of the @racket[name], @racket[expr], and
@scheme[sub-expr] arguments: @racket[sub-expr] arguments:
@itemize[ @itemize[
@item{When @scheme[name] is @scheme[#f], and when @scheme[expr] is @item{When @racket[name] is @racket[#f], and when @racket[expr] is
either an identifier or a syntax pair containing an identifier as either an identifier or a syntax pair containing an identifier as
its first element, then the form name from the error message is the its first element, then the form name from the error message is the
identifier's symbol.} identifier's symbol.}
@item{When @scheme[name] is @scheme[#f] and when @scheme[expr] is not @item{When @racket[name] is @racket[#f] and when @racket[expr] is not
an identifier or a syntax pair containing and identifier as its an identifier or a syntax pair containing and identifier as its
first element, then the form name in the error message is first element, then the form name in the error message is
@scheme["?"].} @racket["?"].}
@item{@scheme[symbol]: When @scheme[name] is a symbol, then the symbol @item{@racket[symbol]: When @racket[name] is a symbol, then the symbol
is used as the form name in the generated error message.} is used as the form name in the generated error message.}
]} ]}
@ -239,48 +239,48 @@ through a combination of the @scheme[name], @scheme[expr], and
@defproc[(call-with-exception-handler [f (any/c . -> . any)][thunk (-> any)]) any]{ @defproc[(call-with-exception-handler [f (any/c . -> . any)][thunk (-> any)]) any]{
Installs @scheme[f] as the @tech{exception handler} for the Installs @racket[f] as the @tech{exception handler} for the
@tech{dynamic extent} of the call to @scheme[thunk]. If an exception @tech{dynamic extent} of the call to @racket[thunk]. If an exception
is raised during the evaluation of @scheme[thunk] (in an extension of is raised during the evaluation of @racket[thunk] (in an extension of
the current continuation that does not have its own exception the current continuation that does not have its own exception
handler), then @scheme[f] is applied to the @scheme[raise]d value in handler), then @racket[f] is applied to the @racket[raise]d value in
the continuation of the @scheme[raise] call (but normally extended the continuation of the @racket[raise] call (but normally extended
with a @tech{continuation barrier}; see @secref["prompt-model"] and with a @tech{continuation barrier}; see @secref["prompt-model"] and
@scheme[raise]). @racket[raise]).
Any procedure that takes one argument can be an exception handler. If Any procedure that takes one argument can be an exception handler. If
the exception handler returns a value when invoked by @scheme[raise], the exception handler returns a value when invoked by @racket[raise],
then @scheme[raise] propagates the value to the ``previous'' exception then @racket[raise] propagates the value to the ``previous'' exception
handler (still in the dynamic extent of the call to @scheme[raise], handler (still in the dynamic extent of the call to @racket[raise],
and under the same barrier, if any). The previous exception handler is and under the same barrier, if any). The previous exception handler is
the exception handler associated with the rest of the continuation the exception handler associated with the rest of the continuation
after the point where the called exception handler was associated with after the point where the called exception handler was associated with
the continuation; if no previous handler is available, the the continuation; if no previous handler is available, the
uncaught-exception handler is used (see below). In all cases, a call uncaught-exception handler is used (see below). In all cases, a call
to an exception handler is @scheme[parameterize-break]ed to disable to an exception handler is @racket[parameterize-break]ed to disable
breaks, and it is wrapped with @scheme[call-with-exception-handler] to breaks, and it is wrapped with @racket[call-with-exception-handler] to
install the an exception handler that reports both the original and install the an exception handler that reports both the original and
newly raised exceptions.} newly raised exceptions.}
@defparam[uncaught-exception-handler f (any/c . -> . any)]{ @defparam[uncaught-exception-handler f (any/c . -> . any)]{
A @tech{parameter} that determines an exception handler used by A @tech{parameter} that determines an exception handler used by
@scheme[raise] when the relevant continuation has no exception handler @racket[raise] when the relevant continuation has no exception handler
installed with @scheme[call-with-exception-handler] or installed with @racket[call-with-exception-handler] or
@scheme[with-handlers]. Unlike exception handlers installed with @racket[with-handlers]. Unlike exception handlers installed with
@scheme[call-with-exception-handler], the handler for uncaught @racket[call-with-exception-handler], the handler for uncaught
exceptions must not return a value when called by @scheme[raise]; if exceptions must not return a value when called by @racket[raise]; if
it returns, an exception is raised (to be handled by an exception it returns, an exception is raised (to be handled by an exception
handler that reports both the original and newly raised exception). handler that reports both the original and newly raised exception).
The default uncaught-exception handler prints an error message using The default uncaught-exception handler prints an error message using
the current @tech{error display handler} (see @scheme[error-display-handler]) the current @tech{error display handler} (see @racket[error-display-handler])
and then escapes by calling the current error escape handler (see and then escapes by calling the current error escape handler (see
@scheme[error-escape-handler]). The call to each handler is @racket[error-escape-handler]). The call to each handler is
@scheme[parameterize]d to set @scheme[error-display-handler] to the @racket[parameterize]d to set @racket[error-display-handler] to the
default @tech{error display handler}, and it is @scheme[parameterize-break]ed default @tech{error display handler}, and it is @racket[parameterize-break]ed
to disable breaks. The call to the error escape handler is further to disable breaks. The call to the error escape handler is further
parameterized to set @scheme[error-escape-handler] to the default parameterized to set @racket[error-escape-handler] to the default
error escape handler. error escape handler.
When the current @tech{error display handler} is the default handler, then the When the current @tech{error display handler} is the default handler, then the
@ -291,35 +291,35 @@ fails.}
@defform[(with-handlers ([pred-expr handler-expr] ...) @defform[(with-handlers ([pred-expr handler-expr] ...)
body ...+)]{ body ...+)]{
Evaluates each @scheme[pred-expr] and and @scheme[handler-expr] in the Evaluates each @racket[pred-expr] and and @racket[handler-expr] in the
order that they are specified, and then evaluates the @scheme[body]s order that they are specified, and then evaluates the @racket[body]s
with a new exception handler during the its dynamic extent. with a new exception handler during the its dynamic extent.
The new exception handler processes an exception only if one of the The new exception handler processes an exception only if one of the
@scheme[pred-expr] procedures returns a true value when applied to the @racket[pred-expr] procedures returns a true value when applied to the
exception, otherwise the exception handler is invoked from the exception, otherwise the exception handler is invoked from the
continuation of the @scheme[with-handlers] expression (by raising the continuation of the @racket[with-handlers] expression (by raising the
exception again). If an exception is handled by one of the exception again). If an exception is handled by one of the
@scheme[handler-expr] procedures, the result of the entire @racket[handler-expr] procedures, the result of the entire
@scheme[with-handlers] expression is the return value of the handler. @racket[with-handlers] expression is the return value of the handler.
When an exception is raised during the evaluation of @scheme[body]s, When an exception is raised during the evaluation of @racket[body]s,
each predicate procedure @scheme[pred-expr] is applied to the each predicate procedure @racket[pred-expr] is applied to the
exception value; if a predicate returns a true value, the exception value; if a predicate returns a true value, the
corresponding @scheme[handler-expr] procedure is invoked with the corresponding @racket[handler-expr] procedure is invoked with the
exception as an argument. The predicates are tried in the order that exception as an argument. The predicates are tried in the order that
they are specified. they are specified.
Before any predicate or handler procedure is invoked, the continuation Before any predicate or handler procedure is invoked, the continuation
of the entire @scheme[with-handlers] expression is restored, but also of the entire @racket[with-handlers] expression is restored, but also
@scheme[parameterize-break]ed to disable breaks. Thus, breaks are @racket[parameterize-break]ed to disable breaks. Thus, breaks are
disabled by default during the predicate and handler procedures (see disabled by default during the predicate and handler procedures (see
@secref["breakhandler"]), and the exception handler is the one from @secref["breakhandler"]), and the exception handler is the one from
the continuation of the @scheme[with-handlers] expression. the continuation of the @racket[with-handlers] expression.
The @scheme[exn:fail?] procedure is useful as a handler predicate to The @racket[exn:fail?] procedure is useful as a handler predicate to
catch all error exceptions. Avoid using @scheme[(lambda (x) #t)] as a catch all error exceptions. Avoid using @racket[(lambda (x) #t)] as a
predicate, because the @scheme[exn:break] exception typically should predicate, because the @racket[exn:break] exception typically should
not be caught (unless it will be re-raised to cooperatively not be caught (unless it will be re-raised to cooperatively
break). Beware, also, of catching and discarding exceptions, because break). Beware, also, of catching and discarding exceptions, because
discarding an error message can make debugging unnecessarily discarding an error message can make debugging unnecessarily
@ -328,9 +328,9 @@ difficult.}
@defform[(with-handlers* ([pred-expr handler-expr] ...) @defform[(with-handlers* ([pred-expr handler-expr] ...)
body ...+)]{ body ...+)]{
Like @scheme[with-handlers], but if a @scheme[handler-expr] procedure Like @racket[with-handlers], but if a @racket[handler-expr] procedure
is called, breaks are not explicitly disabled, and the handler call is is called, breaks are not explicitly disabled, and the handler call is
in tail position with respect to the @scheme[with-handlers*] form.} in tail position with respect to the @racket[with-handlers*] form.}
@;------------------------------------------------------------------------ @;------------------------------------------------------------------------
@section{Configuring Default Handling} @section{Configuring Default Handling}
@ -340,21 +340,21 @@ in tail position with respect to the @scheme[with-handlers*] form.}
A parameter for the @deftech{error escape handler}, which takes no A parameter for the @deftech{error escape handler}, which takes no
arguments and escapes from the dynamic context of an exception. The arguments and escapes from the dynamic context of an exception. The
default error escape handler escapes using default error escape handler escapes using
@scheme[(abort-current-continuation (default-continuation-prompt-tag) @racket[(abort-current-continuation (default-continuation-prompt-tag)
void)]. void)].
The error escape handler is normally called directly by an exception The error escape handler is normally called directly by an exception
handler, in a @tech{parameterization} that sets the @tech{error handler, in a @tech{parameterization} that sets the @tech{error
display handler} and @tech{error escape handler} to the default display handler} and @tech{error escape handler} to the default
handlers, and it is normally @scheme[parameterize-break]ed to disable handlers, and it is normally @racket[parameterize-break]ed to disable
breaks. To escape from a run-time error in a different context, use breaks. To escape from a run-time error in a different context, use
@scheme[raise] or @scheme[error]. @racket[raise] or @racket[error].
Due to a @tech{continuation barrier} around exception-handling calls, Due to a @tech{continuation barrier} around exception-handling calls,
an error escape handler cannot invoke a full continuation that was an error escape handler cannot invoke a full continuation that was
created prior to the exception, but it can abort to a prompt (see created prior to the exception, but it can abort to a prompt (see
@scheme[call-with-continuation-prompt]) or invoke an escape @racket[call-with-continuation-prompt]) or invoke an escape
continuation (see @scheme[call-with-escape-continuation]).} continuation (see @racket[call-with-escape-continuation]).}
@defparam[error-display-handler proc (string? any/c . -> . any)]{ @defparam[error-display-handler proc (string? any/c . -> . any)]{
@ -364,24 +364,24 @@ exception value. More generally, the handler's first argument is a
string to print as an error message, and the second is a value string to print as an error message, and the second is a value
representing a raised exception. representing a raised exception.
The default error display handler @scheme[display]s its first argument The default error display handler @racket[display]s its first argument
to the current error port (determined by the to the current error port (determined by the
@scheme[current-error-port] parameter) and extracts a stack trace (see @racket[current-error-port] parameter) and extracts a stack trace (see
@scheme[continuation-mark-set->context]) to display from the second @racket[continuation-mark-set->context]) to display from the second
argument if it is an @scheme[exn] value but not an argument if it is an @racket[exn] value but not an
@scheme[exn:fail:user] value. @racket[exn:fail:user] value.
@margin-note{The default error display handler in DrScheme also uses @margin-note{The default error display handler in DrRacket also uses
the second argument to highlight source locations.} the second argument to highlight source locations.}
To report a run-time error, use @scheme[raise] or procedures like To report a run-time error, use @racket[raise] or procedures like
@scheme[error], instead of calling the error display handler @racket[error], instead of calling the error display handler
directly.} directly.}
@defparam[error-print-width width (and exact-integer? (>=/c 3))]{ @defparam[error-print-width width (and exact-integer? (>=/c 3))]{
A parameter whose value is used as the maximum number of characters A parameter whose value is used as the maximum number of characters
used to print a Scheme value that is embedded in a primitive error used to print a Racket value that is embedded in a primitive error
message.} message.}
@defparam[error-print-context-length cnt exact-nonnegative-integer?]{ @defparam[error-print-context-length cnt exact-nonnegative-integer?]{
@ -389,35 +389,35 @@ message.}
A parameter whose value is used by the default @tech{error display handler} A parameter whose value is used by the default @tech{error display handler}
as the maximum number of lines of context (or ``stack trace'') to as the maximum number of lines of context (or ``stack trace'') to
print; a single ``...'' line is printed if more lines are available print; a single ``...'' line is printed if more lines are available
after the first @scheme[cnt] lines. A @scheme[0] value for after the first @racket[cnt] lines. A @racket[0] value for
@scheme[cnt] disables context printing entirely.} @racket[cnt] disables context printing entirely.}
@defparam[error-value->string-handler proc (any/c exact-nonnegative-integer? @defparam[error-value->string-handler proc (any/c exact-nonnegative-integer?
. -> . . -> .
string?)]{ string?)]{
A parameter that determines the @deftech{error value conversion A parameter that determines the @deftech{error value conversion
handler}, which is used to print a Scheme value that is embedded in a handler}, which is used to print a Racket value that is embedded in a
primitive error message. primitive error message.
The integer argument to the handler specifies the maximum number of The integer argument to the handler specifies the maximum number of
characters that should be used to represent the value in the resulting characters that should be used to represent the value in the resulting
string. The default error value conversion handler @scheme[print]s string. The default error value conversion handler @racket[print]s
the value into a string (using the current @tech{global port print the value into a string (using the current @tech{global port print
handler}; see @scheme[global-port-print-handler]). If the printed form handler}; see @racket[global-port-print-handler]). If the printed form
is too long, the printed form is truncated and the last three is too long, the printed form is truncated and the last three
characters of the return string are set to ``...''. characters of the return string are set to ``...''.
If the string returned by an error value conversion handler is longer If the string returned by an error value conversion handler is longer
than requested, the string is destructively ``truncated'' by setting than requested, the string is destructively ``truncated'' by setting
the first extra position in the string to the null character. If a the first extra position in the string to the null character. If a
non-string is returned, then the string @scheme["..."] is used. If a non-string is returned, then the string @racket["..."] is used. If a
primitive error string needs to be generated before the handler has primitive error string needs to be generated before the handler has
returned, the default error value conversion handler is used. returned, the default error value conversion handler is used.
Call to an error value conversion handler are @scheme[parameterized] Call to an error value conversion handler are @racket[parameterized]
to re-install the default error value conversion handler, and to to re-install the default error value conversion handler, and to
enable printing of unreadable values (see @scheme[print-unreadable]).} enable printing of unreadable values (see @racket[print-unreadable]).}
@defboolparam[error-print-source-location include?]{ @defboolparam[error-print-source-location include?]{
@ -426,9 +426,9 @@ include source information, such as the source line and column or the
expression. This parameter also controls the error message when a expression. This parameter also controls the error message when a
module-defined variable is accessed before its definition is executed; module-defined variable is accessed before its definition is executed;
the parameter determines whether the message includes a module the parameter determines whether the message includes a module
name. Only the message field of an @scheme[exn:fail:read], name. Only the message field of an @racket[exn:fail:read],
@scheme[exn:fail:syntax], or @scheme[exn:fail:contract:variable] @racket[exn:fail:syntax], or @racket[exn:fail:contract:variable]
structure is affected by the parameter. The default is @scheme[#t].} structure is affected by the parameter. The default is @racket[#t].}
@;------------------------------------------------------------------------ @;------------------------------------------------------------------------
@section{Built-in Exception Types} @section{Built-in Exception Types}
@ -437,16 +437,16 @@ structure is affected by the parameter. The default is @scheme[#t].}
[continuation-marks continuation-mark-set?]) [continuation-marks continuation-mark-set?])
#:inspector #f]{ #:inspector #f]{
The base @tech{structure type} for exceptions. The @scheme[message] The base @tech{structure type} for exceptions. The @racket[message]
field contains an error message, and the @scheme[continuation-marks] field contains an error message, and the @racket[continuation-marks]
field contains the value produced by @scheme[(current-continuation-marks)] field contains the value produced by @racket[(current-continuation-marks)]
immediately before the exception was raised.} immediately before the exception was raised.}
@defstruct[(exn:fail exn) () @defstruct[(exn:fail exn) ()
#:inspector #f]{ #:inspector #f]{
Raised for exceptions that represent errors, as opposed to Raised for exceptions that represent errors, as opposed to
@scheme[exn:break].} @racket[exn:break].}
@defstruct[(exn:fail:contract exn:fail) () @defstruct[(exn:fail:contract exn:fail) ()
@ -468,7 +468,7 @@ Raised for division by exact zero.}
@defstruct[(exn:fail:contract:non-fixnum-result exn:fail:contract) () @defstruct[(exn:fail:contract:non-fixnum-result exn:fail:contract) ()
#:inspector #f]{ #:inspector #f]{
Raised by functions like @scheme[fx+] when the result would not be a fixnum.} Raised by functions like @racket[fx+] when the result would not be a fixnum.}
@defstruct[(exn:fail:contract:continuation exn:fail:contract) () @defstruct[(exn:fail:contract:continuation exn:fail:contract) ()
#:inspector #f]{ #:inspector #f]{
@ -485,27 +485,27 @@ or @tech{module-level variable}.}
@defstruct[(exn:fail:syntax exn:fail) ([exprs (listof syntax?)]) @defstruct[(exn:fail:syntax exn:fail) ([exprs (listof syntax?)])
#:inspector #f]{ #:inspector #f]{
Raised for a syntax error that is not a @scheme[read] error. The Raised for a syntax error that is not a @racket[read] error. The
@scheme[exprs] indicate the relevant source expressions, @racket[exprs] indicate the relevant source expressions,
least-specific to most-specific.} least-specific to most-specific.}
@defstruct[(exn:fail:read exn:fail) ([srclocs (listof srcloc?)]) @defstruct[(exn:fail:read exn:fail) ([srclocs (listof srcloc?)])
#:inspector #f]{ #:inspector #f]{
Raised for a @scheme[read] error. The @scheme[srclocs] indicate the Raised for a @racket[read] error. The @racket[srclocs] indicate the
relevant source expressions.} relevant source expressions.}
@defstruct[(exn:fail:read:eof exn:fail:read) () @defstruct[(exn:fail:read:eof exn:fail:read) ()
#:inspector #f]{ #:inspector #f]{
Raised for a @scheme[read] error, specifically when the error is due Raised for a @racket[read] error, specifically when the error is due
to an unexpected end-of-file.} to an unexpected end-of-file.}
@defstruct[(exn:fail:read:non-char exn:fail:read) () @defstruct[(exn:fail:read:non-char exn:fail:read) ()
#:inspector #f]{ #:inspector #f]{
Raised for a @scheme[read] error, specifically when the error is due Raised for a @racket[read] error, specifically when the error is due
to an unexpected non-character (i.e., ``special'') element in the to an unexpected non-character (i.e., ``special'') element in the
input stream.} input stream.}
@ -556,32 +556,32 @@ context when printing the error message.}
#:inspector #f]{ #:inspector #f]{
Raised asynchronously (when enabled) in response to a break request. Raised asynchronously (when enabled) in response to a break request.
The @scheme[continuation] field can be used by a handler to resume the The @racket[continuation] field can be used by a handler to resume the
interrupted computation.} interrupted computation.}
@defthing[prop:exn:srclocs struct-type-property?]{ @defthing[prop:exn:srclocs struct-type-property?]{
A property that identifies structure types that provide a list of A property that identifies structure types that provide a list of
@scheme[srcloc] values. The property is normally attached to structure @racket[srcloc] values. The property is normally attached to structure
types used to represent exception information. types used to represent exception information.
The property value must be a procedure that accepts a single The property value must be a procedure that accepts a single
value---the structure type instance from which to extract source value---the structure type instance from which to extract source
locations---and returns a list of @scheme[srcloc]s. Some @tech{error locations---and returns a list of @racket[srcloc]s. Some @tech{error
display handlers} use only the first returned location.} display handlers} use only the first returned location.}
@defproc[(exn:srclocs? [v any/c]) boolean?]{ @defproc[(exn:srclocs? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] has the @scheme[prop:exn:srclocs] Returns @racket[#t] if @racket[v] has the @racket[prop:exn:srclocs]
property, @scheme[#f] otherwise.} property, @racket[#f] otherwise.}
@defproc[(exn:srclocs-accessor [v exn:srclocs?]) @defproc[(exn:srclocs-accessor [v exn:srclocs?])
(exn:srclocs? . -> . (listof srcloc))]{ (exn:srclocs? . -> . (listof srcloc))]{
Returns the @scheme[srcloc]-getting procedure associated with @scheme[v].} Returns the @racket[srcloc]-getting procedure associated with @racket[v].}
@defstruct[srcloc ([source any/c] @defstruct[srcloc ([source any/c]
@ -591,23 +591,23 @@ Returns the @scheme[srcloc]-getting procedure associated with @scheme[v].}
[span (or/c exact-nonnegative-integer? #f)]) [span (or/c exact-nonnegative-integer? #f)])
#:inspector #f]{ #:inspector #f]{
The fields of an @scheme[srcloc] instance are as follows: The fields of an @racket[srcloc] instance are as follows:
@itemize[ @itemize[
@item{@scheme[source] --- An arbitrary value identifying the source, @item{@racket[source] --- An arbitrary value identifying the source,
often a path (see @secref["pathutils"]).} often a path (see @secref["pathutils"]).}
@item{@scheme[line] --- The line number (counts from 1) or @item{@racket[line] --- The line number (counts from 1) or
@scheme[#f] (unknown).} @racket[#f] (unknown).}
@item{@scheme[column] --- The column number (counts from 0) or @item{@racket[column] --- The column number (counts from 0) or
@scheme[#f] (unknown).} @racket[#f] (unknown).}
@item{@scheme[position] --- The starting position (counts from 1) or @item{@racket[position] --- The starting position (counts from 1) or
@scheme[#f] (unknown).} @racket[#f] (unknown).}
@item{@scheme[span] --- The number of covered positions (counts from @item{@racket[span] --- The number of covered positions (counts from
0) or @scheme[#f] (unknown).} 0) or @racket[#f] (unknown).}
]} ]}

130
collects/scribblings/reference/file-ports.scrbl
View File

@ -36,11 +36,11 @@
@title[#:tag "file-ports"]{File Ports} @title[#:tag "file-ports"]{File Ports}
A port created by @scheme[open-input-file], @scheme[open-output-file], A port created by @racket[open-input-file], @racket[open-output-file],
@scheme[subprocess], and related functions is a @deftech{file-stream @racket[subprocess], and related functions is a @deftech{file-stream
port}. The initial input, output, and error ports in stand-alone port}. The initial input, output, and error ports in @exec{racket}
MzScheme are also file-stream ports. The @scheme[file-stream-port?] are also file-stream ports. The @racket[file-stream-port?] predicate
predicate recognizes file-stream ports. recognizes file-stream ports.
When an input or output file-stream port is created, it is placed into When an input or output file-stream port is created, it is placed into
the management of the current custodian (see the management of the current custodian (see
@ -50,16 +50,16 @@ the management of the current custodian (see
[#:mode mode-flag (or/c 'binary 'text) 'binary]) [#:mode mode-flag (or/c 'binary 'text) 'binary])
input-port?]{ input-port?]{
Opens the file specified by @scheme[path] for input. The Opens the file specified by @racket[path] for input. The
@scheme[mode-flag] argument specifies how the file's bytes are @racket[mode-flag] argument specifies how the file's bytes are
translated on input: translated on input:
@itemize[ @itemize[
@item{@indexed-scheme['binary] --- bytes are returned from the port @item{@indexed-racket['binary] --- bytes are returned from the port
exactly as they are read from the file.} exactly as they are read from the file.}
@item{@indexed-scheme['text] --- return and linefeed bytes (10 and @item{@indexed-racket['text] --- return and linefeed bytes (10 and
13) as read from the file are filtered by the port in a platform 13) as read from the file are filtered by the port in a platform
specific manner: specific manner:
@ -74,25 +74,25 @@ translated on input:
]} ]}
] ]
Under Windows, @scheme['text] mode works only with regular files; Under Windows, @racket['text] mode works only with regular files;
attempting to use @scheme['text] with other kinds of files triggers an attempting to use @racket['text] with other kinds of files triggers an
@scheme[exn:fail:filesystem] exception. @racket[exn:fail:filesystem] exception.
Otherwise, the file specified by @scheme[path] need not be a regular Otherwise, the file specified by @racket[path] need not be a regular
file. It might a device that is connected through the filesystem, such file. It might a device that is connected through the filesystem, such
as @filepath{aux} under Windows or @filepath{/dev/null} under Unix. In all as @filepath{aux} under Windows or @filepath{/dev/null} under Unix. In all
cases, the port is buffered by default. cases, the port is buffered by default.
The port produced by @scheme[open-input-file] should be explicitly The port produced by @racket[open-input-file] should be explicitly
closed, either though @scheme[close-input-port] or indirectly via closed, either though @racket[close-input-port] or indirectly via
@scheme[custodian-shutdown-all], to release the OS-level file @racket[custodian-shutdown-all], to release the OS-level file
handle. The input port will not be closed automatically if it is handle. The input port will not be closed automatically if it is
otherwise available for garbage collection (see otherwise available for garbage collection (see
@secref["gc-model"]); a @tech{will} could be associated input port @secref["gc-model"]); a @tech{will} could be associated input port
to close it more automatically (see @secref["willexecutor"]). to close it more automatically (see @secref["willexecutor"]).
A @tech{path} value that is the @tech{cleanse}d version of A @tech{path} value that is the @tech{cleanse}d version of
@scheme[path] is used as the name of the opened port. @racket[path] is used as the name of the opened port.
@file-examples[ @file-examples[
;; put some text in a file ;; put some text in a file
@ -110,79 +110,79 @@ A @tech{path} value that is the @tech{cleanse}d version of
'must-truncate 'truncate/replace) 'error]) 'must-truncate 'truncate/replace) 'error])
output-port?]{ output-port?]{
Opens the file specified by @scheme[path] for output. The Opens the file specified by @racket[path] for output. The
@scheme[mode-flag] argument specifies how bytes written to the port @racket[mode-flag] argument specifies how bytes written to the port
are translated when written to the file: are translated when written to the file:
@itemize[ @itemize[
@item{@scheme['binary] --- bytes are written to the file exactly @item{@racket['binary] --- bytes are written to the file exactly
as written to the port.} as written to the port.}
@item{@scheme['text] --- under Windows, a linefeed byte (10) written @item{@racket['text] --- under Windows, a linefeed byte (10) written
to the port is translated to a return-linefeed combination in the to the port is translated to a return-linefeed combination in the
file; no filtering occurs for returns.} file; no filtering occurs for returns.}
] ]
Under Windows, @scheme['text] mode works only with regular files; Under Windows, @racket['text] mode works only with regular files;
attempting to use @scheme['text] with other kinds of files triggers an attempting to use @racket['text] with other kinds of files triggers an
@scheme[exn:fail:filesystem] exception. @racket[exn:fail:filesystem] exception.
The @scheme[exists-flag] argument specifies how to handle/require The @racket[exists-flag] argument specifies how to handle/require
files that already exist: files that already exist:
@itemize[ @itemize[
@item{@indexed-scheme['error] --- raise @scheme[exn:fail:filesystem] @item{@indexed-racket['error] --- raise @racket[exn:fail:filesystem]
if the file exists.} if the file exists.}
@item{@indexed-scheme['replace] --- remove the old file, if it @item{@indexed-racket['replace] --- remove the old file, if it
exists, and write a new one.} exists, and write a new one.}
@item{@indexed-scheme['truncate] --- remove all old data, if the file @item{@indexed-racket['truncate] --- remove all old data, if the file
exists.} exists.}
@item{@indexed-scheme['must-truncate] --- remove all old data in an @item{@indexed-racket['must-truncate] --- remove all old data in an
existing file; if the file does not exist, the existing file; if the file does not exist, the
@exnraise[exn:fail:filesystem].} @exnraise[exn:fail:filesystem].}
@item{@indexed-scheme['truncate/replace] --- try @scheme['truncate]; @item{@indexed-racket['truncate/replace] --- try @racket['truncate];
if it fails (perhaps due to file permissions), try if it fails (perhaps due to file permissions), try
@scheme['replace].} @racket['replace].}
@item{@indexed-scheme['update] --- open an existing file without @item{@indexed-racket['update] --- open an existing file without
truncating it; if the file does not exist, the truncating it; if the file does not exist, the
@exnraise[exn:fail:filesystem]. Use @scheme[file-position] @exnraise[exn:fail:filesystem]. Use @racket[file-position]
to change the current read/write position.} to change the current read/write position.}
@item{@indexed-scheme['can-update] --- open an existing file without @item{@indexed-racket['can-update] --- open an existing file without
truncating it, or create the file if it does not exist.} truncating it, or create the file if it does not exist.}
@item{@indexed-scheme['append] --- append to the end of the file, @item{@indexed-racket['append] --- append to the end of the file,
whether it already exists or not; under Windows, whether it already exists or not; under Windows,
@scheme['append] is equivalent to @scheme['update], except that @racket['append] is equivalent to @racket['update], except that
the file is not required to exist, and the file position is the file is not required to exist, and the file position is
immediately set to the end of the file after opening it.} immediately set to the end of the file after opening it.}
] ]
The file specified by @scheme[path] need not be a regular file. It The file specified by @racket[path] need not be a regular file. It
might a device that is connected through the filesystem, such as might a device that is connected through the filesystem, such as
@filepath{aux} under Windows or @filepath{/dev/null} under Unix. The output @filepath{aux} under Windows or @filepath{/dev/null} under Unix. The output
port is block-buffered by default, unless the file corresponds to a port is block-buffered by default, unless the file corresponds to a
terminal, in which case is it line buffered bu default. terminal, in which case is it line buffered bu default.
The port produced by @scheme[open-output-port] should be explicitly The port produced by @racket[open-output-port] should be explicitly
closed, either though @scheme[close-output-port] or indirectly via closed, either though @racket[close-output-port] or indirectly via
@scheme[custodian-shutdown-all], to release the OS-level file @racket[custodian-shutdown-all], to release the OS-level file
handle. The output port will not be closed automatically if it is handle. The output port will not be closed automatically if it is
otherwise available for garbage collection (see otherwise available for garbage collection (see
@secref["gc-model"]); a @tech{will} could be associated input port @secref["gc-model"]); a @tech{will} could be associated input port
to close it more automatically (see @secref["willexecutor"]). to close it more automatically (see @secref["willexecutor"]).
A @tech{path} value that is the @tech{cleanse}d version of A @tech{path} value that is the @tech{cleanse}d version of
@scheme[path] is used as the name of the opened port. @racket[path] is used as the name of the opened port.
@file-examples[ @file-examples[
(define out (open-output-file some-file)) (define out (open-output-file some-file))
@ -196,7 +196,7 @@ A @tech{path} value that is the @tech{cleanse}d version of
'replace 'truncate 'truncate/replace) 'error]) 'replace 'truncate 'truncate/replace) 'error])
(values input-port? output-port?)]{ (values input-port? output-port?)]{
Like @scheme[open-output-file], but producing two values: an input Like @racket[open-output-file], but producing two values: an input
port and an output port. The two ports are connected in that they port and an output port. The two ports are connected in that they
share the underlying file device. This procedure is intended for use share the underlying file device. This procedure is intended for use
with special devices that can be opened by only one process, such as with special devices that can be opened by only one process, such as
@ -204,18 +204,18 @@ with special devices that can be opened by only one process, such as
confusing. For example, using one port does not automatically flush confusing. For example, using one port does not automatically flush
the other port's buffer, and reading or writing in one port moves the the other port's buffer, and reading or writing in one port moves the
file position (if any) for the other port. For regular files, use file position (if any) for the other port. For regular files, use
separate @scheme[open-input-file] and @scheme[open-output-file] calls separate @racket[open-input-file] and @racket[open-output-file] calls
to avoid confusion.} to avoid confusion.}
@defproc[(call-with-input-file [path path-string?] @defproc[(call-with-input-file [path path-string?]
[proc (input-port? . -> . any)] [proc (input-port? . -> . any)]
[#:mode mode-flag (or/c 'binary 'text) 'binary]) [#:mode mode-flag (or/c 'binary 'text) 'binary])
any]{ any]{
Calls @scheme[open-input-file] with the @scheme[path] and Calls @racket[open-input-file] with the @racket[path] and
@scheme[mode-flag] arguments, and passes the resulting port @racket[mode-flag] arguments, and passes the resulting port
to @scheme[proc]. The result of @scheme[proc] is the result of the to @racket[proc]. The result of @racket[proc] is the result of the
@scheme[call-with-input-file] call, but the newly opened port is closed @racket[call-with-input-file] call, but the newly opened port is closed
when @scheme[thunk] return. when @racket[thunk] return.
@file-examples[ @file-examples[
(with-output-to-file some-file (with-output-to-file some-file
@ -230,9 +230,9 @@ when @scheme[thunk] return.
[#:exists exists-flag (or/c 'error 'append 'update [#:exists exists-flag (or/c 'error 'append 'update
'replace 'truncate 'truncate/replace) 'error]) 'replace 'truncate 'truncate/replace) 'error])
any]{ any]{
Analogous to @scheme[call-with-input-file], but passing @scheme[path], Analogous to @racket[call-with-input-file], but passing @racket[path],
@scheme[mode-flag] and @scheme[exists-flag] to @racket[mode-flag] and @racket[exists-flag] to
@scheme[open-output-file]. @racket[open-output-file].
@file-examples[ @file-examples[
(call-with-output-file some-file (call-with-output-file some-file
@ -247,9 +247,9 @@ Analogous to @scheme[call-with-input-file], but passing @scheme[path],
[proc (input-port? . -> . any)] [proc (input-port? . -> . any)]
[#:mode mode-flag (or/c 'binary 'text) 'binary]) [#:mode mode-flag (or/c 'binary 'text) 'binary])
any]{ any]{
Like @scheme[call-with-input-file], but the newly opened port is Like @racket[call-with-input-file], but the newly opened port is
closed whenever control escapes the dynamic extent of the closed whenever control escapes the dynamic extent of the
@scheme[call-with-input-file*] call, whether through @scheme[proc]'s @racket[call-with-input-file*] call, whether through @racket[proc]'s
return, a continuation application, or a prompt-based abort.} return, a continuation application, or a prompt-based abort.}
@defproc[(call-with-output-file* [path path-string?] @defproc[(call-with-output-file* [path path-string?]
@ -258,19 +258,19 @@ return, a continuation application, or a prompt-based abort.}
[#:exists exists-flag (or/c 'error 'append 'update [#:exists exists-flag (or/c 'error 'append 'update
'replace 'truncate 'truncate/replace) 'error]) 'replace 'truncate 'truncate/replace) 'error])
any]{ any]{
Like @scheme[call-with-output-file], but the newly opened port is Like @racket[call-with-output-file], but the newly opened port is
closed whenever control escapes the dynamic extent of the closed whenever control escapes the dynamic extent of the
@scheme[call-with-output-file*] call, whether through @scheme[proc]'s @racket[call-with-output-file*] call, whether through @racket[proc]'s
return, a continuation application, or a prompt-based abort.} return, a continuation application, or a prompt-based abort.}
@defproc[(with-input-from-file [path path-string?] @defproc[(with-input-from-file [path path-string?]
[thunk (-> any)] [thunk (-> any)]
[#:mode mode-flag (or/c 'binary 'text) 'binary]) [#:mode mode-flag (or/c 'binary 'text) 'binary])
any]{ any]{
Like @scheme[call-with-input-file*], but instead of passing the newly Like @racket[call-with-input-file*], but instead of passing the newly
opened port to the given procedure argument, the port is installed as opened port to the given procedure argument, the port is installed as
the current input port (see @scheme[current-input-port]) using the current input port (see @racket[current-input-port]) using
@scheme[parameterize] around the call to @scheme[thunk]. @racket[parameterize] around the call to @racket[thunk].
@file-examples[ @file-examples[
(with-output-to-file some-file (with-output-to-file some-file
@ -285,10 +285,10 @@ the current input port (see @scheme[current-input-port]) using
[#:exists exists-flag (or/c 'error 'append 'update [#:exists exists-flag (or/c 'error 'append 'update
'replace 'truncate 'truncate/replace) 'error]) 'replace 'truncate 'truncate/replace) 'error])
any]{ any]{
Like @scheme[call-with-output-file*], but instead of passing the newly Like @racket[call-with-output-file*], but instead of passing the newly
opened port to the given procedure argument, the port is installed as opened port to the given procedure argument, the port is installed as
the current output port (see @scheme[current-output-port]) using the current output port (see @racket[current-output-port]) using
@scheme[parameterize] around the call to @scheme[thunk]. @racket[parameterize] around the call to @racket[thunk].
@file-examples[ @file-examples[
(with-output-to-file some-file (with-output-to-file some-file
@ -301,14 +301,14 @@ the current output port (see @scheme[current-output-port]) using
@index['("inode")]{Returns} a number that represents @index['("inode")]{Returns} a number that represents
the identity of the device and file read or written by the identity of the device and file read or written by
@scheme[port]. For two ports whose open times overlap, the @racket[port]. For two ports whose open times overlap, the
result of @scheme[port-file-identity] is the same for both ports if result of @racket[port-file-identity] is the same for both ports if
and only if the ports access the same device and file. For ports whose and only if the ports access the same device and file. For ports whose
open times do not overlap, no guarantee can be provided for the port open times do not overlap, no guarantee can be provided for the port
identities (even if the ports actually access the same file)---except identities (even if the ports actually access the same file)---except
as can be inferred through relationships with other ports. If as can be inferred through relationships with other ports. If
@scheme[port] is closed, the @exnraise[exn:fail]. Under @racket[port] is closed, the @exnraise[exn:fail]. Under
Windows 95, 98, and Me, if @scheme[port] is connected to a Windows 95, 98, and Me, if @racket[port] is connected to a
pipe instead of a file, the @exnraise[exn:fail:filesystem]. pipe instead of a file, the @exnraise[exn:fail:filesystem].
@file-examples[ @file-examples[

20
collects/scribblings/reference/filesystem.scrbl
View File

@ -64,19 +64,19 @@ by @racket[kind], which must be one of the following:
if it is defined, otherwise it is the current directory.} if it is defined, otherwise it is the current directory.}
@item{@indexed-racket['init-dir] --- the directory containing the @item{@indexed-racket['init-dir] --- the directory containing the
initialization file used by stand-alone @exec{mzracket} executable. initialization file used by the Racket executable.
It is the same as the current user's home directory.} It is the same as the current user's home directory.}
@item{@indexed-racket['init-file] --- the file loaded at start-up by @item{@indexed-racket['init-file] --- the file loaded at start-up by
the stand-alone @exec{mzracket} executable. The directory part of the the Racket executable. The directory part of the
path is the same path as returned for @racket['init-dir]. The file path is the same path as returned for @racket['init-dir]. The file
name is platform-specific: name is platform-specific:
@itemize[ @itemize[
@item{@|AllUnix|: @indexed-file{.mzracketrc}} @item{@|AllUnix|: @indexed-file{.racketrc}}
@item{Windows: @indexed-file{mzracketrc.rkt}} @item{Windows: @indexed-file{racketrc.rkt}}
]} ]}
@ -109,7 +109,7 @@ by @racket[kind], which must be one of the following:
operating system for Windows. Under @|AllUnix|, the operating system for Windows. Under @|AllUnix|, the
result is @racket["/"].} result is @racket["/"].}
@item{@indexed-racket['exec-file] --- the path of the @exec{mzracket} @item{@indexed-racket['exec-file] --- the path of the Racket
executable as provided by the operating system for the current executable as provided by the operating system for the current
invocation. invocation.
@ -119,10 +119,10 @@ by @racket[kind], which must be one of the following:
@item{@indexed-racket['run-file] --- the path of the current @item{@indexed-racket['run-file] --- the path of the current
executable; this may be different from result for executable; this may be different from result for
@racket['exec-file] because an alternate path was provided through a @racket['exec-file] because an alternate path was provided through a
@DFlag{name} or @Flag{N} command-line flag to the @exec{mzracket} @DFlag{name} or @Flag{N} command-line flag to the Racket
(or @exec{mred}) executable, or because an embedding executable (or GRacket) executable, or because an embedding executable
installed an alternate path. In particular a ``launcher'' script installed an alternate path. In particular a ``launcher'' script
created by @racket[make-mzracket-launcher] sets this path to the created by @racket[make-racket-launcher] sets this path to the
script's path.} script's path.}
@item{@indexed-racket['collects-dir] --- a path to the main @item{@indexed-racket['collects-dir] --- a path to the main
@ -132,7 +132,7 @@ by @racket[kind], which must be one of the following:
soft-link or relative to the user's executable search path, so that soft-link or relative to the user's executable search path, so that
the two results should be combined with the two results should be combined with
@racket[find-executable-path]. The @racket['collects-dir] path is @racket[find-executable-path]. The @racket['collects-dir] path is
normally embedded in the @exec{mzracket} executable, but it can be normally embedded in the Racket executable, but it can be
overridden by the @DFlag{collects} or @Flag{X} command-line flag.} overridden by the @DFlag{collects} or @Flag{X} command-line flag.}
@item{@indexed-racket['orig-dir] --- the current directory at @item{@indexed-racket['orig-dir] --- the current directory at
@ -170,7 +170,7 @@ that the file or directory @racket[related-sub] exists in the same
directory as the executable. The result is then the full path for the directory as the executable. The result is then the full path for the
found @racket[related-sub], instead of the path for the executable. found @racket[related-sub], instead of the path for the executable.
This procedure is used by the @exec{mzracket} executable to find the This procedure is used by the Racket executable to find the
standard library collection directory (see @secref["collects"]). In standard library collection directory (see @secref["collects"]). In
this case, @racket[program] is the name used to start Racket and this case, @racket[program] is the name used to start Racket and
@racket[related] is @racket["collects"]. The @racket[related-sub] @racket[related] is @racket["collects"]. The @racket[related-sub]

42
collects/scribblings/reference/futures.scrbl
View File

@ -11,35 +11,35 @@
@note-lib[racket/future] @note-lib[racket/future]
@margin-note{Currently, parallel support for @scheme[future] is @margin-note{Currently, parallel support for @racket[future] is
enabled by default for Windows, Linux x86/x86_64, and Mac OS X enabled by default for Windows, Linux x86/x86_64, and Mac OS X
x86/x86_64. To enable support for other platforms, use x86/x86_64. To enable support for other platforms, use
@DFlag{enable-futures} with @exec{configure} when building PLT @DFlag{enable-futures} with @exec{configure} when building
Scheme.} Racket.}
The @scheme[future] and @scheme[touch] functions from The @racket[future] and @racket[touch] functions from
@schememodname[racket/future] provide access to parallelism as @racketmodname[racket/future] provide access to parallelism as
supported by the hardware and operation system. supported by the hardware and operation system.
In contrast to @scheme[thread], which provides concurrency for In contrast to @racket[thread], which provides concurrency for
arbitrary computations without parallelism, @scheme[future] provides arbitrary computations without parallelism, @racket[future] provides
parallelism for limited computations. A future executes its work in parallelism for limited computations. A future executes its work in
parallel (assuming that support for parallelism is available) until it parallel (assuming that support for parallelism is available) until it
detects an attempt to perform an operation that is too complex for the detects an attempt to perform an operation that is too complex for the
system to run safely in parallel. Similarly, work in a future is system to run safely in parallel. Similarly, work in a future is
suspended if it depends in some way on the current continuation, such suspended if it depends in some way on the current continuation, such
as raising an exception. A suspended computation for a future is as raising an exception. A suspended computation for a future is
resumed when @scheme[touch] is applied to the future. resumed when @racket[touch] is applied to the future.
``Safe'' parallel execution of a future means that all operations ``Safe'' parallel execution of a future means that all operations
provided by the system must be able to enforce contracts and produce provided by the system must be able to enforce contracts and produce
results as documented. ``Safe'' does not preclude concurrent access to results as documented. ``Safe'' does not preclude concurrent access to
mutable data that is visible in the program. For example, a mutable data that is visible in the program. For example, a
computation in a future might use @scheme[set!] to modify a shared computation in a future might use @racket[set!] to modify a shared
variable, in which case concurrent assignment to the variable can be variable, in which case concurrent assignment to the variable can be
visible in other futures and threads. Furthermore, guarantees about visible in other futures and threads. Furthermore, guarantees about
the visibility of effects and ordering are determined by the operating the visibility of effects and ordering are determined by the operating
system and hardware---which rarely support, for example, the guarantee system and hardware---which rarely support, for example, the guarantee
of sequential consistency that is provided for @scheme[thread]-based of sequential consistency that is provided for @racket[thread]-based
concurrency. At the same time, operations that seem obviously safe may concurrency. At the same time, operations that seem obviously safe may
have a complex enough implementation internally that they cannot run have a complex enough implementation internally that they cannot run
in parallel. See also @guidesecref["effective-futures"]. in parallel. See also @guidesecref["effective-futures"].
@ -49,16 +49,16 @@ in parallel. See also @guidesecref["effective-futures"].
@defproc[(touch [f future?]) any] @defproc[(touch [f future?]) any]
)]{ )]{
The @scheme[future] procedure returns a future value that The @racket[future] procedure returns a future value that
encapsulates @scheme[thunk]. The @scheme[touch] function forces the encapsulates @racket[thunk]. The @racket[touch] function forces the
evaluation of the @scheme[thunk] inside the given future, returning evaluation of the @racket[thunk] inside the given future, returning
the values produced by @scheme[thunk]. After @scheme[touch] forces the values produced by @racket[thunk]. After @racket[touch] forces
the evaluation of a @scheme[thunk], the resulting values are retained the evaluation of a @racket[thunk], the resulting values are retained
by the future descriptor in place of @scheme[thunk], and additional by the future descriptor in place of @racket[thunk], and additional
@scheme[touch]es of the future descriptor return those values. @racket[touch]es of the future descriptor return those values.
Between a call to @scheme[future] and @scheme[touch] for a given Between a call to @racket[future] and @racket[touch] for a given
future, the given @scheme[thunk] may run speculatively in parallel to future, the given @racket[thunk] may run speculatively in parallel to
other computations, as described above. other computations, as described above.
@interaction[ @interaction[
@ -69,8 +69,8 @@ in parallel. See also @guidesecref["effective-futures"].
@defproc[(future? [v any/c]) boolean?]{ @defproc[(future? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] is a future-descriptor value, Returns @racket[#t] if @racket[v] is a future-descriptor value,
@scheme[#f] otherwise. @racket[#f] otherwise.
} }
@defproc[(processor-count) exact-positive-integer?]{ @defproc[(processor-count) exact-positive-integer?]{

4
collects/scribblings/reference/help.scrbl
View File

@ -67,8 +67,8 @@ introduces a binding without actually executing the
documentation, but cannot or do not want to run the providing module. documentation, but cannot or do not want to run the providing module.
@schemeblock[ @schemeblock[
(require racket/gui) (code:comment @#,t{does not work in @exec{mzscheme}}) (require racket/gui) (code:comment @#,t{does not work in @exec{racket}})
(require (for-label racket/gui)) (code:comment @#,t{ok in @exec{mzscheme}}) (require (for-label racket/gui)) (code:comment @#,t{ok in @exec{racket}})
(help frame%) (help frame%)
] ]

18
collects/scribblings/reference/init.scrbl
View File

@ -5,14 +5,14 @@
@title{Init Libraries} @title{Init Libraries}
@defmodule*/no-declare[(racket/init)]{The @schememodname[racket/init] @defmodule*/no-declare[(racket/init)]{The @racketmodname[racket/init]
library is the default start-up library for MzScheme. It re-exports library is the default start-up library for Racket. It re-exports
the @schememodname[scheme], @schememodname[racket/enter] and the @racketmodname[racket], @racketmodname[racket/enter] and
@schememodname[racket/help] libraries, and it sets @racketmodname[racket/help] libraries, and it sets
@scheme[current-print] to use @scheme[pretty-print].} @racket[current-print] to use @racket[pretty-print].}
@defmodule*/no-declare[(racket/gui/init)]{The @defmodule*/no-declare[(racket/gui/init)]{The
@schememodname[racket/gui/init] library is the default start-up @racketmodname[racket/gui/init] library is the default start-up
library for MrEd. It re-exports the @schememodname[racket/init] and library for GRacket. It re-exports the @racketmodname[racket/init] and
@schememodname[racket/gui/base] libraries, and it sets @racketmodname[racket/gui/base] libraries, and it sets
@scheme[current-load] to use @scheme[text-editor-load-handler].} @racket[current-load] to use @racket[text-editor-load-handler].}

46
collects/scribblings/reference/load-lang.scrbl
View File

@ -1,30 +1,30 @@
#lang scribble/doc #lang scribble/doc
@(require "mz.ss") @(require "mz.ss")
@title[#:tag "load-lang"]{The @schememodname[racket/load] Language} @title[#:tag "load-lang"]{The @racketmodname[racket/load] Language}
@defmodulelang[racket/load] @defmodulelang[racket/load]
The @schememodname[racket/load] language supports traditional Scheme The @racketmodname[racket/load] language supports evaluation where
evaluation, where each top-level form in the module body is separately each top-level form in the module body is separately passed to
passed to @scheme[eval] in the same way as for @scheme[load]. @racket[eval] in the same way as for @racket[load].
The namespace for evaluation shares the @tech{module registry} with The namespace for evaluation shares the @tech{module registry} with
the @schememodname[racket/load] module instance, but it has a separate the @racketmodname[racket/load] module instance, but it has a separate
top-level environment, and it is initialized with the bindings of top-level environment, and it is initialized with the bindings of
@schememodname[scheme]. A single namespace is created for each @racketmodname[racket]. A single namespace is created for each
instance of the @schememodname[racket/load] module (i.e., multiple instance of the @racketmodname[racket/load] module (i.e., multiple
modules using the @schememodname[racket/load] language share a modules using the @racketmodname[racket/load] language share a
namespace). The @scheme[racket/load] library exports only namespace). The @racket[racket/load] library exports only
@schemeidfont{#%module-begin} and @schemeidfont{#%top-interaction} @racketidfont{#%module-begin} and @racketidfont{#%top-interaction}
forms that effectively swap in the evaluation namespace and call forms that effectively swap in the evaluation namespace and call
@scheme[eval]. @racket[eval].
For example, the body of a module using @scheme[racket/load] can For example, the body of a module using @racket[racket/load] can
include @scheme[module] forms, so that running the following module include @racket[module] forms, so that running the following module
prints @schemeresultfont{5}: prints @racketresultfont{5}:
@schememod[ @racketmod[
racket/load racket/load
(module m racket/base (module m racket/base
@ -38,22 +38,22 @@ racket/load
(require 'n) (require 'n)
] ]
Definitions in a module using @scheme[racket/load] are evaluated in Definitions in a module using @racket[racket/load] are evaluated in
the current namespace, which means that @scheme[load] and the current namespace, which means that @racket[load] and
@scheme[eval] can see the definitions. For example, running the @racket[eval] can see the definitions. For example, running the
following module prints @schemeresultfont{6}: following module prints @racketresultfont{6}:
@schememod[ @racketmod[
racket/load racket/load
(define x 6) (define x 6)
(display (eval 'x)) (display (eval 'x))
] ]
Since all forms within a @schememodname[racket/load] module are Since all forms within a @racketmodname[racket/load] module are
evaluated in the top level, bindings cannot be exported from the evaluated in the top level, bindings cannot be exported from the
module using @scheme[provide]. Similarly, since evaluation of the module using @racket[provide]. Similarly, since evaluation of the
module-body forms is inherently dynamic, compilation of the module module-body forms is inherently dynamic, compilation of the module
provides essentially no benefit. For these reasons, use provides essentially no benefit. For these reasons, use
@schememodname[racket/load] for interactive exploration of top-level @racketmodname[racket/load] for interactive exploration of top-level
forms only, and not for constructing larger programs. forms only, and not for constructing larger programs.

1
collects/scribblings/reference/match-grammar.ss
View File

@ -18,6 +18,7 @@ pat ::= id @match anything, bind identifier
| (CONS pat pat) @match pair of pats | (CONS pat pat) @match pair of pats
| (MCONS pat pat) @match mutable pair of pats | (MCONS pat pat) @match mutable pair of pats
| (BOX pat) @match boxed pat | (BOX pat) @match boxed pat
| (struct-id pat ...) @match struct-id instance
| (STRUCT struct-id (pat ...)) @match struct-id instance | (STRUCT struct-id (pat ...)) @match struct-id instance
| (REGEXP rx-expr) @match string | (REGEXP rx-expr) @match string
| (REGEXP rx-expr pat) @match string, result with pat | (REGEXP rx-expr pat) @match string, result with pat

243
collects/scribblings/reference/match.scrbl
View File

@ -10,8 +10,8 @@
@guideintro["match"]{pattern matching} @guideintro["match"]{pattern matching}
The @scheme[match] form and related forms support general pattern The @racket[match] form and related forms support general pattern
matching on Scheme values. See also @secref["regexp"] for information matching on Racket values. See also @secref["regexp"] for information
on regular-expression matching on strings, bytes, and streams. on regular-expression matching on strings, bytes, and streams.
@note-lib[racket/match #:use-sources (racket/match)] @note-lib[racket/match #:use-sources (racket/match)]
@ -20,24 +20,24 @@ on regular-expression matching on strings, bytes, and streams.
([clause [pat expr ...+] ([clause [pat expr ...+]
[pat (=> id) expr ...+]])]{ [pat (=> id) expr ...+]])]{
Finds the first @scheme[pat] that matches the result of Finds the first @racket[pat] that matches the result of
@scheme[val-expr], and evaluates the corresponding @scheme[expr]s with @racket[val-expr], and evaluates the corresponding @racket[expr]s with
bindings introduced by @scheme[pat] (if any). The last @scheme[expr] bindings introduced by @racket[pat] (if any). The last @racket[expr]
in the matching clause is evaluated in tail position with respect to in the matching clause is evaluated in tail position with respect to
the @scheme[match] expression. the @racket[match] expression.
The @scheme[clause]s are tried in order to find a match. If no The @racket[clause]s are tried in order to find a match. If no
@scheme[clause] matches, then the @exnraise[exn:misc:match?]. @racket[clause] matches, then the @exnraise[exn:misc:match?].
An optional @scheme[(=> id)] between a @scheme[pat] and the An optional @racket[(=> id)] between a @racket[pat] and the
@scheme[expr]s is bound to a @defterm{failure procedure} of zero @racket[expr]s is bound to a @defterm{failure procedure} of zero
arguments. If this procedure is invoked, it escapes back to the arguments. If this procedure is invoked, it escapes back to the
pattern matching expression, and resumes the matching process as if pattern matching expression, and resumes the matching process as if
the pattern had failed to match. The @scheme[expr]s must not mutate the pattern had failed to match. The @racket[expr]s must not mutate
the object being matched before calling the failure procedure, the object being matched before calling the failure procedure,
otherwise the behavior of matching is unpredictable. otherwise the behavior of matching is unpredictable.
The grammar of @scheme[pat] is as follows, where non-italicized The grammar of @racket[pat] is as follows, where non-italicized
identifiers are recognized symbolically (i.e., not by binding). identifiers are recognized symbolically (i.e., not by binding).
@|match-grammar| @|match-grammar|
@ -46,16 +46,16 @@ In more detail, patterns match as follows:
@itemize[ @itemize[
@item{@scheme[_id], excluding the reserved names @schemeidfont{_}, @item{@racket[_id], excluding the reserved names @racketidfont{_},
@schemeidfont{...}, @schemeidfont{.._}, @racketidfont{...}, @racketidfont{.._},
@schemeidfont{..}@scheme[_k], and @racketidfont{..}@racket[_k], and
@schemeidfont{..}@scheme[_k] for non-negative integers @racketidfont{..}@racket[_k] for non-negative integers
@scheme[_k] --- matches anything, and binds @scheme[id] to the @racket[_k] --- matches anything, and binds @racket[id] to the
matching values. If an @scheme[_id] is used multiple times matching values. If an @racket[_id] is used multiple times
within a pattern, the corresponding matches must be the same within a pattern, the corresponding matches must be the same
according to @scheme[(match-equality-test)], except that according to @racket[(match-equality-test)], except that
instances of an @scheme[_id] in different @schemeidfont{or} and instances of an @racket[_id] in different @racketidfont{or} and
@schemeidfont{not} sub-patterns are independent. @racketidfont{not} sub-patterns are independent.
@examples[ @examples[
#:eval match-eval #:eval match-eval
@ -67,7 +67,7 @@ In more detail, patterns match as follows:
[(list a b c) (list c b a)]) [(list a b c) (list c b a)])
]} ]}
@item{@schemeidfont{_} --- matches anything, without binding any @item{@racketidfont{_} --- matches anything, without binding any
identifiers. identifiers.
@examples[ @examples[
@ -76,9 +76,9 @@ In more detail, patterns match as follows:
[(list _ _ a) a]) [(list _ _ a) a])
]} ]}
@item{@scheme[#t], @scheme[#f], @scheme[_string], @scheme[_bytes], @item{@racket[#t], @racket[#f], @racket[_string], @racket[_bytes],
@scheme[_number], @scheme[_char], or @scheme[(#,(schemeidfont @racket[_number], @racket[_char], or @racket[(#,(racketidfont
"quote") _datum)] --- matches an @scheme[equal?] constant. "quote") _datum)] --- matches an @racket[equal?] constant.
@examples[ @examples[
#:eval match-eval #:eval match-eval
@ -87,17 +87,17 @@ In more detail, patterns match as follows:
["yes" #t]) ["yes" #t])
]} ]}
@item{@scheme[(#,(schemeidfont "list") _lvp ...)] --- matches a list @item{@racket[(#,(racketidfont "list") _lvp ...)] --- matches a list
of elements. In the case of @scheme[(#,(schemeidfont "list") of elements. In the case of @racket[(#,(racketidfont "list")
_pat ...)], the pattern matches a list with as many element as _pat ...)], the pattern matches a list with as many element as
@scheme[_pat]s, and each element must match the corresponding @racket[_pat]s, and each element must match the corresponding
@scheme[_pat]. In the more general case, each @scheme[_lvp] @racket[_pat]. In the more general case, each @racket[_lvp]
corresponds to a ``spliced'' list of greedy matches. corresponds to a ``spliced'' list of greedy matches.
For spliced lists, @schemeidfont{...} and @schemeidfont{___} For spliced lists, @racketidfont{...} and @racketidfont{___}
are synonyms for zero or more matches. The are synonyms for zero or more matches. The
@schemeidfont{..}@scheme[_k] and @schemeidfont{__}@scheme[_k] @racketidfont{..}@racket[_k] and @racketidfont{__}@racket[_k]
forms are also synonyms, specifying @scheme[_k] or more forms are also synonyms, specifying @racket[_k] or more
matches. Pattern variables that precede these splicing matches. Pattern variables that precede these splicing
operators are bound to lists of matching forms. operators are bound to lists of matching forms.
@ -121,11 +121,11 @@ In more detail, patterns match as follows:
[_ 'else]) [_ 'else])
]} ]}
@item{@scheme[(#,(schemeidfont "list-rest") _lvp ... _pat)] --- @item{@racket[(#,(racketidfont "list-rest") _lvp ... _pat)] ---
similar to a @schemeidfont{list} pattern, but the final similar to a @racketidfont{list} pattern, but the final
@scheme[_pat] matches the ``rest'' of the list after the last @racket[_pat] matches the ``rest'' of the list after the last
@scheme[_lvp]. In fact, the matched value can be a non-list @racket[_lvp]. In fact, the matched value can be a non-list
chain of pairs (i.e., an ``improper list'') if @scheme[_pat] chain of pairs (i.e., an ``improper list'') if @racket[_pat]
matches non-list values. matches non-list values.
@examples[ @examples[
@ -136,9 +136,9 @@ In more detail, patterns match as follows:
[(list-rest a ... d) (list a d)]) [(list-rest a ... d) (list a d)])
]} ]}
@item{@scheme[(#,(schemeidfont "list-no-order") _pat ...)] --- @item{@racket[(#,(racketidfont "list-no-order") _pat ...)] ---
similar to a @schemeidfont{list} pattern, but the elements to similar to a @racketidfont{list} pattern, but the elements to
match each @scheme[_pat] can appear in the list in any order. match each @racket[_pat] can appear in the list in any order.
@examples[ @examples[
#:eval match-eval #:eval match-eval
@ -146,8 +146,8 @@ In more detail, patterns match as follows:
[(list-no-order 3 2 x) x]) [(list-no-order 3 2 x) x])
]} ]}
@item{@scheme[(#,(schemeidfont "list-no-order") _pat ... _lvp)] --- @item{@racket[(#,(racketidfont "list-no-order") _pat ... _lvp)] ---
generalizes @schemeidfont{list-no-order} to allow a pattern generalizes @racketidfont{list-no-order} to allow a pattern
that matches multiple list elements that are interspersed in that matches multiple list elements that are interspersed in
any order with matches for the other patterns. any order with matches for the other patterns.
@ -157,8 +157,8 @@ In more detail, patterns match as follows:
[(list-no-order 6 2 y ...) y]) [(list-no-order 6 2 y ...) y])
]} ]}
@item{@scheme[(#,(schemeidfont "vector") _lvp ...)] --- like a @item{@racket[(#,(racketidfont "vector") _lvp ...)] --- like a
@schemeidfont{list} pattern, but matching a vector. @racketidfont{list} pattern, but matching a vector.
@examples[ @examples[
#:eval match-eval #:eval match-eval
@ -166,8 +166,8 @@ In more detail, patterns match as follows:
[(vector 1 (list a) ..3 5) a]) [(vector 1 (list a) ..3 5) a])
]} ]}
@item{@scheme[(#,(schemeidfont "hash-table") (_pat _pat) ...)] --- @item{@racket[(#,(racketidfont "hash-table") (_pat _pat) ...)] ---
similar to @schemeidfont{list-no-order}, but matching against similar to @racketidfont{list-no-order}, but matching against
hash table's key--value pairs. hash table's key--value pairs.
@examples[ @examples[
@ -176,8 +176,8 @@ In more detail, patterns match as follows:
[(hash-table ("b" b) ("a" a)) (list b a)]) [(hash-table ("b" b) ("a" a)) (list b a)])
]} ]}
@item{@scheme[(#,(schemeidfont "hash-table") (_pat _pat) ...+ _ooo)] @item{@racket[(#,(racketidfont "hash-table") (_pat _pat) ...+ _ooo)]
--- Generalizes @schemeidfont{hash-table} to support a final --- Generalizes @racketidfont{hash-table} to support a final
repeating pattern. repeating pattern.
@examples[ @examples[
@ -186,7 +186,7 @@ In more detail, patterns match as follows:
[(hash-table (key val) ...) key]) [(hash-table (key val) ...) key])
]} ]}
@item{@scheme[(#,(schemeidfont "cons") _pat1 _pat2)] --- matches a pair value. @item{@racket[(#,(racketidfont "cons") _pat1 _pat2)] --- matches a pair value.
@examples[ @examples[
#:eval match-eval #:eval match-eval
@ -194,7 +194,7 @@ In more detail, patterns match as follows:
[(cons a b) (+ a b)]) [(cons a b) (+ a b)])
]} ]}
@item{@scheme[(#,(schemeidfont "mcons") _pat1 _pat2)] --- matches a mutable pair value. @item{@racket[(#,(racketidfont "mcons") _pat1 _pat2)] --- matches a mutable pair value.
@examples[ @examples[
#:eval match-eval #:eval match-eval
@ -203,7 +203,7 @@ In more detail, patterns match as follows:
[(mcons a b) 'mutable]) [(mcons a b) 'mutable])
]} ]}
@item{@scheme[(#,(schemeidfont "box") _pat)] --- matches a boxed value. @item{@racket[(#,(racketidfont "box") _pat)] --- matches a boxed value.
@examples[ @examples[
#:eval match-eval #:eval match-eval
@ -211,37 +211,38 @@ In more detail, patterns match as follows:
[(box a) a]) [(box a) a])
]} ]}
@item{@scheme[(#,(schemeidfont "struct") _struct-id (_pat ...))] --- @item{@racket[(_struct-id _pat ...)] or
@racket[(#,(racketidfont "struct") _struct-id (_pat ...))] ---
matches an instance of a structure type names matches an instance of a structure type names
@scheme[_struct-id], where each field in the instance matches @racket[_struct-id], where each field in the instance matches
the corresponding @scheme[_pat]. the corresponding @racket[_pat]. See also @scheme[struct*].
Usually, @scheme[_struct-id] is defined with Usually, @racket[_struct-id] is defined with
@scheme[define-struct]. More generally, @scheme[_struct-id] @racket[struct]. More generally, @racket[_struct-id]
must be bound to expansion-time information for a structure must be bound to expansion-time information for a structure
type (see @secref["structinfo"]), where the information type (see @secref["structinfo"]), where the information
includes at least a predicate binding and field accessor includes at least a predicate binding and field accessor
bindings corresponding to the number of field bindings corresponding to the number of field
@scheme[_pat]s. In particular, a module import or a @racket[_pat]s. In particular, a module import or a
@scheme[unit] import with a signature containing a @racket[unit] import with a signature containing a
@scheme[struct] declaration can provide the structure type @racket[struct] declaration can provide the structure type
information. information.
@defexamples[ @defexamples[
#:eval match-eval #:eval match-eval
(define-struct tree (val left right)) (define-struct tree (val left right))
(match (make-tree 0 (make-tree 1 #f #f) #f) (match (make-tree 0 (make-tree 1 #f #f) #f)
[(struct tree (a (struct tree (b _ _)) _)) (list a b)]) [(tree a (tree b _ _) _) (list a b)])
]} ]}
@item{@scheme[(#,(schemeidfont "struct") _struct-id _)] --- @item{@racket[(#,(racketidfont "struct") _struct-id _)] ---
matches any instance of @scheme[_struct-id], without regard to matches any instance of @racket[_struct-id], without regard to
contents of the fields of the instance. contents of the fields of the instance.
} }
@item{@scheme[(#,(schemeidfont "regexp") _rx-expr)] --- matches a @item{@racket[(#,(racketidfont "regexp") _rx-expr)] --- matches a
string that matches the regexp pattern produced by string that matches the regexp pattern produced by
@scheme[_rx-expr]; see @secref["regexp"] for more information @racket[_rx-expr]; see @secref["regexp"] for more information
about regexps. about regexps.
@examples[ @examples[
@ -254,10 +255,10 @@ In more detail, patterns match as follows:
[_ 'no]) [_ 'no])
]} ]}
@item{@scheme[(#,(schemeidfont "regexp") _rx-expr _pat)] --- extends @item{@racket[(#,(racketidfont "regexp") _rx-expr _pat)] --- extends
the @schemeidfont{regexp} form to further constrain the match the @racketidfont{regexp} form to further constrain the match
where the result of @scheme[regexp-match] is matched against where the result of @racket[regexp-match] is matched against
@scheme[_pat]. @racket[_pat].
@examples[ @examples[
#:eval match-eval #:eval match-eval
@ -269,16 +270,16 @@ In more detail, patterns match as follows:
[_ 'no]) [_ 'no])
]} ]}
@item{@scheme[(#,(schemeidfont "pregexp") _rx-expr)] or @item{@racket[(#,(racketidfont "pregexp") _rx-expr)] or
@scheme[(#,(schemeidfont "regexp") _rx-expr _pat)] --- like the @racket[(#,(racketidfont "regexp") _rx-expr _pat)] --- like the
@schemeidfont{regexp} patterns, but if @scheme[_rx-expr] @racketidfont{regexp} patterns, but if @racket[_rx-expr]
produces a string, it is converted to a pattern using produces a string, it is converted to a pattern using
@scheme[pregexp] instead of @scheme[regexp].} @racket[pregexp] instead of @racket[regexp].}
@item{@scheme[(#,(schemeidfont "and") _pat ...)] --- matches if all @item{@racket[(#,(racketidfont "and") _pat ...)] --- matches if all
of the @scheme[_pat]s match. This pattern is often used as of the @racket[_pat]s match. This pattern is often used as
@scheme[(#,(schemeidfont "and") _id _pat)] to bind @scheme[_id] @racket[(#,(racketidfont "and") _id _pat)] to bind @racket[_id]
to the entire value that matches @scheme[pat]. to the entire value that matches @racket[pat].
@examples[ @examples[
#:eval match-eval #:eval match-eval
@ -286,12 +287,12 @@ In more detail, patterns match as follows:
[(list _ (and a (list _ ...)) _) a]) [(list _ (and a (list _ ...)) _) a])
]} ]}
@item{@scheme[(#,(schemeidfont "or") _pat ...)] --- matches if any of @item{@racket[(#,(racketidfont "or") _pat ...)] --- matches if any of
the @scheme[_pat]s match. @bold{Beware}: the result expression the @racket[_pat]s match. @bold{Beware}: the result expression
can be duplicated once for each @scheme[_pat]! Identifiers in can be duplicated once for each @racket[_pat]! Identifiers in
@scheme[_pat] are bound only in the corresponding copy of the @racket[_pat] are bound only in the corresponding copy of the
result expression; in a module context, if the result result expression; in a module context, if the result
expression refers to a binding, then that all @scheme[_pat]s expression refers to a binding, then that all @racket[_pat]s
must include the binding. must include the binding.
@examples[ @examples[
@ -300,8 +301,8 @@ In more detail, patterns match as follows:
[(or (list a 1) (list a 2)) a]) [(or (list a 1) (list a 2)) a])
]} ]}
@item{@scheme[(#,(schemeidfont "not") _pat ...)] --- matches when @item{@racket[(#,(racketidfont "not") _pat ...)] --- matches when
none of the @scheme[_pat]s match, and binds no identifiers. none of the @racket[_pat]s match, and binds no identifiers.
@examples[ @examples[
#:eval match-eval #:eval match-eval
@ -313,9 +314,9 @@ In more detail, patterns match as follows:
[_ 'no]) [_ 'no])
]} ]}
@item{@scheme[(#,(schemeidfont "app") _expr _pat)] --- applies @item{@racket[(#,(racketidfont "app") _expr _pat)] --- applies
@scheme[_expr] to the value to be matched; the result of the @racket[_expr] to the value to be matched; the result of the
application is matched againt @scheme[_pat]. application is matched againt @racket[_pat].
@examples[ @examples[
#:eval match-eval #:eval match-eval
@ -323,11 +324,11 @@ In more detail, patterns match as follows:
[(app length 2) 'yes]) [(app length 2) 'yes])
]} ]}
@item{@scheme[(#,(schemeidfont "?") _expr _pat ...)] --- applies @item{@racket[(#,(racketidfont "?") _expr _pat ...)] --- applies
@scheme[_expr] to the value to be matched, and checks whether @racket[_expr] to the value to be matched, and checks whether
the result is a true value; the additional @scheme[_pat]s must the result is a true value; the additional @racket[_pat]s must
also match (i.e., @schemeidfont{?} combines a predicate also match (i.e., @racketidfont{?} combines a predicate
application and an @schemeidfont{and} pattern). application and an @racketidfont{and} pattern).
@examples[ @examples[
#:eval match-eval #:eval match-eval
@ -335,10 +336,10 @@ In more detail, patterns match as follows:
[(list (? odd?) ...) 'yes]) [(list (? odd?) ...) 'yes])
]} ]}
@item{@scheme[(#,(schemeidfont "quasiquote") _qp)] --- introduces a @item{@racket[(#,(racketidfont "quasiquote") _qp)] --- introduces a
quasipattern, in which identifiers match symbols. Like the quasipattern, in which identifiers match symbols. Like the
@scheme[quasiquote] expression form, @schemeidfont{unquote} @racket[quasiquote] expression form, @racketidfont{unquote}
and @schemeidfont{unquote-splicing} escape back to normal and @racketidfont{unquote-splicing} escape back to normal
patterns. patterns.
@examples[ @examples[
@ -347,8 +348,8 @@ In more detail, patterns match as follows:
[`(1 ,a ,(? odd? b)) (list a b)]) [`(1 ,a ,(? odd? b)) (list a b)])
]} ]}
@item{@scheme[_derived-pattern] --- matches a pattern defined by a @item{@racket[_derived-pattern] --- matches a pattern defined by a
macro extension via @scheme[define-match-expander].} macro extension via @racket[define-match-expander].}
]} ]}
@ -358,20 +359,20 @@ In more detail, patterns match as follows:
@defform[(match-lambda clause ...)]{ @defform[(match-lambda clause ...)]{
Equivalent to @scheme[(lambda (id) (match id clause ...))]. Equivalent to @racket[(lambda (id) (match id clause ...))].
} }
@defform[(match-lambda* clause ...)]{ @defform[(match-lambda* clause ...)]{
Equivalent to @scheme[(lambda lst (match lst clause ...))]. Equivalent to @racket[(lambda lst (match lst clause ...))].
} }
@defform[(match-let ([pat expr] ...) body ...+)]{ @defform[(match-let ([pat expr] ...) body ...+)]{
Generalizes @scheme[let] to support pattern bindings. Each Generalizes @racket[let] to support pattern bindings. Each
@scheme[expr] is matched against its corresponding @scheme[pat] (the @racket[expr] is matched against its corresponding @racket[pat] (the
match must succeed), and the bindings that @scheme[pat] introduces are match must succeed), and the bindings that @racket[pat] introduces are
visible in the @scheme[body]s. visible in the @racket[body]s.
@examples[ @examples[
#:eval match-eval #:eval match-eval
@ -382,9 +383,9 @@ visible in the @scheme[body]s.
@defform[(match-let* ([pat expr] ...) body ...+)]{ @defform[(match-let* ([pat expr] ...) body ...+)]{
Like @scheme[match-let], but generalizes @scheme[let*], so that the Like @racket[match-let], but generalizes @racket[let*], so that the
bindings of each @scheme[pat] are available in each subsequent bindings of each @racket[pat] are available in each subsequent
@scheme[expr]. @racket[expr].
@examples[ @examples[
#:eval match-eval #:eval match-eval
@ -395,13 +396,13 @@ bindings of each @scheme[pat] are available in each subsequent
@defform[(match-letrec ([pat expr] ...) body ...+)]{ @defform[(match-letrec ([pat expr] ...) body ...+)]{
Like @scheme[match-let], but generalizes @scheme[letrec].} Like @racket[match-let], but generalizes @racket[letrec].}
@defform[(match-define pat expr)]{ @defform[(match-define pat expr)]{
Defines the names bound by @scheme[pat] to the values produced by Defines the names bound by @racket[pat] to the values produced by
matching against the result of @scheme[expr]. matching against the result of @racket[expr].
@examples[ @examples[
#:eval match-eval #:eval match-eval
@ -418,39 +419,41 @@ A predicate for the exception raised by in the case of a match failure.
@; ---------------------------------------- @; ----------------------------------------
@section{Extending @scheme[match]} @section{Extending @racket[match]}
@defform*[((define-match-expander id proc-expr) @defform*[((define-match-expander id proc-expr)
(define-match-expander id proc-expr proc-expr))]{ (define-match-expander id proc-expr proc-expr))]{
Binds @scheme[id] to a @deftech{match expander}. Binds @racket[id] to a @deftech{match expander}.
The first @scheme[proc-expr] subexpression must evaluate to a The first @racket[proc-expr] subexpression must evaluate to a
transformer that produces a @scheme[_pat] for @scheme[match]. transformer that produces a @racket[_pat] for @racket[match].
Whenever @scheme[id] appears as the beginning of a pattern, this Whenever @racket[id] appears as the beginning of a pattern, this
transformer is given, at expansion time, a syntax object transformer is given, at expansion time, a syntax object
corresponding to the entire pattern (including @scheme[id]). The corresponding to the entire pattern (including @racket[id]). The
pattern is the replaced with the result of the transformer. pattern is the replaced with the result of the transformer.
A transformer produced by a second @scheme[proc-expr] subexpression is A transformer produced by a second @racket[proc-expr] subexpression is
used when @scheme[id] is used in an expression context. Using the used when @racket[id] is used in an expression context. Using the
second @scheme[proc-expr], @scheme[id] can be given meaning both second @racket[proc-expr], @racket[id] can be given meaning both
inside and outside patterns.} inside and outside patterns.}
@defparam[match-equality-test comp-proc (any/c any/c . -> . any)]{ @defparam[match-equality-test comp-proc (any/c any/c . -> . any)]{
A parameter that determines the comparison procedure used to check A parameter that determines the comparison procedure used to check
whether multiple uses of an identifier match the ``same'' value. The whether multiple uses of an identifier match the ``same'' value. The
default is @scheme[equal?].} default is @racket[equal?].}
@; ---------------------------------------------------------------------- @; ----------------------------------------------------------------------
@section{Library Extensions} @section{Library Extensions}
@defform[(struct* struct-id ([field pat] ...))]{ @defform[(struct* struct-id ([field pat] ...))]{
Matches an instance of a structure type named @scheme[struct-id], where the field @scheme[field] in the instance matches the corresponding @scheme[pat]. A @scheme[match] pattern form that matches an instance of a structure
type named @racket[struct-id], where the field @racket[field] in the
instance matches the corresponding @racket[pat].
Any field of @scheme[struct-id] may be omitted and they may occur in any order. Any field of @racket[struct-id] may be omitted and they may occur in any order.
@defexamples[ @defexamples[
#:eval match-eval #:eval match-eval

64
collects/scribblings/reference/memory.scrbl
View File

@ -11,28 +11,28 @@ A @deftech{weak box} is similar to a normal box (see
@secref["boxes"]), but when the garbage collector (see @secref["boxes"]), but when the garbage collector (see
@secref["gc-model"]) can prove that the content value of a weak box is @secref["gc-model"]) can prove that the content value of a weak box is
only reachable via weak references, the content of the weak box is only reachable via weak references, the content of the weak box is
replaced with @scheme[#f]. A @defterm{@tech{weak reference}} is a replaced with @racket[#f]. A @defterm{@tech{weak reference}} is a
reference through a weak box, through a key reference in a weak hash reference through a weak box, through a key reference in a weak hash
table (see @secref["hashtables"]), through a value in an ephemeron table (see @secref["hashtables"]), through a value in an ephemeron
where the value can be replaced by @scheme[#f] (see where the value can be replaced by @racket[#f] (see
@secref["ephemerons"]), or through a custodian (see @secref["ephemerons"]), or through a custodian (see
@secref["custodians"]). @secref["custodians"]).
@defproc[(make-weak-box [v any/c]) weak-box?]{ @defproc[(make-weak-box [v any/c]) weak-box?]{
Returns a new weak box that initially contains @scheme[v].} Returns a new weak box that initially contains @racket[v].}
@defproc[(weak-box-value [weak-box weak-box?]) any]{ @defproc[(weak-box-value [weak-box weak-box?]) any]{
Returns the value contained in @scheme[weak-box]. If the garbage Returns the value contained in @racket[weak-box]. If the garbage
collector has proven that the previous content value of collector has proven that the previous content value of
@scheme[weak-box] was reachable only through a weak reference, then @racket[weak-box] was reachable only through a weak reference, then
@scheme[#f] is returned.} @racket[#f] is returned.}
@defproc[(weak-box? [v any/c]) boolean?]{ @defproc[(weak-box? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] is a weak box, @scheme[#f] otherwise.} Returns @racket[#t] if @racket[v] is a weak box, @racket[#f] otherwise.}
@;------------------------------------------------------------------------ @;------------------------------------------------------------------------
@section[#:tag "ephemerons"]{Ephemerons} @section[#:tag "ephemerons"]{Ephemerons}
@ -44,7 +44,7 @@ An @deftech{ephemeron} is similar to a weak box (see
@item{an ephemeron contains a key and a value; the value can be @item{an ephemeron contains a key and a value; the value can be
extracted from the ephemeron, but the value is replaced extracted from the ephemeron, but the value is replaced
by @scheme[#f] when the automatic memory manager can prove that by @racket[#f] when the automatic memory manager can prove that
either the ephemeron or the key is reachable only through weak either the ephemeron or the key is reachable only through weak
references (see @secref["weakbox"]); and} references (see @secref["weakbox"]); and}
@ -65,20 +65,20 @@ key.
@defproc[(make-ephemeron [key any/c][v any/c]) ephemeron?]{ @defproc[(make-ephemeron [key any/c][v any/c]) ephemeron?]{
Returns a new @tech{ephemeron} whose key is @scheme[key] and whose Returns a new @tech{ephemeron} whose key is @racket[key] and whose
value is initially @scheme[v].} value is initially @racket[v].}
@defproc[(ephemeron-value [ephemeron ephemeron?]) any]{ @defproc[(ephemeron-value [ephemeron ephemeron?]) any]{
Returns the value contained in @scheme[ephemeron]. If the garbage Returns the value contained in @racket[ephemeron]. If the garbage
collector has proven that the key for @scheme[ephemeron] is only collector has proven that the key for @racket[ephemeron] is only
weakly reachable, then the result is @scheme[#f].} weakly reachable, then the result is @racket[#f].}
@defproc[(ephemeron? [v any/c]) boolean?]{ @defproc[(ephemeron? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] is an @tech{ephemeron}, @scheme[#f] Returns @racket[#t] if @racket[v] is an @tech{ephemeron}, @racket[#f]
otherwise.} otherwise.}
@;------------------------------------------------------------------------ @;------------------------------------------------------------------------
@ -94,7 +94,7 @@ executors. A @tech{will} is useful for triggering clean-up actions on
data associated with an unreachable value, such as closing a port data associated with an unreachable value, such as closing a port
embedded in an object when the object is no longer used. embedded in an object when the object is no longer used.
Calling the @scheme[will-execute] or @scheme[will-try-execute] Calling the @racket[will-execute] or @racket[will-try-execute]
procedure executes a will that is ready in the specified will procedure executes a will that is ready in the specified will
executor. Wills are not executed automatically, because certain executor. Wills are not executed automatically, because certain
programs need control to avoid race conditions. However, a program can programs need control to avoid race conditions. However, a program can
@ -113,7 +113,7 @@ the values are reachable from each other.
A will executor's register is held non-weakly until after the A will executor's register is held non-weakly until after the
corresponding will procedure is executed. Thus, if the content value corresponding will procedure is executed. Thus, if the content value
of a weak box (see @secref["weakbox"]) is registered with a will of a weak box (see @secref["weakbox"]) is registered with a will
executor, the weak box's content is not changed to @scheme[#f] until executor, the weak box's content is not changed to @racket[#f] until
all wills have been executed for the value and the value has been all wills have been executed for the value and the value has been
proven again reachable through only weak references. proven again reachable through only weak references.
@ -125,34 +125,34 @@ Returns a new will executor with no managed values.}
@defproc[(will-executor? [v any/c]) boolean?]{ @defproc[(will-executor? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] is a will executor, @scheme[#f] Returns @racket[#t] if @racket[v] is a will executor, @racket[#f]
otherwise.} otherwise.}
@defproc[(will-register [executor will-executor?][v any/c][proc (any/c . -> . any)]) @defproc[(will-register [executor will-executor?][v any/c][proc (any/c . -> . any)])
void?]{ void?]{
Registers the value @scheme[v] with the will procedure @scheme[proc] Registers the value @racket[v] with the will procedure @racket[proc]
in the will executor @scheme[executor]. When @scheme[v] is proven in the will executor @racket[executor]. When @racket[v] is proven
unreachable, then the procedure @scheme[proc] is ready to be called unreachable, then the procedure @racket[proc] is ready to be called
with @scheme[v] as its argument via @scheme[will-execute] or with @racket[v] as its argument via @racket[will-execute] or
@scheme[will-try-execute]. The @scheme[proc] argument is strongly @racket[will-try-execute]. The @racket[proc] argument is strongly
referenced until the will procedure is executed.} referenced until the will procedure is executed.}
@defproc[(will-execute [executor will-executor?]) any]{ @defproc[(will-execute [executor will-executor?]) any]{
Invokes the will procedure for a single ``unreachable'' value Invokes the will procedure for a single ``unreachable'' value
registered with the executor @scheme[executable]. The values returned registered with the executor @racket[executable]. The values returned
by the will procedure are the result of the @scheme[will-execute] by the will procedure are the result of the @racket[will-execute]
call. If no will is ready for immediate execution, call. If no will is ready for immediate execution,
@scheme[will-execute] blocks until one is ready.} @racket[will-execute] blocks until one is ready.}
@defproc[(will-try-execute [executor any/c]) any]{ @defproc[(will-try-execute [executor any/c]) any]{
Like @scheme[will-execute] if a will is ready for immediate Like @racket[will-execute] if a will is ready for immediate
execution. Otherwise, @scheme[#f] is returned.} execution. Otherwise, @racket[#f] is returned.}
@;------------------------------------------------------------------------ @;------------------------------------------------------------------------
@section[#:tag "garbagecollection"]{Garbage Collection} @section[#:tag "garbagecollection"]{Garbage Collection}
@ -163,22 +163,22 @@ Forces an immediate garbage collection. Some effectively unreachable
data may remain uncollected, because the collector cannot prove that data may remain uncollected, because the collector cannot prove that
it is unreachable. it is unreachable.
The @scheme[collect-garbage] procedure provides some control over the The @racket[collect-garbage] procedure provides some control over the
timing of collections, but garbage will obviously be collected even if timing of collections, but garbage will obviously be collected even if
this procedure is never called.} this procedure is never called.}
@defproc[(current-memory-use [cust custodian? #f]) exact-nonnegative-integer?]{ @defproc[(current-memory-use [cust custodian? #f]) exact-nonnegative-integer?]{
Returns an estimate of the number of bytes of memory occupied by Returns an estimate of the number of bytes of memory occupied by
reachable data from @scheme[cust]. (The estimate is calculated reachable data from @racket[cust]. (The estimate is calculated
@italic{without} performing an immediate garbage collection; @italic{without} performing an immediate garbage collection;
performing a collection generally decreases the number returned by performing a collection generally decreases the number returned by
@scheme[current-memory-use].) If @scheme[cust] is not provided, the @racket[current-memory-use].) If @racket[cust] is not provided, the
estimate is a total reachable from any custodians. estimate is a total reachable from any custodians.
When PLT Scheme is compiled without support for memory accounting, the When Racket is compiled without support for memory accounting, the
estimate is the same (i.e., all memory) for any individual custodian; estimate is the same (i.e., all memory) for any individual custodian;
see also @scheme[custodian-memory-accounting-available?].} see also @racket[custodian-memory-accounting-available?].}
@defproc[(dump-memory-stats) any]{ @defproc[(dump-memory-stats) any]{

78
collects/scribblings/reference/mpairs.scrbl
View File

@ -1,12 +1,12 @@
#lang scribble/doc #lang scribble/doc
@(require "mz.ss" @(require "mz.ss"
scribble/scheme scribble/racket
(for-label racket/mpair)) (for-label racket/mpair))
@title[#:tag "mpairs"]{Mutable Pairs and Lists} @title[#:tag "mpairs"]{Mutable Pairs and Lists}
A @deftech{mutable pair} is like a pair created by @scheme[cons], but A @deftech{mutable pair} is like a pair created by @racket[cons], but
it supports @scheme[set-mcar!] and @scheme[set-mcdr!] mutation it supports @racket[set-mcar!] and @racket[set-mcdr!] mutation
operations to change the parts of the mutable pair (like traditional Lisp and operations to change the parts of the mutable pair (like traditional Lisp and
Scheme pairs). Scheme pairs).
@ -23,31 +23,31 @@ always better choices.
@; ---------------------------------------- @; ----------------------------------------
@section{Mutable Pair Constructors and Selectors} @section{Mutable Pair Constructors and Selectors}
@defproc[(mpair? [v any/c]) boolean?]{Returns @scheme[#t] if @scheme[v] is @defproc[(mpair? [v any/c]) boolean?]{Returns @racket[#t] if @racket[v] is
a @tech{mutable pair}, @scheme[#f] otherwise.} a @tech{mutable pair}, @racket[#f] otherwise.}
@defproc[(mcons [a any/c] [d any/c]) pair?]{Returns a newly allocated @defproc[(mcons [a any/c] [d any/c]) pair?]{Returns a newly allocated
@tech{mutable pair} whose first @tech{mutable pair} whose first
element is @scheme[a] and second element is @scheme[d].} element is @racket[a] and second element is @racket[d].}
@defproc[(mcar [p mpair?]) any/c]{Returns the first element of the @defproc[(mcar [p mpair?]) any/c]{Returns the first element of the
@tech{mutable pair} @scheme[p].} @tech{mutable pair} @racket[p].}
@defproc[(mcdr [p mpair?]) any/c]{Returns the second element of the @defproc[(mcdr [p mpair?]) any/c]{Returns the second element of the
@tech{mutable pair} @scheme[p].} @tech{mutable pair} @racket[p].}
@defproc[(set-mcar! [p mpair?] [v any/v]) @defproc[(set-mcar! [p mpair?] [v any/v])
void?]{ void?]{
Changes the @tech{mutable pair} @scheme[p] so that its first element is Changes the @tech{mutable pair} @racket[p] so that its first element is
@scheme[v].} @racket[v].}
@defproc[(set-mcdr! [p mpair?] [v any/v]) @defproc[(set-mcdr! [p mpair?] [v any/v])
void?]{ void?]{
Changes the @tech{mutable pair} @scheme[p] so that its second element is Changes the @tech{mutable pair} @racket[p] so that its second element is
@scheme[v].} @racket[v].}
@; ---------------------------------------- @; ----------------------------------------
@section{Mutable List Functions} @section{Mutable List Functions}
@ -58,127 +58,127 @@ For functions described in this section, contracts are not directly
enforced. In particular, when a @tech{mutable list} is expected, enforced. In particular, when a @tech{mutable list} is expected,
supplying any other kind of value (or mutating a value that starts as supplying any other kind of value (or mutating a value that starts as
a @tech{mutable list}) tends to produce an exception from a @tech{mutable list}) tends to produce an exception from
@scheme[mcar] or @scheme[mcdr]. @racket[mcar] or @racket[mcdr].
@defproc[(mlist? [v any/c]) boolean?]{Returns @scheme[#t] if @defproc[(mlist? [v any/c]) boolean?]{Returns @racket[#t] if
@scheme[v] is a @tech{mutable list}: either the empty list, or a @racket[v] is a @tech{mutable list}: either the empty list, or a
@tech{mutable pair} whose second element is a @tech{mutable list}.} @tech{mutable pair} whose second element is a @tech{mutable list}.}
@defproc[(mlist [v any/c] ...) mlist?]{Returns a newly allocated @defproc[(mlist [v any/c] ...) mlist?]{Returns a newly allocated
@tech{mutable list} containing the @scheme[v]s as its elements.} @tech{mutable list} containing the @racket[v]s as its elements.}
@defproc[(list->mlist [lst list?]) mlist?]{ @defproc[(list->mlist [lst list?]) mlist?]{
Returns a newly allocated @tech{mutable list} with the same elements as Returns a newly allocated @tech{mutable list} with the same elements as
@scheme[lst].} @racket[lst].}
@defproc[(mlist->list [mlst mlist?]) list?]{ @defproc[(mlist->list [mlst mlist?]) list?]{
Returns a newly allocated @tech{mutable list} with the same elements as Returns a newly allocated @tech{mutable list} with the same elements as
@scheme[nlst].} @racket[nlst].}
@defproc[(mlength [mlst mlist?]) @defproc[(mlength [mlst mlist?])
exact-nonnegative-integer?]{ exact-nonnegative-integer?]{
Returns the number of elements in @scheme[mlst].} Returns the number of elements in @racket[mlst].}
@defproc[(mlist-ref [mlst mlist?][pos exact-nonnegative-integer?]) @defproc[(mlist-ref [mlst mlist?][pos exact-nonnegative-integer?])
any/c]{ any/c]{
Like @scheme[list-ref], but for @tech{mutable lists}.} Like @racket[list-ref], but for @tech{mutable lists}.}
@defproc[(mlist-tail [mlst mlist?][pos exact-nonnegative-integer?]) @defproc[(mlist-tail [mlst mlist?][pos exact-nonnegative-integer?])
any/c]{ any/c]{
Like @scheme[list-tail], but for @tech{mutable lists}.} Like @racket[list-tail], but for @tech{mutable lists}.}
@defproc*[([(mappend [mlst mlist?] ...) mlist?] @defproc*[([(mappend [mlst mlist?] ...) mlist?]
[(mappend [mlst mlist?] ... [v any/c]) any/c])]{ [(mappend [mlst mlist?] ... [v any/c]) any/c])]{
Like @scheme[append], but for @tech{mutable lists}.} Like @racket[append], but for @tech{mutable lists}.}
@defproc*[([(mappend! [mlst mlist?] ...) mlist?] @defproc*[([(mappend! [mlst mlist?] ...) mlist?]
[(mappend! [mlst mlist?] ... [v any/c]) any/c])]{ [(mappend! [mlst mlist?] ... [v any/c]) any/c])]{
The @scheme[mappend!] procedure appends the given @tech{mutable lists} by mutating The @racket[mappend!] procedure appends the given @tech{mutable lists} by mutating
the tail of each to refer to the next, using @scheme[set-mcdr!]. Empty the tail of each to refer to the next, using @racket[set-mcdr!]. Empty
lists are dropped; in particular, the result of calling lists are dropped; in particular, the result of calling
@scheme[mappend!] with one or more empty lists is the same as the @racket[mappend!] with one or more empty lists is the same as the
result of the call with the empty lists removed from the set of result of the call with the empty lists removed from the set of
arguments.} arguments.}
@defproc[(mreverse [mlst mlist?]) mlist?]{ @defproc[(mreverse [mlst mlist?]) mlist?]{
Like @scheme[reverse], but for @tech{mutable lists}.} Like @racket[reverse], but for @tech{mutable lists}.}
@defproc[(mreverse! [mlst mlist?]) mlist?]{ @defproc[(mreverse! [mlst mlist?]) mlist?]{
Like @scheme[mreverse], but destructively reverses the Like @racket[mreverse], but destructively reverses the
@tech{mutable list} by using @tech{mutable list} by using
all of the mutable pairs in @scheme[mlst] and changing them with all of the mutable pairs in @racket[mlst] and changing them with
@scheme[set-mcdr!].} @racket[set-mcdr!].}
@defproc[(mmap [proc procedure?] [mlst mlist?] ...+) @defproc[(mmap [proc procedure?] [mlst mlist?] ...+)
mlist?]{ mlist?]{
Like @scheme[map], but for @tech{mutable lists}.} Like @racket[map], but for @tech{mutable lists}.}
@defproc[(mfor-each [proc procedure?] [mlst mlist?] ...+) @defproc[(mfor-each [proc procedure?] [mlst mlist?] ...+)
void?]{ void?]{
Like @scheme[for-each], but for @tech{mutable lists}.} Like @racket[for-each], but for @tech{mutable lists}.}
@defproc[(mmember [v any/c] [mlst mlist?]) @defproc[(mmember [v any/c] [mlst mlist?])
(or/c mlist? #f)]{ (or/c mlist? #f)]{
Like @scheme[member], but for @tech{mutable lists}.} Like @racket[member], but for @tech{mutable lists}.}
@defproc[(mmemv [v any/c] [mlst mlist?]) @defproc[(mmemv [v any/c] [mlst mlist?])
(or/c mlist? #f)]{ (or/c mlist? #f)]{
Like @scheme[memv], but for @tech{mutable lists}.} Like @racket[memv], but for @tech{mutable lists}.}
@defproc[(mmemq [v any/c] [mlst mlist?]) @defproc[(mmemq [v any/c] [mlst mlist?])
(or/c list? #f)]{ (or/c list? #f)]{
Like @scheme[memq], but for @tech{mutable lists}.} Like @racket[memq], but for @tech{mutable lists}.}
@defproc[(massoc [v any/c] [mlst (mlistof mpair?)]) @defproc[(massoc [v any/c] [mlst (mlistof mpair?)])
(or/c mpair? #f)]{ (or/c mpair? #f)]{
Like @scheme[assoc], but for @tech{mutable lists} of @tech{mutable pairs}.} Like @racket[assoc], but for @tech{mutable lists} of @tech{mutable pairs}.}
@defproc[(massv [v any/c] [mlst (mlistof mpair?)]) @defproc[(massv [v any/c] [mlst (mlistof mpair?)])
(or/c mpair? #f)]{ (or/c mpair? #f)]{
Like @scheme[assv], but for @tech{mutable lists} of @tech{mutable pairs}.} Like @racket[assv], but for @tech{mutable lists} of @tech{mutable pairs}.}
@defproc[(massq [v any/c] [mlst (mlistof mpair?)]) @defproc[(massq [v any/c] [mlst (mlistof mpair?)])
(or/c mpair? #f)]{ (or/c mpair? #f)]{
Like @scheme[assq], but for @tech{mutable lists} of @tech{mutable pairs}.} Like @racket[assq], but for @tech{mutable lists} of @tech{mutable pairs}.}
@defproc[(mlistof [pred (any/c . -> . any/c)]) @defproc[(mlistof [pred (any/c . -> . any/c)])
(any/c . -> . boolean?)]{ (any/c . -> . boolean?)]{
Returns a procedure that returns @scheme[#t] when given a @tech{mutable list} Returns a procedure that returns @racket[#t] when given a @tech{mutable list}
for which @scheme[pred] returns a true value for all elements.} for which @racket[pred] returns a true value for all elements.}

2
collects/scribblings/reference/mz.ss
View File

@ -58,7 +58,7 @@
" and " " and "
(schememodname racket/init) (schememodname racket/init)
" libraries, which means that they are available when " " libraries, which means that they are available when "
(exec "racket") " is started with no command-line arguments." " the Racket executable is started with no command-line arguments."
" They are not provided by " (schememodname racket/base) " They are not provided by " (schememodname racket/base)
" or " (schememodname racket) "." " or " (schememodname racket) "."
. more)))] . more)))]

302
collects/scribblings/reference/networking.scrbl
View File

@ -21,45 +21,45 @@ For information about TCP in general, see @italic{TCP/IP Illustrated,
tcp-listener?]{ tcp-listener?]{
Creates a ``listening'' server on the local machine at the port number Creates a ``listening'' server on the local machine at the port number
specified by @scheme[port-no]. If @scheme[port-no] is 0 the socket binds specified by @racket[port-no]. If @racket[port-no] is 0 the socket binds
to an ephemeral port, which can be determined by calling to an ephemeral port, which can be determined by calling
@scheme[tcp-addresses]. The @scheme[max-allow-wait] argument @racket[tcp-addresses]. The @racket[max-allow-wait] argument
determines the maximum number of client connections that can be determines the maximum number of client connections that can be
waiting for acceptance. (When @scheme[max-allow-wait] clients are waiting for acceptance. (When @racket[max-allow-wait] clients are
waiting acceptance, no new client connections can be made.) waiting acceptance, no new client connections can be made.)
If the @scheme[reuse?] argument is true, then @scheme[tcp-listen] will If the @racket[reuse?] argument is true, then @racket[tcp-listen] will
create a listener even if the port is involved in a @tt{TIME_WAIT} create a listener even if the port is involved in a @tt{TIME_WAIT}
state. Such a use of @scheme[reuse?] defeats certain guarantees of the state. Such a use of @racket[reuse?] defeats certain guarantees of the
TCP protocol; see Stevens's book for details. Furthermore, on many TCP protocol; see Stevens's book for details. Furthermore, on many
modern platforms, a true value for @scheme[reuse?] overrides modern platforms, a true value for @racket[reuse?] overrides
@tt{TIME_WAIT} only if the listener was previously created with a true @tt{TIME_WAIT} only if the listener was previously created with a true
value for @scheme[reuse?]. value for @racket[reuse?].
If @scheme[hostname] is @scheme[#f] (the default), then the listener If @racket[hostname] is @racket[#f] (the default), then the listener
accepts connections to all of the listening machine's addresses. accepts connections to all of the listening machine's addresses.
Otherwise, the listener accepts connections only at the interface(s) Otherwise, the listener accepts connections only at the interface(s)
associated with the given hostname. For example, providing associated with the given hostname. For example, providing
@scheme["127.0.0.1"] as @scheme[hostname] creates a listener that @racket["127.0.0.1"] as @racket[hostname] creates a listener that
accepts only connections to @scheme["127.0.0.1"] (the loopback accepts only connections to @racket["127.0.0.1"] (the loopback
interface) from the local machine. interface) from the local machine.
(Scheme implements a listener with multiple sockets, if necessary, to (Racket implements a listener with multiple sockets, if necessary, to
accomodate multiple addresses with different protocol families. Under accomodate multiple addresses with different protocol families. Under
Linux, if @scheme[hostname] maps to both IPv4 and IPv6 addresses, then Linux, if @racket[hostname] maps to both IPv4 and IPv6 addresses, then
the behavior depends on whether IPv6 is supported and IPv6 sockets can the behavior depends on whether IPv6 is supported and IPv6 sockets can
be configured to listen to only IPv6 connections: if IPv6 is not be configured to listen to only IPv6 connections: if IPv6 is not
supported or IPv6 sockets are not configurable, then the IPv6 supported or IPv6 sockets are not configurable, then the IPv6
addresses are ignored; otherwise, each IPv6 listener accepts only IPv6 addresses are ignored; otherwise, each IPv6 listener accepts only IPv6
connections.) connections.)
The return value of @scheme[tcp-listen] is a @deftech{TCP The return value of @racket[tcp-listen] is a @deftech{TCP
listener}. This value can be used in future calls to listener}. This value can be used in future calls to
@scheme[tcp-accept], @scheme[tcp-accept-ready?], and @racket[tcp-accept], @racket[tcp-accept-ready?], and
@scheme[tcp-close]. Each new TCP listener value is placed into the @racket[tcp-close]. Each new TCP listener value is placed into the
management of the current custodian (see @secref["custodians"]). management of the current custodian (see @secref["custodians"]).
If the server cannot be started by @scheme[tcp-listen], the If the server cannot be started by @racket[tcp-listen], the
@exnraise[exn:fail:network].} @exnraise[exn:fail:network].}
@ -74,38 +74,38 @@ If the server cannot be started by @scheme[tcp-listen], the
(values input-port? output-port?)]{ (values input-port? output-port?)]{
Attempts to connect as a client to a listening server. The Attempts to connect as a client to a listening server. The
@scheme[hostname] argument is the server host's Internet address name, @racket[hostname] argument is the server host's Internet address name,
and @scheme[port-no] is the port number where the server is listening. and @racket[port-no] is the port number where the server is listening.
(If @scheme[hostname] is associated with multiple addresses, they are (If @racket[hostname] is associated with multiple addresses, they are
tried one at a time until a connection succeeds. The name tried one at a time until a connection succeeds. The name
@scheme["localhost"] generally specifies the local machine.) @racket["localhost"] generally specifies the local machine.)
The optional @scheme[local-hostname] and @scheme[local-port-no] The optional @racket[local-hostname] and @racket[local-port-no]
specify the client's address and port. If both are @scheme[#f] (the specify the client's address and port. If both are @racket[#f] (the
default), the client's address and port are selected automatically. If default), the client's address and port are selected automatically. If
@scheme[local-hostname] is not @scheme[#f], then @racket[local-hostname] is not @racket[#f], then
@scheme[local-port-no] must be non-@scheme[#f]. If @racket[local-port-no] must be non-@racket[#f]. If
@scheme[local-port-no] is non-@scheme[#f] and @scheme[local-hostname] @racket[local-port-no] is non-@racket[#f] and @racket[local-hostname]
is @scheme[#f], then the given port is used but the address is is @racket[#f], then the given port is used but the address is
selected automatically. selected automatically.
Two values are returned by @scheme[tcp-connect]: an input port and an Two values are returned by @racket[tcp-connect]: an input port and an
output port. Data can be received from the server through the input output port. Data can be received from the server through the input
port and sent to the server through the output port. If the server is port and sent to the server through the output port. If the server is
a @exec{mzscheme} process, it can obtain ports to communicate to the a Racket program, it can obtain ports to communicate to the
client with @scheme[tcp-accept]. These ports are placed into the client with @racket[tcp-accept]. These ports are placed into the
management of the current custodian (see @secref["custodians"]). management of the current custodian (see @secref["custodians"]).
Initially, the returned input port is block-buffered, and the returned Initially, the returned input port is block-buffered, and the returned
output port is block-buffered. Change the buffer mode using output port is block-buffered. Change the buffer mode using
@scheme[file-stream-buffer-mode]. @racket[file-stream-buffer-mode].
Both of the returned ports must be closed to terminate the TCP Both of the returned ports must be closed to terminate the TCP
connection. When both ports are still open, closing the output port connection. When both ports are still open, closing the output port
with @scheme[close-output-port] sends a TCP close to the server (which with @racket[close-output-port] sends a TCP close to the server (which
is seen as an end-of-file if the server reads the connection through a is seen as an end-of-file if the server reads the connection through a
port). In contrast, @scheme[tcp-abandon-port] (see below) closes the port). In contrast, @racket[tcp-abandon-port] (see below) closes the
output port, but does not send a TCP close until the input port is output port, but does not send a TCP close until the input port is
also closed. also closed.
@ -117,7 +117,7 @@ response to sending data; in particular, some number of writes on the
still-open end may appear to succeed, though writes will eventually still-open end may appear to succeed, though writes will eventually
produce an error. produce an error.
If a connection cannot be established by @scheme[tcp-connect], the If a connection cannot be established by @racket[tcp-connect], the
@exnraise[exn:fail:network].} @exnraise[exn:fail:network].}
@defproc[(tcp-connect/enable-break [hostname string?] @defproc[(tcp-connect/enable-break [hostname string?]
@ -129,49 +129,49 @@ If a connection cannot be established by @scheme[tcp-connect], the
#f)]) #f)])
(values input-port? output-port?)]{ (values input-port? output-port?)]{
Like @scheme[tcp-connect], but breaking is enabled (see Like @racket[tcp-connect], but breaking is enabled (see
@secref["breakhandler"]) while trying to connect. If breaking is @secref["breakhandler"]) while trying to connect. If breaking is
disabled when @scheme[tcp-connect/enable-break] is called, then either disabled when @racket[tcp-connect/enable-break] is called, then either
ports are returned or the @scheme[exn:break] exception is raised, but ports are returned or the @racket[exn:break] exception is raised, but
not both.} not both.}
@defproc[(tcp-accept [listener tcp-listener?]) @defproc[(tcp-accept [listener tcp-listener?])
(values input-port? output-port?)]{ (values input-port? output-port?)]{
Accepts a client connection for the server associated with Accepts a client connection for the server associated with
@scheme[listener]. If no client connection is waiting on the @racket[listener]. If no client connection is waiting on the
listening port, the call to @scheme[tcp-accept] will block. (See also listening port, the call to @racket[tcp-accept] will block. (See also
@scheme[tcp-accept-ready?].) @racket[tcp-accept-ready?].)
Two values are returned by @scheme[tcp-accept]: an input port and an Two values are returned by @racket[tcp-accept]: an input port and an
output port. Data can be received from the client through the input output port. Data can be received from the client through the input
port and sent to the client through the output port. These ports are port and sent to the client through the output port. These ports are
placed into the management of the current custodian (see placed into the management of the current custodian (see
@secref["custodians"]). @secref["custodians"]).
In terms of buffering and connection states, the ports act the same as In terms of buffering and connection states, the ports act the same as
ports from @scheme[tcp-connect]. ports from @racket[tcp-connect].
If a connection cannot be accepted by @scheme[tcp-accept], or if the If a connection cannot be accepted by @racket[tcp-accept], or if the
listener has been closed, the @exnraise[exn:fail:network].} listener has been closed, the @exnraise[exn:fail:network].}
@defproc[(tcp-accept/enable-break [listener tcp-listener?]) @defproc[(tcp-accept/enable-break [listener tcp-listener?])
(values input-port? output-port?)]{ (values input-port? output-port?)]{
Like @scheme[tcp-accept], but breaking is enabled (see Like @racket[tcp-accept], but breaking is enabled (see
@secref["breakhandler"]) while trying to accept a connection. If @secref["breakhandler"]) while trying to accept a connection. If
breaking is disabled when @scheme[tcp-accept/enable-break] is called, breaking is disabled when @racket[tcp-accept/enable-break] is called,
then either ports are returned or the @scheme[exn:break] exception is then either ports are returned or the @racket[exn:break] exception is
raised, but not both.} raised, but not both.}
@defproc[(tcp-accept-ready? [listener tcp-listener?]) boolean?]{ @defproc[(tcp-accept-ready? [listener tcp-listener?]) boolean?]{
Tests whether an unaccepted client has connected to the server Tests whether an unaccepted client has connected to the server
associated with @scheme[listener]. If a client is associated with @racket[listener]. If a client is
waiting, the return value is @scheme[#t], otherwise it is waiting, the return value is @racket[#t], otherwise it is
@scheme[#f]. A client is accepted with the @scheme[tcp-accept] @racket[#f]. A client is accepted with the @racket[tcp-accept]
procedure, which returns ports for communicating with the client and procedure, which returns ports for communicating with the client and
removes the client from the list of unaccepted clients. removes the client from the list of unaccepted clients.
@ -180,48 +180,48 @@ If the listener has been closed, the @exnraise[exn:fail:network].}
@defproc[(tcp-close [listener tcp-listener?]) void?]{ @defproc[(tcp-close [listener tcp-listener?]) void?]{
Shuts down the server associated with @scheme[listener]. All Shuts down the server associated with @racket[listener]. All
unaccepted clients receive an end-of-file from the server; connections unaccepted clients receive an end-of-file from the server; connections
to accepted clients are unaffected. to accepted clients are unaffected.
If the listener has already been closed, the @exnraise[exn:fail:network]. If the listener has already been closed, the @exnraise[exn:fail:network].
The listener's port number may not become immediately available for The listener's port number may not become immediately available for
new listeners (with the default @scheme[reuse?] argument of new listeners (with the default @racket[reuse?] argument of
@scheme[tcp-listen]). For further information, see Stevens's @racket[tcp-listen]). For further information, see Stevens's
explanation of the @tt{TIME_WAIT} TCP state.} explanation of the @tt{TIME_WAIT} TCP state.}
@defproc[(tcp-listener? [v any/c]) boolean?]{ @defproc[(tcp-listener? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] is a @tech{TCP listener} created by Returns @racket[#t] if @racket[v] is a @tech{TCP listener} created by
@scheme[tcp-listen], @scheme[#f] otherwise.} @racket[tcp-listen], @racket[#f] otherwise.}
@defproc[(tcp-accept-evt [listener tcp-listener?]) evt?]{ @defproc[(tcp-accept-evt [listener tcp-listener?]) evt?]{
Returns a @tech{synchronizable event} (see @secref["sync"]) that is in Returns a @tech{synchronizable event} (see @secref["sync"]) that is in
a blocking state when @scheme[tcp-accept] on @scheme[listener] would a blocking state when @racket[tcp-accept] on @racket[listener] would
block. If the event is chosen in a synchronization, the result is a block. If the event is chosen in a synchronization, the result is a
list of two items, which correspond to the two results of list of two items, which correspond to the two results of
@scheme[tcp-accept]. (If the event is not chosen, no connections are @racket[tcp-accept]. (If the event is not chosen, no connections are
accepted.) The ports are placed into the management of the custodian accepted.) The ports are placed into the management of the custodian
that is the current custodian (see @secref["custodians"]) at the time that that is the current custodian (see @secref["custodians"]) at the time that
@scheme[tcp-accept-evt] is called.} @racket[tcp-accept-evt] is called.}
@defproc[(tcp-abandon-port [tcp-port tcp-port?]) void?]{ @defproc[(tcp-abandon-port [tcp-port tcp-port?]) void?]{
Like @scheme[close-output-port] or @scheme[close-input-port] Like @racket[close-output-port] or @racket[close-input-port]
(depending on whether @scheme[tcp-port] is an input or output port), (depending on whether @racket[tcp-port] is an input or output port),
but if @scheme[tcp-port] is an output port and its associated input but if @racket[tcp-port] is an output port and its associated input
port is not yet closed, then the other end of the TCP connection does port is not yet closed, then the other end of the TCP connection does
not receive a TCP close message until the input port is also not receive a TCP close message until the input port is also
closed. closed.
The TCP protocol does not include a ``no longer reading'' state on The TCP protocol does not include a ``no longer reading'' state on
connections, so @scheme[tcp-abandon-port] is equivalent to connections, so @racket[tcp-abandon-port] is equivalent to
@scheme[close-input-port] on input @tech{TCP ports}.} @racket[close-input-port] on input @tech{TCP ports}.}
@defproc[(tcp-addresses [tcp-port (or/c tcp-port? tcp-listener?)] @defproc[(tcp-addresses [tcp-port (or/c tcp-port? tcp-listener?)]
@ -230,7 +230,7 @@ connections, so @scheme[tcp-abandon-port] is equivalent to
(values string? (integer-in 1 65535) (values string? (integer-in 1 65535)
string? (integer-in 1 65535)))]{ string? (integer-in 1 65535)))]{
Returns two strings when @scheme[port-numbers?] is @scheme[#f] (the Returns two strings when @racket[port-numbers?] is @racket[#f] (the
default). The first string is the Internet address for the local default). The first string is the Internet address for the local
machine a viewed by the given @tech{TCP port}'s connection. (For most machine a viewed by the given @tech{TCP port}'s connection. (For most
machines, the answer corresponds to the current machine's only machines, the answer corresponds to the current machine's only
@ -238,21 +238,21 @@ Internet address, but when a machine serves multiple addresses, the
result is connection-specific.) The second string is the Internet result is connection-specific.) The second string is the Internet
address for the other end of the connection. address for the other end of the connection.
If @scheme[port-numbers?] is true, then four results are returned: a If @racket[port-numbers?] is true, then four results are returned: a
string for the local machine's address, an exact integer between string for the local machine's address, an exact integer between
@scheme[1] and @scheme[65535] for the local machine's port number, a @racket[1] and @racket[65535] for the local machine's port number, a
string for the remote machine's address, and an exact integer between string for the remote machine's address, and an exact integer between
@scheme[1] and @scheme[65535] for the remote machine's port number. @racket[1] and @racket[65535] for the remote machine's port number.
If the given port has been closed, the @exnraise[exn:fail:network].} If the given port has been closed, the @exnraise[exn:fail:network].}
@defproc[(tcp-port? [v any/c]) boolean?]{ @defproc[(tcp-port? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] is a @deftech{TCP port}---which is a Returns @racket[#t] if @racket[v] is a @deftech{TCP port}---which is a
port returned by @scheme[tcp-accept], @scheme[tcp-connect], port returned by @racket[tcp-accept], @racket[tcp-connect],
@scheme[tcp-accept/enable-break], or @racket[tcp-accept/enable-break], or
@scheme[tcp-connect/enable-break]---@scheme[#f] otherwise.} @racket[tcp-connect/enable-break]---@racket[#f] otherwise.}
@;------------------------------------------------------------------------ @;------------------------------------------------------------------------
@section[#:tag "udp"]{UDP} @section[#:tag "udp"]{UDP}
@ -270,17 +270,17 @@ Creates and returns a @deftech{UDP socket} to send and receive
datagrams (broadcasting is allowed). Initially, the socket is not datagrams (broadcasting is allowed). Initially, the socket is not
bound or connected to any address or port. bound or connected to any address or port.
If @scheme[family-hostname] or @scheme[family-port-no] is not If @racket[family-hostname] or @racket[family-port-no] is not
@scheme[#f], then the socket's protocol family is determined from @racket[#f], then the socket's protocol family is determined from
these arguments. The socket is @italic{not} bound to the hostname these arguments. The socket is @italic{not} bound to the hostname
or port number. For example, the arguments might be the hostname or port number. For example, the arguments might be the hostname
and port to which messages will be sent through the socket, which and port to which messages will be sent through the socket, which
ensures that the socket's protocol family is consistent with the ensures that the socket's protocol family is consistent with the
destination. Alternately, the arguments might be the same as for destination. Alternately, the arguments might be the same as for
a future call to @scheme[udp-bind!], which ensures that the a future call to @racket[udp-bind!], which ensures that the
socket's protocol family is consistent with the binding. If socket's protocol family is consistent with the binding. If
neither @scheme[family-hostname] nor @scheme[family-port-no] is neither @racket[family-hostname] nor @racket[family-port-no] is
non-@scheme[#f], then the socket's protocol family is IPv4.} non-@racket[#f], then the socket's protocol family is IPv4.}
@defproc[(udp-bind! [udp-socket udp?] @defproc[(udp-bind! [udp-socket udp?]
[hostname-string (or/c string? #f)] [hostname-string (or/c string? #f)]
@ -288,35 +288,35 @@ non-@scheme[#f], then the socket's protocol family is IPv4.}
(integer-in 0 65535))]) (integer-in 0 65535))])
void?]{ void?]{
Binds an unbound @scheme[udp-socket] to the local port number Binds an unbound @racket[udp-socket] to the local port number
@scheme[port-no]. If @scheme[port-no] is 0 the @scheme[udp-socket] is @racket[port-no]. If @racket[port-no] is 0 the @racket[udp-socket] is
bound to an ephemeral port, which can be determined by calling bound to an ephemeral port, which can be determined by calling
@scheme[udp-addresses]. @racket[udp-addresses].
If @scheme[hostname-string] is @scheme[#f], then the socket If @racket[hostname-string] is @racket[#f], then the socket
accepts connections to all of the listening machine's IP accepts connections to all of the listening machine's IP
addresses at @scheme[port-no]. Otherwise, the socket accepts addresses at @racket[port-no]. Otherwise, the socket accepts
connections only at the IP address associated with the given connections only at the IP address associated with the given
name. For example, providing @scheme["127.0.0.1"] as name. For example, providing @racket["127.0.0.1"] as
@scheme[hostname-string] typically creates a listener that @racket[hostname-string] typically creates a listener that
accepts only connections to @scheme["127.0.0.1"] from the local accepts only connections to @racket["127.0.0.1"] from the local
machine. machine.
A socket cannot receive datagrams until it is bound to a local address A socket cannot receive datagrams until it is bound to a local address
and port. If a socket is not bound before it is used with a sending and port. If a socket is not bound before it is used with a sending
procedure @scheme[udp-send], @scheme[udp-send-to], etc., the sending procedure @racket[udp-send], @racket[udp-send-to], etc., the sending
procedure binds the socket to a random local port. Similarly, if an procedure binds the socket to a random local port. Similarly, if an
event from @scheme[udp-send-evt] or @scheme[udp-send-to-evt] is chosen event from @racket[udp-send-evt] or @racket[udp-send-to-evt] is chosen
for a synchronization (see @secref["sync"]), the socket is bound; if for a synchronization (see @secref["sync"]), the socket is bound; if
the event is not chosen, the socket may or may not become bound. the event is not chosen, the socket may or may not become bound.
The binding of a bound socket cannot be changed, with one exception: The binding of a bound socket cannot be changed, with one exception:
on some systems, if the socket is bound automatically when sending, if on some systems, if the socket is bound automatically when sending, if
the socket is disconnected via @scheme[udp-connect!], and if the the socket is disconnected via @racket[udp-connect!], and if the
socket is later used again in a send, then the later send may change socket is later used again in a send, then the later send may change
the socket's automatic binding. the socket's automatic binding.
If @scheme[udp-socket] is already bound or closed, the If @racket[udp-socket] is already bound or closed, the
@exnraise[exn:fail:network].} @exnraise[exn:fail:network].}
@ -328,21 +328,21 @@ If @scheme[udp-socket] is already bound or closed, the
void?]{ void?]{
Connects the socket to the indicated remote address and port if Connects the socket to the indicated remote address and port if
@scheme[hostname-string] is a string and @scheme[port-no] is an exact @racket[hostname-string] is a string and @racket[port-no] is an exact
integer. integer.
If @scheme[hostname-string] is @scheme[#f], then @scheme[port-no] also If @racket[hostname-string] is @racket[#f], then @racket[port-no] also
must be @scheme[#f], and the port is disconnected (if connected). If must be @racket[#f], and the port is disconnected (if connected). If
one of @scheme[hostname-string] or @scheme[port-no] is @scheme[#f] and one of @racket[hostname-string] or @racket[port-no] is @racket[#f] and
the other is not, the @exnraise[exn:fail:contract]. the other is not, the @exnraise[exn:fail:contract].
A connected socket can be used with @scheme[udp-send] (not A connected socket can be used with @racket[udp-send] (not
@scheme[udp-send-to]), and it accepts datagrams only from the @racket[udp-send-to]), and it accepts datagrams only from the
connected address and port. A socket need not be connected to receive connected address and port. A socket need not be connected to receive
datagrams. A socket can be connected, re-connected, and disconnected datagrams. A socket can be connected, re-connected, and disconnected
any number of times. any number of times.
If @scheme[udp-socket] is closed, the @exnraise[exn:fail:network].} If @racket[udp-socket] is closed, the @exnraise[exn:fail:network].}
@defproc[(udp-send-to [udp-socket udp?] @defproc[(udp-send-to [udp-socket udp?]
@ -354,19 +354,19 @@ If @scheme[udp-socket] is closed, the @exnraise[exn:fail:network].}
[end-pos exact-nonnegative-integer? (bytes-length bstr)]) [end-pos exact-nonnegative-integer? (bytes-length bstr)])
void]{ void]{
Sends @scheme[(subbytes bytes start-pos end-pos)] as a datagram from Sends @racket[(subbytes bytes start-pos end-pos)] as a datagram from
the unconnected @scheme[udp-socket] to the socket at the remote the unconnected @racket[udp-socket] to the socket at the remote
machine @scheme[hostname-address] on the port @scheme[port-no]. The machine @racket[hostname-address] on the port @racket[port-no]. The
@scheme[udp-socket] need not be bound or connected; if it is not @racket[udp-socket] need not be bound or connected; if it is not
bound, @scheme[udp-send-to] binds it to a random local port. If the bound, @racket[udp-send-to] binds it to a random local port. If the
socket's outgoing datagram queue is too full to support the send, socket's outgoing datagram queue is too full to support the send,
@scheme[udp-send-to] blocks until the datagram can be queued. @racket[udp-send-to] blocks until the datagram can be queued.
If @scheme[start-pos] is greater than the length of @scheme[bstr], or If @racket[start-pos] is greater than the length of @racket[bstr], or
if @scheme[end-pos] is less than @scheme[start-pos] or greater than if @racket[end-pos] is less than @racket[start-pos] or greater than
the length of @scheme[bstr], the @exnraise[exn:fail:contract]. the length of @racket[bstr], the @exnraise[exn:fail:contract].
If @scheme[udp-socket] is closed or connected, the If @racket[udp-socket] is closed or connected, the
@exnraise[exn:fail:network].} @exnraise[exn:fail:network].}
@defproc[(udp-send [udp-socket udp?] @defproc[(udp-send [udp-socket udp?]
@ -375,9 +375,9 @@ If @scheme[udp-socket] is closed or connected, the
[end-pos exact-nonnegative-integer? (bytes-length bstr)]) [end-pos exact-nonnegative-integer? (bytes-length bstr)])
void]{ void]{
Like @scheme[udp-send-to], except that @scheme[udp-socket] must be Like @racket[udp-send-to], except that @racket[udp-socket] must be
connected, and the datagram goes to the connection target. If connected, and the datagram goes to the connection target. If
@scheme[udp-socket] is closed or unconnected, the @racket[udp-socket] is closed or unconnected, the
@exnraise[exn:fail:network].} @exnraise[exn:fail:network].}
@defproc[(udp-send-to* [udp-socket udp?] @defproc[(udp-send-to* [udp-socket udp?]
@ -389,9 +389,9 @@ connected, and the datagram goes to the connection target. If
[end-pos exact-nonnegative-integer? (bytes-length bstr)]) [end-pos exact-nonnegative-integer? (bytes-length bstr)])
boolean?]{ boolean?]{
Like @scheme[udp-send-to], but never blocks; if the socket's outgoing Like @racket[udp-send-to], but never blocks; if the socket's outgoing
queue is too full to support the send, @scheme[#f] is returned, queue is too full to support the send, @racket[#f] is returned,
otherwise the datagram is queued and the result is @scheme[#t].} otherwise the datagram is queued and the result is @racket[#t].}
@defproc[(udp-send* [udp-socket udp?] @defproc[(udp-send* [udp-socket udp?]
[bstr bytes?] [bstr bytes?]
@ -399,8 +399,8 @@ otherwise the datagram is queued and the result is @scheme[#t].}
[end-pos exact-nonnegative-integer? (bytes-length bstr)]) [end-pos exact-nonnegative-integer? (bytes-length bstr)])
boolean?]{ boolean?]{
Like @scheme[udp-send], except that (like @scheme[udp-send-to]) it Like @racket[udp-send], except that (like @racket[udp-send-to]) it
never blocks and returns @scheme[#f] or @scheme[#t].} never blocks and returns @racket[#f] or @racket[#t].}
@defproc[(udp-send-to/enable-break [udp-socket udp?] @defproc[(udp-send-to/enable-break [udp-socket udp?]
[hostname string?] [hostname string?]
@ -411,10 +411,10 @@ never blocks and returns @scheme[#f] or @scheme[#t].}
[end-pos exact-nonnegative-integer? (bytes-length bstr)]) [end-pos exact-nonnegative-integer? (bytes-length bstr)])
void]{ void]{
Like @scheme[udp-send-to], but breaking is enabled (see Like @racket[udp-send-to], but breaking is enabled (see
@secref["breakhandler"]) while trying to send the datagram. If @secref["breakhandler"]) while trying to send the datagram. If
breaking is disabled when @scheme[udp-send-to/enable-break] is called, breaking is disabled when @racket[udp-send-to/enable-break] is called,
then either the datagram is sent or the @scheme[exn:break] exception then either the datagram is sent or the @racket[exn:break] exception
is raised, but not both.} is raised, but not both.}
@ -424,8 +424,8 @@ is raised, but not both.}
[end-pos exact-nonnegative-integer? (bytes-length bstr)]) [end-pos exact-nonnegative-integer? (bytes-length bstr)])
void]{ void]{
Like @scheme[udp-send], except that breaks are enabled like Like @racket[udp-send], except that breaks are enabled like
@scheme[udp-send-to/enable-break].} @racket[udp-send-to/enable-break].}
@defproc[(udp-receive! [udp-socket udp?] @defproc[(udp-receive! [udp-socket udp?]
@ -436,24 +436,24 @@ Like @scheme[udp-send], except that breaks are enabled like
string? string?
(integer-in 1 65535))]{ (integer-in 1 65535))]{
Accepts up to @math{@scheme[end-pos]-@scheme[start-pos]} bytes of Accepts up to @math{@racket[end-pos]-@racket[start-pos]} bytes of
@scheme[udp-socket]'s next incoming datagram into @scheme[bstr], @racket[udp-socket]'s next incoming datagram into @racket[bstr],
writing the datagram bytes starting at position @scheme[start-pos] writing the datagram bytes starting at position @racket[start-pos]
within @scheme[bstr]. The @scheme[udp-socket] must be bound to a local within @racket[bstr]. The @racket[udp-socket] must be bound to a local
address and port (but need not be connected). If no incoming datagram address and port (but need not be connected). If no incoming datagram
is immediately available, @scheme[udp-receive!] blocks until one is is immediately available, @racket[udp-receive!] blocks until one is
available. available.
Three values are returned: the number of received bytes (between Three values are returned: the number of received bytes (between
@scheme[0] and @math{@scheme[end-pos]-@scheme[start-pos]}, a hostname @racket[0] and @math{@racket[end-pos]-@racket[start-pos]}, a hostname
string indicating the source address of the datagram, and an integer string indicating the source address of the datagram, and an integer
indicating the source port of the datagram. If the received datagram indicating the source port of the datagram. If the received datagram
is longer than @math{@scheme[end-pos]-@scheme[start-pos]} bytes, the is longer than @math{@racket[end-pos]-@racket[start-pos]} bytes, the
remainder is discarded. remainder is discarded.
If @scheme[start-pos] is greater than the length of @scheme[bstr], or If @racket[start-pos] is greater than the length of @racket[bstr], or
if @scheme[end-pos] is less than @scheme[start-pos] or greater than if @racket[end-pos] is less than @racket[start-pos] or greater than
the length of @scheme[bstr], the @exnraise[exn:fail:contract].} the length of @racket[bstr], the @exnraise[exn:fail:contract].}
@defproc[(udp-receive!* [udp-socket udp?] @defproc[(udp-receive!* [udp-socket udp?]
[bstr (and/c bytes? (not immutable?))] [bstr (and/c bytes? (not immutable?))]
@ -463,8 +463,8 @@ the length of @scheme[bstr], the @exnraise[exn:fail:contract].}
(or/c string? #f) (or/c string? #f)
(or/c (integer-in 1 65535) #f))]{ (or/c (integer-in 1 65535) #f))]{
Like @scheme[udp-receive!], except that it never blocks. If no Like @racket[udp-receive!], except that it never blocks. If no
datagram is available, the three result values are all @scheme[#f].} datagram is available, the three result values are all @racket[#f].}
@defproc[(udp-receive!/enable-break [udp-socket udp?] @defproc[(udp-receive!/enable-break [udp-socket udp?]
[bstr (and/c bytes? (not immutable?))] [bstr (and/c bytes? (not immutable?))]
@ -474,48 +474,48 @@ datagram is available, the three result values are all @scheme[#f].}
string? string?
(integer-in 1 65535))]{ (integer-in 1 65535))]{
Like @scheme[udp-receive!], but breaking is enabled (see Like @racket[udp-receive!], but breaking is enabled (see
@secref["breakhandler"]) while trying to receive the datagram. If @secref["breakhandler"]) while trying to receive the datagram. If
breaking is disabled when @scheme[udp-receive!/enable-break] is breaking is disabled when @racket[udp-receive!/enable-break] is
called, then either a datagram is received or the @scheme[exn:break] called, then either a datagram is received or the @racket[exn:break]
exception is raised, but not both.} exception is raised, but not both.}
@defproc[(udp-close [udp-socket udp?]) void?]{ @defproc[(udp-close [udp-socket udp?]) void?]{
Closes @scheme[udp-socket], discarding unreceived datagrams. If the Closes @racket[udp-socket], discarding unreceived datagrams. If the
socket is already closed, the @exnraise[exn:fail:network].} socket is already closed, the @exnraise[exn:fail:network].}
@defproc[(udp? [v any/c]) boolean?]{ @defproc[(udp? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] is a socket created by Returns @racket[#t] if @racket[v] is a socket created by
@scheme[udp-open-socket], @scheme[#f] otherwise.} @racket[udp-open-socket], @racket[#f] otherwise.}
@defproc[(udp-bound? [udp-socket udp?]) boolean?]{ @defproc[(udp-bound? [udp-socket udp?]) boolean?]{
Returns @scheme[#t] if @scheme[udp-socket] is bound to a local address Returns @racket[#t] if @racket[udp-socket] is bound to a local address
and port, @scheme[#f] otherwise.} and port, @racket[#f] otherwise.}
@defproc[(udp-connected? [udp-socket udp?]) boolean?]{ @defproc[(udp-connected? [udp-socket udp?]) boolean?]{
Returns @scheme[#t] if @scheme[udp-socket] is connected to a remote Returns @racket[#t] if @racket[udp-socket] is connected to a remote
address and port, @scheme[#f] otherwise.} address and port, @racket[#f] otherwise.}
@defproc[(udp-send-ready-evt [udp-socket udp?]) evt?]{ @defproc[(udp-send-ready-evt [udp-socket udp?]) evt?]{
Returns a @tech{synchronizable event} (see @secref["sync"]) that is Returns a @tech{synchronizable event} (see @secref["sync"]) that is
in a blocking state when @scheme[udp-send-to] on @scheme[udp-socket] in a blocking state when @racket[udp-send-to] on @racket[udp-socket]
would block.} would block.}
@defproc[(udp-receive-ready-evt [udp-socket udp?]) evt?]{ @defproc[(udp-receive-ready-evt [udp-socket udp?]) evt?]{
Returns a @tech{synchronizable event} (see @secref["sync"]) that is Returns a @tech{synchronizable event} (see @secref["sync"]) that is
in a blocking state when @scheme[udp-receive!] on @scheme[udp-socket] in a blocking state when @racket[udp-receive!] on @racket[udp-socket]
would block.} would block.}
@defproc[(udp-send-to-evt [udp-socket udp?] @defproc[(udp-send-to-evt [udp-socket udp?]
@ -528,9 +528,9 @@ would block.}
evt?]{ evt?]{
Returns a @tech{synchronizable event}. The event is in a blocking Returns a @tech{synchronizable event}. The event is in a blocking
state when @scheme[udp-send-to] on @scheme[udp-socket] would state when @racket[udp-send-to] on @racket[udp-socket] would
block. Otherwise, if the event is chosen in a synchronization, data is block. Otherwise, if the event is chosen in a synchronization, data is
sent as for @scheme[(udp-send-to udp-socket hostname-address port-no sent as for @racket[(udp-send-to udp-socket hostname-address port-no
bstr start-pos end-pos)], and the synchronization result is bstr start-pos end-pos)], and the synchronization result is
@|void-const|. (No bytes are sent if the event is not chosen.)} @|void-const|. (No bytes are sent if the event is not chosen.)}
@ -542,11 +542,11 @@ bstr start-pos end-pos)], and the synchronization result is
evt?]{ evt?]{
Returns a @tech{synchronizable event}. The event is in a blocking Returns a @tech{synchronizable event}. The event is in a blocking
state when @scheme[udp-send] on @scheme[udp-socket] would state when @racket[udp-send] on @racket[udp-socket] would
block. Otherwise, if the event is chosen in a synchronization, data is block. Otherwise, if the event is chosen in a synchronization, data is
sent as for @scheme[(udp-send-to udp-socket bstr start-pos end-pos)], sent as for @racket[(udp-send-to udp-socket bstr start-pos end-pos)],
and the synchronization result is @|void-const|. (No bytes are sent if and the synchronization result is @|void-const|. (No bytes are sent if
the event is not chosen.) If @scheme[udp-socket] is closed or the event is not chosen.) If @racket[udp-socket] is closed or
unconnected, the @exnraise[exn:fail:network] during a synchronization unconnected, the @exnraise[exn:fail:network] during a synchronization
attempt.} attempt.}
@ -557,12 +557,12 @@ attempt.}
evt?]{ evt?]{
Returns a @tech{synchronizable event}. The event is in a blocking Returns a @tech{synchronizable event}. The event is in a blocking
state when @scheme[udp-receive] on @scheme[udp-socket] would state when @racket[udp-receive] on @racket[udp-socket] would
block. Otherwise, if the event is chosen in a synchronization, data is block. Otherwise, if the event is chosen in a synchronization, data is
received into @scheme[bstr] as for @scheme[(udp-receive! udp-socket received into @racket[bstr] as for @racket[(udp-receive! udp-socket
bytes start-pos end-pos)], and the synchronization result is a list of bytes start-pos end-pos)], and the synchronization result is a list of
three values, corresponding to the three results from three values, corresponding to the three results from
@scheme[udp-receive!]. (No bytes are received and the @scheme[bstr] @racket[udp-receive!]. (No bytes are received and the @racket[bstr]
content is not modified if the event is not chosen.)} content is not modified if the event is not chosen.)}
@defproc[(udp-addresses [udp-port udp?] @defproc[(udp-addresses [udp-port udp?]
@ -571,7 +571,7 @@ content is not modified if the event is not chosen.)}
(values string? (integer-in 1 65535) (values string? (integer-in 1 65535)
string? (integer-in 1 65535)))]{ string? (integer-in 1 65535)))]{
Returns two strings when @scheme[port-numbers?] is @scheme[#f] (the Returns two strings when @racket[port-numbers?] is @racket[#f] (the
default). The first string is the Internet address for the local default). The first string is the Internet address for the local
machine a viewed by the given @tech{UDP socket}'s connection. (For most machine a viewed by the given @tech{UDP socket}'s connection. (For most
machines, the answer corresponds to the current machine's only machines, the answer corresponds to the current machine's only
@ -579,10 +579,10 @@ Internet address, but when a machine serves multiple addresses, the
result is connection-specific.) The second string is the Internet result is connection-specific.) The second string is the Internet
address for the other end of the connection. address for the other end of the connection.
If @scheme[port-numbers?] is true, then four results are returned: a If @racket[port-numbers?] is true, then four results are returned: a
string for the local machine's address, an exact integer between string for the local machine's address, an exact integer between
@scheme[1] and @scheme[65535] for the local machine's port number, a @racket[1] and @racket[65535] for the local machine's port number, a
string for the remote machine's address, and an exact integer between string for the remote machine's address, and an exact integer between
@scheme[1] and @scheme[65535] for the remote machine's port number. @racket[1] and @racket[65535] for the remote machine's port number.
If the given port has been closed, the @exnraise[exn:fail:network].} If the given port has been closed, the @exnraise[exn:fail:network].}

560
collects/scribblings/reference/numbers.scrbl
View File

File diff suppressed because it is too large Load Diff

76
collects/scribblings/reference/package.scrbl
View File

@ -5,7 +5,7 @@
@(define pack-eval (make-base-eval)) @(define pack-eval (make-base-eval))
@interaction-eval[#:eval pack-eval (require racket/package)] @interaction-eval[#:eval pack-eval (require racket/package)]
@title[#:tag "package"]{Limiting Scope: @scheme[define-package], @scheme[open-package], ...} @title[#:tag "package"]{Limiting Scope: @racket[define-package], @racket[open-package], ...}
@note-lib-only[racket/package] @note-lib-only[racket/package]
@ -18,34 +18,34 @@
(code:line #:all-defined-except (id ...))])] (code:line #:all-defined-except (id ...))])]
)]{ )]{
@margin-note{The @scheme[define-package] form is based on the @schemeidfont{module} @margin-note{The @racket[define-package] form is based on the @racketidfont{module}
form of Chez Scheme @cite["Waddell99"].} form of Chez Scheme @cite["Waddell99"].}
The @scheme[define-package] form is similar to @scheme[module], except The @racket[define-package] form is similar to @racket[module], except
that it can appear in any definition context. The @scheme[form]s that it can appear in any definition context. The @racket[form]s
within a @scheme[define-package] form can be definitions or within a @racket[define-package] form can be definitions or
expressions; definitions are not visible outside the expressions; definitions are not visible outside the
@scheme[define-package] form, but @scheme[exports] determines a subset @racket[define-package] form, but @racket[exports] determines a subset
of the bindings that can be made visible outside the package using of the bindings that can be made visible outside the package using
the definition form @scheme[(open-package package-id)]. the definition form @racket[(open-package package-id)].
The @scheme[(id ...)] and @scheme[#:only (id ...)] @scheme[exports] The @racket[(id ...)] and @racket[#:only (id ...)] @racket[exports]
forms are equivalent: exactly the listed @scheme[id]s are forms are equivalent: exactly the listed @racket[id]s are
exported. The @scheme[#:all-defined] form exports all definitions from exported. The @racket[#:all-defined] form exports all definitions from
the package body, and @scheme[#:all-defined-except (id ...)] exports the package body, and @racket[#:all-defined-except (id ...)] exports
all definitions except the listed @scheme[id]s. all definitions except the listed @racket[id]s.
All of the usual definition forms work within a All of the usual definition forms work within a
@scheme[define-package] body, and such definitions are visible to all @racket[define-package] body, and such definitions are visible to all
expressions within the body (and, in particular, the definitions can expressions within the body (and, in particular, the definitions can
refer to each other). However, @scheme[define-package] handles refer to each other). However, @racket[define-package] handles
@scheme[define*], @scheme[define*-syntax], @scheme[define*-values], @racket[define*], @racket[define*-syntax], @racket[define*-values],
@scheme[define*-syntaxes], and @racket[define*-syntaxes], and
@scheme[open*-package] specially: the bindings introduced by those @racket[open*-package] specially: the bindings introduced by those
forms within a @scheme[define-package] body are visible only to forms within a @racket[define-package] body are visible only to
@scheme[form]s that appear later in the body, and they can shadow any @racket[form]s that appear later in the body, and they can shadow any
binding from preceding @scheme[form]s (even if the preceding binding binding from preceding @racket[form]s (even if the preceding binding
did not use one of the special @schemeidfont{*} definition forms). If did not use one of the special @racketidfont{*} definition forms). If
an exported identifier is defined multiple times, the last definition an exported identifier is defined multiple times, the last definition
is the exported one. is the exported one.
@ -70,17 +70,17 @@ little-russian-doll
@defform[(package-begin form ...)]{ @defform[(package-begin form ...)]{
Similar to @scheme[define-package], but it only limits the visible of Similar to @racket[define-package], but it only limits the visible of
definitions without binding a package name. If the last @scheme[form] definitions without binding a package name. If the last @racket[form]
is an expression, then the expression is in @tech{tail position} for is an expression, then the expression is in @tech{tail position} for
the @scheme[package-begin] form, so that its result is the the @racket[package-begin] form, so that its result is the
@scheme[package-begin] result. @racket[package-begin] result.
A @scheme[package-begin] form can be used as an expression, but if it A @racket[package-begin] form can be used as an expression, but if it
is used in a context where definitions are allowed, then the is used in a context where definitions are allowed, then the
definitions are essentially spliced into the enclosing context (though definitions are essentially spliced into the enclosing context (though
the defined bindings remain hidden outside the the defined bindings remain hidden outside the
@scheme[package-begin]). @racket[package-begin]).
@examples[ @examples[
#:eval pack-eval #:eval pack-eval
@ -98,10 +98,10 @@ secret
@defidform[open*-package] @defidform[open*-package]
)]{ )]{
Equivalent to @scheme[define], @scheme[define-values], Equivalent to @racket[define], @racket[define-values],
@scheme[define-syntax], @scheme[define-syntaxes], @racket[define-syntax], @racket[define-syntaxes],
and @scheme[open-package], except within a and @racket[open-package], except within a
@scheme[define-package] or @scheme[package-begin] form, where they @racket[define-package] or @racket[package-begin] form, where they
create bindings that are visible only to later body forms. create bindings that are visible only to later body forms.
@examples[ @examples[
@ -127,19 +127,19 @@ cookies
@defproc[(package-original-identifiers [id identifier?]) (listof identifier?)] @defproc[(package-original-identifiers [id identifier?]) (listof identifier?)]
)]{ )]{
The @scheme[package?], @scheme[package-exported-identifiers], and The @racket[package?], @racket[package-exported-identifiers], and
@scheme[package-original-identifiers] functions are exported @racket[package-original-identifiers] functions are exported
@scheme[for-syntax] by @schememodname[racket/package]. @racket[for-syntax] by @racketmodname[racket/package].
The @scheme[package?] predicate returns @scheme[#t] if @scheme[v] is a The @racket[package?] predicate returns @racket[#t] if @racket[v] is a
package value as obtained by @scheme[syntax-local-value] on an package value as obtained by @racket[syntax-local-value] on an
identifier that is bound to a package. identifier that is bound to a package.
Given such an identifier, the @scheme[package-exported-identifiers] Given such an identifier, the @racket[package-exported-identifiers]
function returns a list of identifiers that corresponding to the function returns a list of identifiers that corresponding to the
bindings that would be introduced by opening the package in the bindings that would be introduced by opening the package in the
lexical context being expanded. The lexical context being expanded. The
@scheme[package-original-identifiers] function returns a parallel list @racket[package-original-identifiers] function returns a parallel list
of identifiers for existing bindings of package's exports.} of identifiers for existing bindings of package's exports.}
@; ---------------------------------------------------------------------- @; ----------------------------------------------------------------------

114
collects/scribblings/reference/promise.scrbl
View File

@ -10,9 +10,6 @@ A @deftech{promise} encapsulates an expression to be evaluated on
demand via @scheme[force]. After a promise has been @scheme[force]d, demand via @scheme[force]. After a promise has been @scheme[force]d,
every later @scheme[force] of the promise produces the same result. every later @scheme[force] of the promise produces the same result.
This module provides this functionality, and extends it to additional
kinds of promises with various evaluation strategies.
@defproc[(promise? [v any/c]) boolean?]{ @defproc[(promise? [v any/c]) boolean?]{
@ -31,18 +28,18 @@ This includes multiple values and exceptions.}
@defform[(lazy body ...+)]{ @defform[(lazy body ...+)]{
Like @scheme[delay], if the last @scheme[body] produces a promise when Like @scheme[delay], if the last @scheme[body] produces a promise when
forced, then this promise is @scheme[force]d too to obtain a value. forced, then this promise is @scheme[force]d, too, to obtain a value.
In other words, this form creates a composable promise, where the In other words, this form creates a composable promise, where the
computation of its body is ``attached'' to the computation of the computation of its body is ``attached'' to the computation of the
following promise and a single @scheme[force] iterates through the following promise, and a single @scheme[force] iterates through the
whole chain, tail-calling each step. whole chain, tail-calling each step.
Note that the last @scheme[body] of this form must produce a single Note that the last @scheme[body] of this form must produce a single
value --- but this value can itself be a @scheme[delay] promise that value, but the value can itself be a @scheme[delay] promise that
returns multiple values. returns multiple values.
This form useful for implementing lazy libraries and languages, where The @scheme[lazy] form useful for implementing lazy libraries and
tail-calls can be wrapped in a promise.} languages, where tail calls can be wrapped in a promise.}
@defproc[(force [v any/c]) any]{ @defproc[(force [v any/c]) any]{
@ -57,9 +54,6 @@ the promise will raise the same exception every time.
If @scheme[v] is @scheme[force]d again before the original call to If @scheme[v] is @scheme[force]d again before the original call to
@scheme[force] returns, then the @exnraise[exn:fail]. @scheme[force] returns, then the @exnraise[exn:fail].
Additional kinds of promises are also forced via @scheme[force]. See
below for further details.
If @scheme[v] is not a promise, then it is returned as the result.} If @scheme[v] is not a promise, then it is returned as the result.}
@ -78,56 +72,74 @@ Returns @scheme[#t] if @scheme[promise] is currently being forced.
@defform[(delay/name body ...+)]{ @defform[(delay/name body ...+)]{
Creates a ``call by name'' promise, that is similar to Creates a ``call-by-name'' promise that is similar to
@scheme[delay]-promises, except that the resulting value is not @scheme[delay]-promises, except that the resulting value is not
cached. It is essentially a thunk, wrapped in a way that cached. This kind of promise is essentially a thunk that is wrapped
@scheme[force] recognizes. Note that if a @scheme[delay/name] promise in a way that @scheme[force] recognizes.
forces itself, no exception is raised.
@; TODO: clarify that the point is that code that is written using
@; `force', can be used with these promises too.
Note that this promise is never considered ``running'' or ``forced'' If a @scheme[delay/name] promise forces itself, no exception is
in the sense of @scheme[promise-running?] and raised, the promise is never considered ``running'' or ``forced'' in
@scheme[promise-forced?].} the sense of @scheme[promise-running?] and @scheme[promise-forced?].}
@defform[(delay/sync body ...+)]{ @defform[(delay/sync body ...+)]{
Conventional promises are not useful when multiple threads attempt to Produces a promise where an attempt to @scheme[force] the promise by a
force them: when a promise is running, any additional threads that thread other than one currently running the promise causes the
@scheme[force] it will get an exception. @scheme[delay/sync] is @scheme[force] to block until a result is available. This kind of
useful for such cases: if a second thread attempts to @scheme[force] promise is also a @tech{synchronizable event} for use with
such a promise, it will get blocked until the computation is done and @racket[sync]; @racket[sync]ing on the promise does not @scheme[force]
an answer is available. If @scheme[force] is used with the promise as it, but merely waits until a value is forced by another thread.
it is forced from the same thread, an exception is raised.
In addition, these promises can be used with @scheme[sync], which If a promise created by @scheme[delay/sync] is forced on a thread that
blocks until it has been forced. Note that using @scheme[sync] this is already running the promise, an exception is raised in the same way
way is passive in the sense that it does not trigger evaluation of the as for promises created with @scheme[delay].}
promise.}
@defform[(delay/thread body ...+)]{ @defform/subs[(delay/thread body/option ...+)
@; TODO: document #:group keyword ([body/option body
(code:line #:group thread-group-expr)])]{
This kind of promise begins the computation immediately, but this Like @scheme[delay/sync], but begins the computation immediately on a
happens on a separate thread. When the computation is done, the result newly created thread. The thread is created under the @tech{thread
is cached as usual. Note that exceptions are caught as usual, and will group} specified by @scheme[thread-group-expr], which defaults to
only be raised when @scheme[force]d. If such a promise is @scheme[(make-thread-group)]. A @racket[#:group] specification can
@scheme[force]d before a value is ready, the calling thread will be appear at most once.
blocked until the computation terminates. These promises can also be
used with @scheme[sync].}
@defform[(delay/idle body ...+)]{ Exceptions raised by the @racket[body]s are caught as usual and raised
@; TODO: document #:wait-for, #:work-while, #:tick, #:use keywords only when the promise is @scheme[force]d.}
Similar to @scheme[delay/thread], but the computation thread gets to @defform/subs[(delay/idle body/option ...+)
work only when the process is otherwise idle, as determined by ([body/option body
@scheme[system-idle-evt], and the work is done in small runtime (code:line #:wait-for wait-evt-expr)
fragements, making it overall not raise total CPU use or hurt (code:line #:work-while while-evt-expr)
responsiveness. If the promise is @scheme[forced] before the (code:line #:tick tick-secs-expr)
computation is done, it will run the rest of the computation immediately (code:line #:use use-ratio-expr)])]{
without slicing the runtime. Using @scheme[sync] on these promises
blocks as is the case with @scheme[delay/sync], and this happens in a Like @scheme[delay/thread], but with the following differences:
passive way too, so the computation continues to work in low-priority.
@itemlist[
@item{the computation does not start until the event produced by
@scheme[wait-evt-expr] is ready, where the default is
@racket[(system-idle-evt)];}
@item{the computation thread gets to work only when the process is
otherwise idle as determined by @scheme[while-evt-expr], which
also defaults to @racket[(system-idle-evt)];}
@item{the thread is allowed to run only periodically: out of every
@scheme[tick-secs-expr] (defaults to @scheme[0.2]) seconds, the
thread is allowed to run @scheme[use-ratio-expr] (defaults to
@scheme[0.12]) of the time proportionally; i.e., the thread
runs for @scheme[(* tick-secs-expr use-ratio-expr)] seconds.}
]
If the promise is @scheme[forced] before the computation is done, it
runs the rest of the computation immediately without waiting on events
or periodically restricting evaluation.
A @racket[#:wait-for], @racket[#:work-while], @racket[#:tick], or
@racket[#:use] specification can appear at most once.
@;{ @;{
TODO: Say something on: TODO: Say something on:

2
collects/scribblings/reference/sandbox.scrbl
View File

@ -515,7 +515,7 @@ inspector (see @racket[sandbox-make-code-inspector]) which prevents
loading of untrusted bytecode files --- the sandbox is set-up to allow loading of untrusted bytecode files --- the sandbox is set-up to allow
loading bytecode from files that are specified with loading bytecode from files that are specified with
@racket['read-bytecode]. This specification is given by default to @racket['read-bytecode]. This specification is given by default to
the PLT collection hierarchy (including user-specific libraries) and the Racket collection hierarchy (including user-specific libraries) and
to libraries that are explicitly specified in an @racket[#:allow-read] to libraries that are explicitly specified in an @racket[#:allow-read]
argument. (Note that this applies for loading bytecode files only, argument. (Note that this applies for loading bytecode files only,
under a lower code inspector it is still impossible to use protected under a lower code inspector it is still impossible to use protected

3
collects/scribblings/reference/startup.scrbl
View File

@ -399,9 +399,6 @@ language specifies run-time configuration by
] ]
The @racketmodname[racket/base] and @racketmodname[racket] languages
do not currently specify a run-time configuration action.
A @racket['configure-runtime] query returns a list of vectors, instead A @racket['configure-runtime] query returns a list of vectors, instead
of directly configuring the environment, so that the indicated modules of directly configuring the environment, so that the indicated modules
to be bundled with a program when creating a stand-alone to be bundled with a program when creating a stand-alone

4
collects/scribblings/reference/syntax.scrbl
View File

@ -538,7 +538,7 @@ corresponds to the default @tech{module name resolver}.
with a @litchar{.}), then @racket[rel-string] names a file within with a @litchar{.}), then @racket[rel-string] names a file within
the @filepath{mzlib} @tech{collection}. A @filepath{.ss} the @filepath{mzlib} @tech{collection}. A @filepath{.ss}
suffix is converted to @filepath{.rkt}. (This convention is for suffix is converted to @filepath{.rkt}. (This convention is for
compatibility with older version of PLT Racket.) compatibility with older version of Racket.)
@examples[ @examples[
(code:comment @#,t{@filepath{tar.rkt} module from the @filepath{mzlib} collection:}) (code:comment @#,t{@filepath{tar.rkt} module from the @filepath{mzlib} collection:})
@ -551,7 +551,7 @@ corresponds to the default @tech{module name resolver}.
subcollection, etc., ending with a file name. No suffix is added subcollection, etc., ending with a file name. No suffix is added
automatically, but a @filepath{.ss} suffix is converted to automatically, but a @filepath{.ss} suffix is converted to
@filepath{.rkt}. (This convention is for compatibility with older @filepath{.rkt}. (This convention is for compatibility with older
version of PLT Racket.) version of Racket.)
@examples[ @examples[
(code:comment @#,t{@filepath{tar.rkt} module from the @filepath{mzlib} collection:}) (code:comment @#,t{@filepath{tar.rkt} module from the @filepath{mzlib} collection:})

8
collects/scribblings/reference/threads.scrbl
View File

@ -3,13 +3,13 @@
@title[#:tag "threads"]{Threads} @title[#:tag "threads"]{Threads}
See @secref["thread-model"] for basic information on the PLT Racket See @secref["thread-model"] for basic information on the Racket
thread model. See also @secref["futures"]. thread model. See also @secref["futures"].
When a thread is created, it is placed into the management of the When a thread is created, it is placed into the management of the
@tech{current custodian} and added to the current thread group (see @tech{current custodian} and added to the current @tech{thread
@secref["threadgroups"]). A thread can have any number of custodian group}. A thread can have any number of custodian managers added
managers added through @racket[thread-resume]. through @racket[thread-resume].
A thread that has not terminated can be garbage collected (see A thread that has not terminated can be garbage collected (see
@secref["gc-model"]) if it is unreachable and suspended or if it is @secref["gc-model"]) if it is unreachable and suspended or if it is

8
collects/scribblings/reference/unsafe.scrbl
View File

@ -12,7 +12,7 @@
@defmodule[racket/unsafe/ops] @defmodule[racket/unsafe/ops]
All fuctions and forms provided by @schememodname[racket/base] and All fuctions and forms provided by @schememodname[racket/base] and
@schememodname[scheme] check their arguments to ensure that the @schememodname[racket] check their arguments to ensure that the
arguments conform to contracts and other constraints. For example, arguments conform to contracts and other constraints. For example,
@scheme[vector-ref] checks its arguments to ensure that the first @scheme[vector-ref] checks its arguments to ensure that the first
argument is a vector, that the second argument is an exact integer, argument is a vector, that the second argument is an exact integer,
@ -26,9 +26,9 @@ faster code. If arguments violate an unsafe function's constraints,
the function's behavior and result is unpredictable, and the entire the function's behavior and result is unpredictable, and the entire
system can crash or become corrupted. system can crash or become corrupted.
All of the exported bindings of @schememodname[scheme] are protected All of the exported bindings of @schememodname[racket/unsafe/ops] are
in the sense of @scheme[protect-out], so access to unsafe operations protected in the sense of @scheme[protect-out], so access to unsafe
can be prevented by adjusting the code inspector (see operations can be prevented by adjusting the code inspector (see
@secref["modprotect"]). @secref["modprotect"]).
@section{Unsafe Numeric Operations} @section{Unsafe Numeric Operations}