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]))
(define (delay/thread thunk group)
(define (run)
(call-with-exception-handler
(lambda (e) (pset! p (make-reraise e)) (kill-thread (current-thread)))
(lambda () (pset! p (call-with-values thunk list)))))
(define p
(make-promise/thread
(make-running-thread
(object-name thunk)
(if group
(parameterize ([current-thread-group (make-thread-group)]) (thread run))
(thread run)))))
p)
(unless (or (not group)
(thread-group? group))
(raise-type-error 'delay/thread "thread group" group))
(let ()
(define (run)
(call-with-exception-handler
(lambda (e) (pset! p (make-reraise e)) (kill-thread (current-thread)))
(lambda () (pset! p (call-with-values thunk list)))))
(define p
(make-promise/thread
(make-running-thread
(object-name thunk)
(if group
(parameterize ([current-thread-group group]) (thread run))
(thread run)))))
p))
(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))))
(define-struct (promise/idle promise/thread) ()
@ -122,54 +126,63 @@
(provide (rename-out [delay/idle* delay/idle]))
(define (delay/idle thunk wait-for work-while tick use*)
(define use (cond [(use* . <= . 0) 0] [(use* . >= . 1) 1] [else use*]))
(define work-time (* tick use))
(define rest-time (- tick work-time))
(define (work)
(call-with-exception-handler
(lambda (e) (pset! p (make-reraise e)) (kill-thread (current-thread)))
(lambda () (pset! p (call-with-values thunk list)))))
(define (run)
;; this thread is dedicated to controlling the worker thread, so it's
;; possible to dedicate messages to signaling a `force'.
(define force-evt (thread-receive-evt))
(sync wait-for force-evt)
(pset! p (make-running-thread (object-name thunk) controller-thread))
(let ([worker (parameterize ([current-thread-group (make-thread-group)])
(thread work))])
(cond
[(and (use . >= . 1) (equal? work-while always-evt))
;; as if it was pre-forced
(thread-wait worker)]
[(use . <= . 0)
;; work only when explicitly forced
(thread-suspend worker)
(sync force-evt)
(thread-wait worker)]
[else
(thread-suspend worker)
(let loop ()
;; rest, then wait for idle time, then resume working
(if (eq? (begin0 (or (sync/timeout rest-time force-evt)
(sync work-while force-evt))
(thread-resume worker))
force-evt)
;; forced during one of these => let it run to completion
(thread-wait worker)
;; not forced
(unless (sync/timeout work-time worker)
(thread-suspend worker)
(loop))))])))
;; 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)
(unless (evt? wait-for)
(raise-type-error 'delay/idle "evt" wait-for))
(unless (evt? work-while)
(raise-type-error 'delay/idle "evt" work-while))
(unless (and (real? tick) (not (negative? tick)))
(raise-type-error 'delay/idle "nonnegative real" tick))
(unless (real? use*)
(raise-type-error 'delay/idle "real" use*))
(let ()
(define use (cond [(use* . <= . 0) 0] [(use* . >= . 1) 1] [else use*]))
(define work-time (* tick use))
(define rest-time (- tick work-time))
(define (work)
(call-with-exception-handler
(lambda (e) (pset! p (make-reraise e)) (kill-thread (current-thread)))
(lambda () (pset! p (call-with-values thunk list)))))
(define (run)
;; this thread is dedicated to controlling the worker thread, so it's
;; possible to dedicate messages to signaling a `force'.
(define force-evt (thread-receive-evt))
(sync wait-for force-evt)
(pset! p (make-running-thread (object-name thunk) controller-thread))
(let ([worker (parameterize ([current-thread-group (make-thread-group)])
(thread work))])
(cond
[(and (use . >= . 1) (equal? work-while always-evt))
;; as if it was pre-forced
(thread-wait worker)]
[(use . <= . 0)
;; work only when explicitly forced
(thread-suspend worker)
(sync force-evt)
(thread-wait worker)]
[else
(thread-suspend worker)
(let loop ()
;; rest, then wait for idle time, then resume working
(if (eq? (begin0 (or (sync/timeout rest-time force-evt)
(sync work-while force-evt))
(thread-resume worker))
force-evt)
;; forced during one of these => let it run to completion
(thread-wait worker)
;; not forced
(unless (sync/timeout work-time worker)
(thread-suspend worker)
(loop))))])))
;; 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*
(let ([kwds (list (cons '#:wait-for #'(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 4)
(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)
(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)
]

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

@ -7,47 +7,47 @@
A @deftech{break} is an asynchronous exception, usually triggered
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,
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
thread has a suspended break, additional breaks are ignored.
Breaks are enabled through the @scheme[break-enabled] parameter-like
procedure, and through the @scheme[parameterize-break] form, which is
analogous to @scheme[parameterize]. The @scheme[break-enabled]
Breaks are enabled through the @racket[break-enabled] parameter-like
procedure, and through the @racket[parameterize-break] form, which is
analogous to @racket[parameterize]. The @racket[break-enabled]
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
incompatible with the tail evaluation of a @scheme[parameterize]
incompatible with the tail evaluation of a @racket[parameterize]
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
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
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.
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,
an error value conversion handler, or a @scheme[pre-thunk] or
@scheme[post-thunk] for a @scheme[dynamic-wind], the call is
@scheme[parameterize-break]ed to disable breaks. Furthermore, breaks
an error value conversion handler, or a @racket[pre-thunk] or
@racket[post-thunk] for a @racket[dynamic-wind], the call is
@racket[parameterize-break]ed to disable breaks. Furthermore, breaks
are disabled during the transitions among handlers related to
exceptions, during the transitions between @scheme[pre-thunk]s and
@scheme[post-thunk]s for @scheme[dynamic-wind], and during other
exceptions, during the transitions between @racket[pre-thunk]s and
@racket[post-thunk]s for @racket[dynamic-wind], and during other
transitions for a continuation jump. For example, if breaks are
disabled when a continuation is invoked, and if breaks are also
disabled in the target continuation, then breaks will remain disabled
until from the time of the invocation until the target continuation
executes unless a relevant @scheme[dynamic-wind] @scheme[pre-thunk] or
@scheme[post-thunk] explicitly enables breaks.
executes unless a relevant @racket[dynamic-wind] @racket[pre-thunk] or
@racket[post-thunk] explicitly enables breaks.
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
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
breaks are enabled when the following code is executed,
@schemeblock[
@racketblock[
(with-handlers ([exn:break? (lambda (x) (void))])
(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
possible that @italic{both} occur: the break may occur after the
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
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.
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
exception is raised, but not both. Scheme therefore supplies
@scheme[semaphore-wait/enable-break] (see @secref["semaphore"]),
exception is raised, but not both. Racket therefore supplies
@racket[semaphore-wait/enable-break] (see @secref["semaphore"]),
which does permit the implementation of such an exclusive guarantee:
@schemeblock[
@racketblock[
(parameterize-break #f
(with-handlers ([exn:break? (lambda (x) (void))])
(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
are disabled, in which case a break exception is propagated to the
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
decremented.
To allow similar implementation patterns over blocking port
operations, MzScheme provides @scheme[read-bytes-avail!/enable-break],
@scheme[write-bytes-avail/enable-break], and other procedures.
operations, Racket provides @racket[read-bytes-avail!/enable-break],
@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?])]{
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
currently enabled, @scheme[#f] otherwise. If @scheme[on?] is supplied
as @scheme[#f], breaks are disabled, and if @scheme[on?] is a true
@racket[on?] is not supplied, the result is @racket[#t] if breaks are
currently enabled, @racket[#f] otherwise. If @racket[on?] is supplied
as @racket[#f], breaks are disabled, and if @racket[on?] is a true
value, breaks are enabled.}
@defform[(parameterize-break boolean-expr body ...+)]{Evaluates
@scheme[boolean-expr] to determine whether breaks are initially
enabled in while evaluating the @scheme[body]s in sequence. The result
of the @scheme[parameter-break] expression is the result of the last
@scheme[expr].
@racket[boolean-expr] to determine whether breaks are initially
enabled in while evaluating the @racket[body]s in sequence. The result
of the @racket[parameter-break] expression is the result of the last
@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
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
threads.}
@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
(effectively a thread cell) that holds the current continuation's
break-enable state.}
@ -127,8 +127,8 @@ break-enable state.}
[break-param break-parameterization?]
[thunk (-> any)])
any]{
Analogous to @scheme[(call-with-parameterization parameterization
thunk)] (see @secref["parameters"]), calls @scheme[thunk] in a
continuation whose break-enabled state is in @scheme[break-param]. The
@scheme[thunk] is @italic{not} called in tail position with respect to
the @scheme[call-with-break-parameterization] call.}
Analogous to @racket[(call-with-parameterization parameterization
thunk)] (see @secref["parameters"]), calls @racket[thunk] in a
continuation whose break-enabled state is in @racket[break-param]. The
@racket[thunk] is @italic{not} called in tail position with respect to
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
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}.}
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}
A @deftech{library} is @scheme[module] declaration for use by multiple
programs. Scheme further groups libraries into @deftech{collections}
that can be easily distributed and easily added to a local MzScheme
A @deftech{library} is @racket[module] declaration for use by multiple
programs. Racket further groups libraries into @deftech{collections}
that can be easily distributed and easily added to a local Racket
installation.
Some collections are distributed via @|PLaneT|. Such collections are
referenced through a @scheme[planet] module path (see
@scheme[require]) and are downloaded by Scheme on demand.
referenced through a @racket[planet] module path (see
@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}
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
path for installed collections can be configured through the
@scheme[current-library-collection-paths] parameter. In all of these
cases, the collections are referenced through @scheme[lib] paths (see
@scheme[require]).
@racket[current-library-collection-paths] parameter. In all of these
cases, the collections are referenced through @racket[lib] paths (see
@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
@filepath{cards.ss} library module from the @filepath{games}
@filepath{cards.rkt} library module from the @filepath{games}
collection's @filepath{cards} subcollection:
@schememod[
scheme
(require (lib "setup/getinfo.ss")
(lib "games/cards/cards.ss"))
@racketmod[
racket
(require (lib "setup/getinfo.rkt")
(lib "games/cards/cards.rkt"))
....
]
This example is more compactly and more commonly written as
@schememod[
scheme
@racketmod[
racket
(require setup/getinfo
games/cards/cards)
....
]
When an identifier @scheme[_id] is used in a @scheme[require] form, it
is converted to @scheme[(lib _rel-string)] where @scheme[_rel-string]
is the string form of @scheme[_id].
When an identifier @racket[_id] is used in a @racket[require] form, it
is converted to @racket[(lib _rel-string)] where @racket[_rel-string]
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
element that names a library file; the path elements are separated by
@litchar{/}. If @scheme[_rel-string] contains no @litchar{/}s, then
then @litchar{/main.ss} is implicitly appended to the path. If
@scheme[_rel-string] contains @litchar{/} but does not end with a file
suffix, then @litchar{.ss} is implicitly appended to the path.
@litchar{/}. If @racket[_rel-string] contains no @litchar{/}s, then
then @litchar{/main.rkt} is implicitly appended to the path. If
@racket[_rel-string] contains @litchar{/} but does not end with a file
suffix, then @litchar{.rkt} is implicitly appended to the path.
The translation of a @scheme[planet] or @scheme[lib] path to a
@scheme[module] declaration is determined by the @tech{module name
resolver}, as specified by the @scheme[current-module-name-resolver]
The translation of a @racket[planet] or @racket[lib] path to a
@racket[module] declaration is determined by the @tech{module name
resolver}, as specified by the @racket[current-module-name-resolver]
parameter.
For the default @tech{module name resolver}, The search path for
collections is determined by the
@scheme[current-library-collection-paths] parameter. The list of paths
in @scheme[current-library-collection-paths] is searched from first to
last to locate the first collection in a @scheme[_rel-string]. To find
@racket[current-library-collection-paths] parameter. The list of paths
in @racket[current-library-collection-paths] is searched from first to
last to locate the first collection in a @racket[_rel-string]. To find
a sub-collection, the enclosing collection is first found; if the
sub-collection is not present in the found enclosing collection, then
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
first instance of the collection.)
The value of the @scheme[current-library-collection-paths] parameter
is initialized in @exec{mzscheme} to the result of
@scheme[(find-library-collection-paths)].
The value of the @racket[current-library-collection-paths] parameter
is initialized in the Racket executable to the result of
@racket[(find-library-collection-paths)].
@defproc[(find-library-collection-paths [pre-extras (listof path-string?) null]
@ -86,37 +86,37 @@ Produces a list of paths as follows:
@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
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
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
executable) and it exists, then it is added to the end of the
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
paths relative to the executable.}
@item{If the @indexed-envvar{PLTCOLLECTS} environment variable is
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
bullets above) is used directly.
Note that under @|AllUnix|, paths are separated by @litchar{:}, and
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
@envvar{PLTCOLLECTS} to @tt{":`pwd`"}, @tt{"`pwd`:"}, or
@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?]{
Returns the path to a directory containing the libraries of the
collection indicated by @scheme[collection]s, where the second
@scheme[collection] (if any) names a sub-collection, and so on. If the
collection indicated by @racket[collection]s, where the second
@racket[collection] (if any) names a sub-collection, and so on. If the
collection is not found, the @exnraise[exn:fail:filesystem].}
@defparam[current-library-collection-paths paths (listof (and/c path? complete-path?))]{
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.}
@defboolparam[use-user-specific-search-paths on?]{
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,
@scheme[find-library-collection-paths] omits the user-specific
collection directory when this parameter's value is @scheme[#f].}
@racket[find-library-collection-paths] omits the user-specific
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}
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
framework for composing synchronization abstractions. In addition, the
@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
@(require scribble/struct
scribble/scheme
scribble/racket
"mz.ss")
@(define (cont n)
@ -12,65 +12,65 @@
See @secref["mark-model"] and @secref["prompt-model"] for
general information about continuation marks.
The list of continuation marks for a key @scheme[_k] and a continuation
@scheme[_C] that extends @cont[0] is defined as follows:
The list of continuation marks for a key @racket[_k] and a continuation
@racket[_C] that extends @cont[0] is defined as follows:
@itemize[
@item{If @scheme[_C] is an empty continuation, then the mark list is
@scheme[null].}
@item{If @racket[_C] is an empty continuation, then the mark list is
@racket[null].}
@item{If @scheme[_C]'s first frame contains a mark @scheme[_m] for @scheme[_k],
then the mark list for @scheme[_C] is @scheme[(cons _m _lst)],
where @scheme[_lst] is the mark list for @scheme[_k] in @cont[0].}
@item{If @racket[_C]'s first frame contains a mark @racket[_m] for @racket[_k],
then the mark list for @racket[_C] is @racket[(cons _m _lst)],
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
@scheme[_k], then the mark list for @scheme[_C] is the mark list for
@item{If @racket[_C]'s first frame does not contain a mark keyed by
@racket[_k], then the mark list for @racket[_C] is the mark list for
@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
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,
it fills the @scheme[continuation-marks] field with the value of
@scheme[(current-continuation-marks)], thus providing a snapshot of
Whenever Racket creates an exception record for a primitive exception,
it fills the @racket[continuation-marks] field with the value of
@racket[(current-continuation-marks)], thus providing a snapshot of
the continuation marks at the time of the exception.
When a continuation procedure returned by
@scheme[call-with-current-continuation] or
@scheme[call-with-composable-continuation] is invoked, it restores the
@racket[call-with-current-continuation] or
@racket[call-with-composable-continuation] is invoked, it restores the
captured continuation, and also restores the marks in the
continuation's frames to the marks that were present when
@scheme[call-with-current-continuation] or
@scheme[call-with-composable-continuation] was invoked.
@racket[call-with-current-continuation] or
@racket[call-with-composable-continuation] was invoked.
@defproc[(continuation-marks [cont (or/c continuation? thread?)]
[prompt-tag prompt-tag? (default-continuation-prompt-tag)])
continuation-mark-set?]{
Returns an opaque value containing the set of continuation marks for
all keys in the continuation @scheme[cont] (or the current
continuation of @scheme[cont] if it is a thread) up to the prompt
tagged by @scheme[prompt-tag]. If @scheme[cont] is an escape
all keys in the continuation @racket[cont] (or the current
continuation of @racket[cont] if it is a thread) up to the prompt
tagged by @racket[prompt-tag]. If @racket[cont] is an escape
continuation (see @secref["prompt-model"]), then the current
continuation must extend @scheme[cont], or the
@exnraise[exn:fail:contract]. If @scheme[cont] was not captured with
respect to @scheme[prompt-tag] and does not include a prompt for
@scheme[prompt-tag], the @exnraise[exn:fail:contract]. If
@scheme[cont] is a dead thread, the result is an empty set of
continuation must extend @racket[cont], or the
@exnraise[exn:fail:contract]. If @racket[cont] was not captured with
respect to @racket[prompt-tag] and does not include a prompt for
@racket[prompt-tag], the @exnraise[exn:fail:contract]. If
@racket[cont] is a dead thread, the result is an empty set of
continuation marks.}
@defproc[(current-continuation-marks [prompt-tag prompt-tag? (default-continuation-prompt-tag)])
continuation-mark-set?]{
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
@schemeblock[
@racketblock[
(call-with-current-continuation
(lambda (k)
(continuation-marks k prompt-tag))
@ -82,11 +82,11 @@ other words, it produces the same value as
[key-v any/c]
[prompt-tag prompt-tag? (default-continuation-prompt-tag)])
list?]{
Returns a newly-created list containing the marks for @scheme[key-v]
in @scheme[mark-set], which is a set of marks returned by
@scheme[current-continuation-marks]. The result list is truncated at
Returns a newly-created list containing the marks for @racket[key-v]
in @racket[mark-set], which is a set of marks returned by
@racket[current-continuation-marks]. The result list is truncated at
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*
[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)])
(listof vector?)]{
Returns a newly-created list containing vectors of marks in
@scheme[mark-set] for the keys in @scheme[key-list], up to
@scheme[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
@racket[mark-set] for the keys in @racket[key-list], up to
@racket[prompt-tag]. The length of each vector in the result list is
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
@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
@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.}
@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)])
any]{
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
@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
@scheme[continuation-mark-set-first].}
@racket[continuation-mark-set-first].}
@defproc[(call-with-immediate-continuation-mark
[key-v any/c]
@ -122,44 +122,44 @@ result can be computed more quickly using
[default-v any/c #f])
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
be replaced if the call to
@scheme[call-with-immediate-continuation-mark] were replaced with a
@scheme[with-continuation-mark] form using @scheme[key-v] as the key
@racket[call-with-immediate-continuation-mark] were replaced with a
@racket[with-continuation-mark] form using @racket[key-v] as the key
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
@scheme[call-with-immediate-continuation-mark] call.
@racket[call-with-immediate-continuation-mark] call.
This function could be implemented with a combination of
@scheme[with-continuation-mark], @scheme[current-continuation-marks],
and @scheme[continuation-mark-set->list], but
@scheme[call-with-immediate-continuation-mark] is implemented more
@racket[with-continuation-mark], @racket[current-continuation-marks],
and @racket[continuation-mark-set->list], but
@racket[call-with-immediate-continuation-mark] is implemented more
efficiently; it inspects only the first frame of the current
continuation.}
@defproc[(continuation-mark-set? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] is a mark set created by
@scheme[continuation-marks] or @scheme[current-continuation-marks],
@scheme[#f] otherwise.}
Returns @racket[#t] if @racket[v] is a mark set created by
@racket[continuation-marks] or @racket[current-continuation-marks],
@racket[#f] otherwise.}
@defproc[(continuation-mark-set->context
[mark-set continuation-mark-set?])
list?]{
Returns a list representing an approximate ``@index["stack
dump"]{@as-index{stack trace}}'' for @scheme[mark-set]'s
continuation. The list contains pairs, where the @scheme[car] of each
pair contains either @scheme[#f] or a symbol for a procedure name, and
the @scheme[cdr] of each pair contains either @scheme[#f] or a
@scheme[srcloc] value for the procedure's source location (see
@secref["linecol"]); the @scheme[car] and @scheme[cdr] are never both
@scheme[#f].
dump"]{@as-index{stack trace}}'' for @racket[mark-set]'s
continuation. The list contains pairs, where the @racket[car] of each
pair contains either @racket[#f] or a symbol for a procedure name, and
the @racket[cdr] of each pair contains either @racket[#f] or a
@racket[srcloc] value for the procedure's source location (see
@secref["linecol"]); the @racket[car] and @racket[cdr] are never both
@racket[#f].
Conceptually, the stack-trace list is the result of
@scheme[continuation-mark-set->list] with @scheme[mark-set] and
Scheme's private key for procedure-call marks. The implementation may
@racket[continuation-mark-set->list] with @racket[mark-set] and
Racket's private key for procedure-call marks. The implementation may
be different, however, and the results may merely approximate the
correct answer. Thus, while the result may contain useful hints to
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
default error display handler (see
@scheme[error-display-handler]) for exceptions other than
@scheme[exn:fail:user] (see @scheme[raise-user-error] in
@racket[error-display-handler]) for exceptions other than
@racket[exn:fail:user] (see @racket[raise-user-error] in
@secref["errorproc"]).}
@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}
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
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
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.
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
constitute an invalid sequence are converted to the character
@schemevalfont{#\uFFFD}. Specifically, bytes 255 and 254 are always converted
to @schemevalfont{#\uFFFD}, bytes in the range 192 to 253 produce
@schemevalfont{#\uFFFD} when they are not followed by bytes that form a valid
@racketvalfont{#\uFFFD}. Specifically, bytes 255 and 254 are always converted
to @racketvalfont{#\uFFFD}, bytes in the range 192 to 253 produce
@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
@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
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.
See @secref["bytestrings"] for procedures that facilitate
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
of characters.
@ -39,58 +39,58 @@ culture-specific interpretation of character sequences. In particular,
a locale determines how strings are ``alphabetized,'' how a lowercase
character is converted to an uppercase character, and how strings are
compared without regard to case. String operations such as
@scheme[string-ci=?] are @italic{not} sensitive to the current locale,
but operations such as @scheme[string-locale-ci=?] (see
@racket[string-ci=?] are @italic{not} sensitive to the current locale,
but operations such as @racket[string-locale-ci=?] (see
@secref["strings"]) produce results consistent with the current
locale.
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
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
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
converted to and from strings using the locale's encoding; filesystem
paths are converted to and from strings (for display purposes) using
the locale's encoding; and, finally, Scheme provides functions such as
@scheme[string->bytes/locale] to specifically invoke a locale-specific
the locale's encoding; and, finally, Racket provides functions such as
@racket[string->bytes/locale] to specifically invoke a locale-specific
encoding.
A Unix user selects a locale by setting environment variables, such as
@envvar{LC_ALL}. Under Windows and Mac OS X, the operating system
provides other mechanisms for setting the locale. Within Scheme, the
current locale can be changed by setting the @scheme[current-locale]
parameter. The locale name within Scheme is a string, and the
provides other mechanisms for setting the locale. Within Racket, the
current locale can be changed by setting the @racket[current-locale]
parameter. The locale name within Racket is a string, and the
available locale names depend on the platform and its configuration,
but the @scheme[""] locale means the current user's default locale;
under Windows and Mac OS X, the encoding for @scheme[""] is always
but the @racket[""] locale means the current user's default locale;
under Windows and Mac OS X, the encoding for @racket[""] is always
UTF-8, and locale-sensitive operations use the operating system's
native interface. (In particular, setting the @envvar{LC_ALL} and
@envvar{LC_CTYPE} environment variables do not affect the locale
@scheme[""] under Mac OS X. Use @scheme[getenv] and
@scheme[current-locale] to explicitly install the
@racket[""] under Mac OS X. Use @racket[getenv] and
@racket[current-locale] to explicitly install the
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
UTF-8 for encoding.
@defparam[current-locale locale (or/c string? #f)]{
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
@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
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
@scheme["C"] locale is also always available; setting the locale to
@scheme["C"] is the same as disabling locale sensitivity with
@scheme[#f] only when string operations are restricted to the first
@racket["C"] locale is also always available; setting the locale to
@racket["C"] is the same as disabling locale sensitivity with
@racket[#f] only when string operations are restricted to the first
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
@secref["regexp"]).}

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

@ -8,23 +8,23 @@
A parameter that determines the current @deftech{evaluation handler}.
The evaluation handler is a procedure that takes a top-level form and
evaluates it, returning the resulting values. The @tech{evaluation
handler} is called by @scheme[eval], @scheme[eval-syntax], the default
@tech{load handler}, and @scheme[read-eval-print-loop] to evaluate a
handler} is called by @racket[eval], @racket[eval-syntax], the default
@tech{load handler}, and @racket[read-eval-print-loop] to evaluate a
top-level form. The handler should evaluate its argument in tail
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
syntax object, or an arbitrary datum.
The default handler converts an arbitrary datum to a syntax object
using @scheme[datum->syntax], and then enriches its @tech{lexical
information} in the same way as @scheme[eval]. (If
@scheme[_top-level-form] is a syntax object, then its @tech{lexical
using @racket[datum->syntax], and then enriches its @tech{lexical
information} in the same way as @racket[eval]. (If
@racket[_top-level-form] is a syntax object, then its @tech{lexical
information} is not enriched.) The default evaluation handler
partially expands the form to splice the body of top-level
@scheme[begin] forms into the top level (see
@scheme[expand-to-top-form]), and then individually compiles and
@racket[begin] forms into the top level (see
@racket[expand-to-top-form]), and then individually compiles and
evaluates each spliced form before continuing to expand, compile, and
evaluate later forms.}
@ -34,42 +34,42 @@ evaluate later forms.}
any]{
Calls the current @tech{evaluation handler} to evaluate
@scheme[top-level-form]. The @tech{evaluation handler} is called in
tail position with respect to the @scheme[eval] call, and
@scheme[parameterize]d to set @scheme[current-namespace] to
@scheme[namespace].
@racket[top-level-form]. The @tech{evaluation handler} is called in
tail position with respect to the @racket[eval] call, and
@racket[parameterize]d to set @racket[current-namespace] to
@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
it is sent to the @tech{evaluation handler}:
@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
@scheme[namespace-syntax-introduce] to the
(@scheme[datum->syntax]-converted) identifier produces an
identifier bound to @scheme[module] in a @tech{phase level}
that corresponds to @scheme[namespace]'s @tech{base phase},
@racket[namespace-syntax-introduce] to the
(@racket[datum->syntax]-converted) identifier produces an
identifier bound to @racket[module] in a @tech{phase level}
that corresponds to @racket[namespace]'s @tech{base phase},
then only that identifier is enriched.}
@item{For any other @scheme[top-level-form],
@scheme[namespace-syntax-introduce] is applied to the entire
@item{For any other @racket[top-level-form],
@racket[namespace-syntax-introduce] is applied to the entire
syntax object.}
]
For interactive evaluation in the style of
@scheme[read-eval-print-loop] and @scheme[load], wrap each expression
with @schemeidfont{#%top-interaction}, which is normally bound to
@scheme[#%top-interaction], before passing it to @scheme[eval].}
@racket[read-eval-print-loop] and @racket[load], wrap each expression
with @racketidfont{#%top-interaction}, which is normally bound to
@racket[#%top-interaction], before passing it to @racket[eval].}
@defproc[(eval-syntax [stx syntax?]
[namespace namespace? (current-namespace)])
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
@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
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}.
A load handler takes two arguments: a path (see
@secref["pathutils"]) and an expected module name. The expected
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
contain a module declaration), or @scheme[#f] for any other load.
in response to a @racket[require] (in which case the file should
contain a module declaration), or @racket[#f] for any other load.
The default load handler reads forms from the file in
@scheme[read-syntax] mode with line-counting enabled for the file
port, unless the path has a @scheme[".zo"] suffix. It also
@scheme[parameterize]s each read to set both
@scheme[read-accept-compiled] and @scheme[read-accept-reader] to
@scheme[#t]. In addition, if @scheme[load-on-demand-enabled] is
@scheme[#t], then @scheme[read-on-demand-source] is effectively set to
the @tech{cleanse}d, absolute form of @scheme[path] during the
@scheme[read-syntax] call. After reading a single form, the form is
@racket[read-syntax] mode with line-counting enabled for the file
port, unless the path has a @racket[".zo"] suffix. It also
@racket[parameterize]s each read to set both
@racket[read-accept-compiled] and @racket[read-accept-reader] to
@racket[#t]. In addition, if @racket[load-on-demand-enabled] is
@racket[#t], then @racket[read-on-demand-source] is effectively set to
the @tech{cleanse}d, absolute form of @racket[path] during the
@racket[read-syntax] call. After reading a single form, the form is
passed to the current @tech{evaluation handler}, wrapping the
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
of the @scheme[load] call.
of the @racket[load] call.
If the second argument to the load handler is a symbol, then:
@itemize[
@item{The @scheme[read-syntax] from the file is additionally
@scheme[parameterize]d as follows (to provide consistent reading
@item{The @racket[read-syntax] from the file is additionally
@racket[parameterize]d as follows (to provide consistent reading
of module source):
@schemeblock[
@racketblock[
(current-readtable #f)
(read-case-sensitive #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)
]}
@item{If the read result is not a @schemeidfont{module} form with the
expected name, or if a second @scheme[read-syntax] does not
@item{If the read result is not a @racketidfont{module} form with the
expected name, or if a second @racket[read-syntax] does not
produce an end-of-file, then the @exnraise[exn:fail] without
evaluating the form that was read from the file.}
@item{The @tech{lexical information} of the initial
@schemeidfont{module} identifier is enriched with a binding for
@scheme[module], so that the form corresponds to a module
@racketidfont{module} identifier is enriched with a binding for
@racket[module], so that the form corresponds to a module
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
@schemeidfont{#%top-interaction}, which is normally bound to
@scheme[#%top-interaction], before passing it to the @tech{evaluation
@racketidfont{#%top-interaction}, which is normally bound to
@racket[#%top-interaction], before passing it to the @tech{evaluation
handler}.
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
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]{
Calls the current @tech{load handler} in tail position. The call is
@scheme[parameterized] to set @scheme[current-load-relative-directory]
to the directory of @scheme[file], which is resolved relative to
the value of @scheme[current-directory].}
@racket[parameterized] to set @racket[current-load-relative-directory]
to the directory of @racket[file], which is resolved relative to
the value of @racket[current-directory].}
@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
@scheme[current-load-relative-directory] instead of the value of
@scheme[current-directory] if the former is not @scheme[#f], otherwise
@scheme[current-directory] is used.}
@racket[current-load-relative-directory] instead of the value of
@racket[current-directory] if the former is not @racket[#f], otherwise
@racket[current-directory] is used.}
@defproc[(load/cd [file path-string?]) any]{
Like @scheme[load], but @scheme[load/cd] sets both
@scheme[current-directory] and
@scheme[current-load-relative-directory] before calling the @tech{load
Like @racket[load], but @racket[load/cd] sets both
@racket[current-directory] and
@racket[current-load-relative-directory] before calling the @tech{load
handler}.}
@defparam[current-load-extension proc (path? (or/c symbol? #f) . -> . any)]{
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}.
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]{
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.}
@defproc[(load-relative-extension [file path-string?]) any]{
Like @scheme[load-exension], but resolves @scheme[file] using
@scheme[current-load-relative-directory] like @scheme[load-relative].}
Like @racket[load-exension], but resolves @racket[file] using
@racket[current-load-relative-directory] like @racket[load-relative].}
@defparam[current-load/use-compiled proc (path? (or/c symbol? #f) . -> . any)]{
A parameter that determines the current @deftech{compiled-load
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
@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
@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}
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
@ -222,39 +222,39 @@ addition, the default @tech{compiled-load handler} checks for
X) files.
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
indicated by the @scheme[use-compiled-file-paths] parameter relative
to @scheme[_file]. The subdirectories are checked in order. A
indicated by the @racket[use-compiled-file-paths] parameter relative
to @racket[_file]. The subdirectories are checked in order. A
@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,
or a @filepath{.so}/@filepath{.dll}/@filepath{.dylib} version of the
file is loaded if it exists within a @filepath{native} subdirectory of
a @scheme[use-compiled-file-paths] directory, in an even deeper
subdirectory as named by @scheme[system-library-subpath]. A compiled
a @racket[use-compiled-file-paths] directory, in an even deeper
subdirectory as named by @racket[system-library-subpath]. A compiled
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,
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
exists, then @filepath{.zo} and
@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}.
While a @filepath{.zo}, @filepath{.so}, @filepath{.dll}, or
@filepath{.dylib} file is loaded, the current @scheme[load-relative]
directory is set to the directory of the original @scheme[_file]. If
@filepath{.dylib} file is loaded, the current @racket[load-relative]
directory is set to the directory of the original @racket[_file]. If
the file to be loaded has the suffix @filepath{.ss} while 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
@scheme[current-module-declare-source] parameter is set to
@scheme[#f].
@racket[current-module-declare-source] parameter is set to
@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
other kind of file is loaded, the @tech{extension-load handler} is
called.}
@ -268,10 +268,10 @@ Calls the current @tech{compiled-load handler} in tail position.}
@defparam[current-load-relative-directory path
(or/c (and/c path-string? complete-path?) #f)]{
A parameter that is set by @scheme[load], @scheme[load-relative],
@scheme[load-extension], @scheme[load-relative-extension], and the
A parameter that is set by @racket[load], @racket[load-relative],
@racket[load-extension], @racket[load-relative-extension], and the
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}.
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?)]{
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
handler} (see @scheme[current-load/use-compiled]).}
handler} (see @racket[current-load/use-compiled]).}
@defproc[(read-eval-print-loop) any]{
Starts a new @deftech{REPL} using the current input, output, and error
ports. The REPL wraps each expression to evaluate with
@schemeidfont{#%top-interaction}, which is normally bound to
@scheme[#%top-interaction], and it wraps each evaluation with a
@racketidfont{#%top-interaction}, which is normally bound to
@racket[#%top-interaction], and it wraps each evaluation with a
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
tag whose handler ignores abort arguments and continues the loop. The
@scheme[read-eval-print-loop] procedure does not return until
@scheme[eof] is read, at which point it returns @|void-const|.
@racket[read-eval-print-loop] procedure does not return until
@racket[eof] is read, at which point it returns @|void-const|.
The @scheme[read-eval-print-loop] procedure can be configured through
the @scheme[current-prompt-read], @scheme[current-eval], and
@scheme[current-print] parameters.}
The @racket[read-eval-print-loop] procedure can be configured through
the @racket[current-prompt-read], @racket[current-eval], and
@racket[current-print] parameters.}
@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 procedure that takes no arguments, displays a prompt string, and
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
@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
result of
@schemeblock[
@racketblock[
(let ([in (current-input-port)])
((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
input port and returns an expression read from the input port.
The default read interaction handler accepts @scheme[_src] and
@scheme[_in] and returns
The default read interaction handler accepts @racket[_src] and
@racket[_in] and returns
@schemeblock[
@racketblock[
(parameterize ([read-accept-reader #t])
(read-syntax _src _in))
]}
@ -340,12 +340,12 @@ The default read interaction handler accepts @scheme[_src] and
@defparam[current-print proc (any/c -> any)]{
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).
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
@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|.}
@ -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
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
@tech{load handler}.
The handler's second argument is @scheme[#t] if the compiled form will
be used only for immediate evaluation, or @scheme[#f] if the compiled
The handler's second argument is @racket[#t] if the compiled form will
be used only for immediate evaluation, or @racket[#f] if the compiled
form may be saved for later use; the default compilation handler is
optimized for the special case of immediate evaluation.
When a compiled form is written to an output port, the written form
starts with @litchar{#~}. These forms are essentially assembly code
for PLT Scheme, and reading such an form produces a compiled form (as
long as the @scheme[read-accept-compiled] parameter is set to
@scheme[#t]).
for Racket, and reading such an form produces a compiled form (as
long as the @racket[read-accept-compiled] parameter is set to
@racket[#t]).
When a compiled form contains syntax object constants, the
@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
unexported or protected bindings from a module. At read time, such
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
@secref["modprotect"]).
A compiled-form object may contain @tech{uninterned} symbols (see
@secref["symbols"]) that were created by @scheme[gensym] or
@scheme[string->uninterned-symbol]. When the compiled object is read
@secref["symbols"]) that were created by @racket[gensym] or
@racket[string->uninterned-symbol]. When the compiled object is read
via @litchar{#~}, each uninterned symbol in the original form is
mapped to a new uninterned symbol, where multiple instances of a
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{#~}.
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,
generate distinct identifiers either with
@scheme[generate-temporaries] or by applying the result of
@scheme[make-syntax-introducer] to an existing identifier; those
@racket[generate-temporaries] or by applying the result of
@racket[make-syntax-introducer] to an existing identifier; those
functions will lead to top-level and module bindings with
@tech{unreadable symbol}ic names.}
@defproc[(compile [top-level-form any/c]) compiled-expression?]{
Like @scheme[eval], but calls the current @tech{compilation handler} in
tail position with @scheme[top-level-form].}
Like @racket[eval], but calls the current @tech{compilation handler} in
tail position with @racket[top-level-form].}
@defproc[(compile-syntax [stx syntax?]) compiled-expression?]{
Like @scheme[eval-syntax], but calls the current @tech{compilation
handler} in tail position with @scheme[stx].}
Like @racket[eval-syntax], but calls the current @tech{compilation
handler} in tail position with @racket[stx].}
@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.}
@ -426,10 +426,10 @@ otherwise.}
A parameter that determines how a module declaration is compiled.
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
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.
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?]{
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
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
previously defined. Otherwise, @scheme[set!] expressions for global
previously defined. Otherwise, @racket[set!] expressions for global
variables are compiled to raise the
@scheme[exn:fail:contract:variable] exception if the global variable
is not defined at the time the @scheme[set!] is performed. Note that
@racket[exn:fail:contract:variable] exception if the global variable
is not defined at the time the @racket[set!] is performed. Note that
this parameter is used when an expression is @italic{compiled}, not
when it is @italic{evaluated}.}
@ -455,22 +455,22 @@ when it is @italic{evaluated}.}
A parameter that determines whether compilation should avoid
function-call inlining and other optimizations that may cause
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.}
@defboolparam[eval-jit-enabled on?]{
A parameter that determines whether the native-code just-in-time
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
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
value).}
@defboolparam[load-on-demand-enabled on?]{
A parameter that determines whether the default @tech{load handler}
sets @scheme[read-on-demand-source]. See @scheme[current-load] for
more information. The default is @scheme[#t], unless it is disabled
sets @racket[read-on-demand-source]. See @racket[current-load] for
more information. The default is @racket[#t], unless it is disabled
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"]
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
ports and threads. Other kinds of objects exist only for their use as
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,
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
event's state.
The following act as events in stand-alone MzScheme. An extension or
embedding application can extend the set of primitive events --- in
particular, an eventspace in MrEd is an event --- and new structure
types can generate events (see @scheme[prop:evt]).
The following act as events in Racket. An extension or embedding
application can extend the set of primitive events --- in particular,
an eventspace in GRacket is an event --- and new structure types can
generate events (see @racket[prop:evt]).
@itemize[
@item{@scheme[_semaphore] --- a semaphore is ready when
@scheme[semaphore-wait] would not block. @ResultItself{semaphore}.}
@item{@racket[_semaphore] --- a semaphore is ready when
@racket[semaphore-wait] would not block. @ResultItself{semaphore}.}
@item{@scheme[_semaphore-peek] --- a semaphore-peek event returned by
@scheme[semaphore-peek-evt] applied to @scheme[_semaphore] is ready
exactly when @scheme[_semaphore] is
@item{@racket[_semaphore-peek] --- a semaphore-peek event returned by
@racket[semaphore-peek-evt] applied to @racket[_semaphore] is ready
exactly when @racket[_semaphore] is
ready. @ResultItself{semaphore-peek}.}
@item{@scheme[_channel] --- a channel returned by
@scheme[make-channel] is ready when @scheme[channel-get] would not
@item{@racket[_channel] --- a channel returned by
@racket[make-channel] is ready when @racket[channel-get] would not
block. The channel's result as an event is the same as the
@scheme[channel-get] result.}
@racket[channel-get] result.}
@item{@scheme[_channel-put] --- an event returned by
@scheme[channel-put-evt] applied to @scheme[_channel] is ready when
@scheme[channel-put] would not block on
@scheme[_channel]. @ResultItself{channel-put}.}
@item{@racket[_channel-put] --- an event returned by
@racket[channel-put-evt] applied to @racket[_channel] is ready when
@racket[channel-put] would not block on
@racket[_channel]. @ResultItself{channel-put}.}
@item{@scheme[_input-port] --- an input port is ready as an event when
@scheme[read-byte] would not block. @ResultItself{input-port}.}
@item{@racket[_input-port] --- an input port is ready as an event when
@racket[read-byte] would not block. @ResultItself{input-port}.}
@item{@scheme[_output-port] --- an output port is ready when
@scheme[write-bytes-avail] would not block or
@item{@racket[_output-port] --- an output port is ready when
@racket[write-bytes-avail] would not block or
when the port contains buffered characters and
@scheme[write-bytes-avail*] can flush part of the buffer (although
@scheme[write-bytes-avail] might block). @ResultItself{output-port}.}
@racket[write-bytes-avail*] can flush part of the buffer (although
@racket[write-bytes-avail] might block). @ResultItself{output-port}.}
@item{@scheme[_progress] --- an event produced by
@scheme[port-progress-evt] applied to @scheme[_input-port] is ready after
any subsequent read from @scheme[_input-port]. @ResultItself{progress}.}
@item{@racket[_progress] --- an event produced by
@racket[port-progress-evt] applied to @racket[_input-port] is ready after
any subsequent read from @racket[_input-port]. @ResultItself{progress}.}
@item{@scheme[_tcp-listener] --- a TCP listener is ready when
@scheme[tcp-accept] would not block. @ResultItself{listener}.}
@item{@racket[_tcp-listener] --- a TCP listener is ready when
@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}.}
@item{@scheme[_thread-dead] --- an event returned by
@scheme[thread-dead-evt] applied to @scheme[thd] is ready when
@scheme[thd] has terminated. @ResultItself{thread-dead}.}
@item{@racket[_thread-dead] --- an event returned by
@racket[thread-dead-evt] applied to @racket[thd] is ready when
@racket[thd] has terminated. @ResultItself{thread-dead}.}
@item{@scheme[_thread-resume] --- an event returned by
@scheme[thread-resume-evt] applied to @scheme[thd] is ready when
@scheme[thd] subsequently resumes execution (if it was not already
running). The event's result is @scheme[thd].}
@item{@racket[_thread-resume] --- an event returned by
@racket[thread-resume-evt] applied to @racket[thd] is ready when
@racket[thd] subsequently resumes execution (if it was not already
running). The event's result is @racket[thd].}
@item{@scheme[_thread-suspend] --- an event returned by
@scheme[thread-suspend-evt] applied to @scheme[thd] is ready when
@scheme[thd] subsequently suspends execution (if it was not already
suspended). The event's result is @scheme[thd].}
@item{@racket[_thread-suspend] --- an event returned by
@racket[thread-suspend-evt] applied to @racket[thd] is ready when
@racket[thd] subsequently suspends execution (if it was not already
suspended). The event's result is @racket[thd].}
@item{@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}.}
@item{@scheme[_subprocess] --- a subprocess is ready when
@scheme[subprocess-wait] would not block.
@item{@racket[_subprocess] --- a subprocess is ready when
@racket[subprocess-wait] would not block.
@ResultItself{subprocess}.}
@item{@scheme[_will-executor] --- a will executor is ready when
@scheme[will-execute] would not block.
@item{@racket[_will-executor] --- a will executor is ready when
@racket[will-execute] would not block.
@ResultItself{will-executor}.}
@item{@scheme[_udp] --- an event returned by @scheme[udp-send-evt] or
@scheme[udp-receive!-evt] is ready when a send or receive on the
@item{@racket[_udp] --- an event returned by @racket[udp-send-evt] or
@racket[udp-receive!-evt] is ready when a send or receive on the
original socket would block, respectively. @ResultItself{udp}.}
@item{@scheme[_log-receiver] --- a @tech{log receiver} as produced by
@scheme[make-log-receiver] is ready when a logged message is
@item{@racket[_log-receiver] --- a @tech{log receiver} as produced by
@racket[make-log-receiver] is ready when a logged message is
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
ready when one or more of the @scheme[_evt]s supplied to
@scheme[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
the chosen @scheme[_evt]'s result.}
@item{@racket[_choice] --- an event returned by @racket[choice-evt] is
ready when one or more of the @racket[_evt]s supplied to
@racket[choice-evt] are ready. If the choice event is chosen, one of
its ready @racket[_evt]s is chosen pseudo-randomly, and the result is
the chosen @racket[_evt]'s result.}
@item{@scheme[_wrap] --- an event returned by @scheme[wrap-evt]
applied to @scheme[_evt] and @scheme[_proc] is ready when @scheme[_evt] is
ready. The event's result is obtained by a call to @scheme[_proc] (with
breaks disabled) on the result of @scheme[evt].}
@item{@racket[_wrap] --- an event returned by @racket[wrap-evt]
applied to @racket[_evt] and @racket[_proc] is ready when @racket[_evt] is
ready. The event's result is obtained by a call to @racket[_proc] (with
breaks disabled) on the result of @racket[evt].}
@item{@scheme[_handle] --- an event returned by @scheme[handle-evt]
applied to @scheme[_evt] and @scheme[_proc] is ready when @scheme[_evt] is
ready. The event's result is obtained by a tail call to @scheme[_proc] on
the result of @scheme[_evt].}
@item{@racket[_handle] --- an event returned by @racket[handle-evt]
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 @racket[_proc] on
the result of @racket[_evt].}
@item{@elemtag["guard-evt"]{@scheme[_guard]} --- an event returned by @scheme[guard-evt] applied
to @scheme[_thunk] generates a new event every time that @scheme[_guard] is
used with @scheme[sync] (or whenever it is part of a choice event
used with @scheme[sync], etc.); the generated event is the result of
calling @scheme[_thunk] when the synchronization begins; if @scheme[_thunk]
returns a non-event, then @scheme[_thunk]'s result is replaced with an
event that is ready and whose result is @scheme[_guard].}
@item{@elemtag["guard-evt"]{@racket[_guard]} --- an event returned by @racket[guard-evt] applied
to @racket[_thunk] generates a new event every time that @racket[_guard] is
used with @racket[sync] (or whenever it is part of a choice event
used with @racket[sync], etc.); the generated event is the result of
calling @racket[_thunk] when the synchronization begins; if @racket[_thunk]
returns a non-event, then @racket[_thunk]'s result is replaced with an
event that is ready and whose result is @racket[_guard].}
@item{@elemtag["nack-guard-evt"]{@scheme[_nack-guard]} --- an event
returned by @scheme[nack-guard-evt] applied to @scheme[_proc]
generates a new event every time that @scheme[_nack-guard] is used
with @scheme[sync] (or whenever it is part of a choice event used
with @scheme[sync], etc.); the generated event is the result of
calling @scheme[_proc] with a NACK (``negative acknowledgment'') event
when the synchronization begins; if @scheme[_proc] returns a
non-event, then @scheme[_proc]'s result is replaced with an event that
is ready and whose result is @scheme[_nack-guard].
@item{@elemtag["nack-guard-evt"]{@racket[_nack-guard]} --- an event
returned by @racket[nack-guard-evt] applied to @racket[_proc]
generates a new event every time that @racket[_nack-guard] is used
with @racket[sync] (or whenever it is part of a choice event used
with @racket[sync], etc.); the generated event is the result of
calling @racket[_proc] with a NACK (``negative acknowledgment'') event
when the synchronization begins; if @racket[_proc] returns a
non-event, then @racket[_proc]'s result is replaced with an event that
is ready and whose result is @racket[_nack-guard].
If the event from @scheme[_proc] is not ultimately chosen as the
unblocked event, then the NACK event supplied to @scheme[_proc]
If the event from @racket[_proc] is not ultimately chosen as the
unblocked event, then the NACK event supplied to @racket[_proc]
becomes ready with a @|void-const| value. This NACK event becomes ready
when the event is abandoned because some other event is chosen,
because the synchronizing thread is dead, or because control escaped
from the call to @scheme[sync] (even if @scheme[_nack-guard]'s @scheme[_proc]
has not yet returned a value). If the event returned by @scheme[_proc] is
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 @racket[_proc] is
chosen, then the NACK event never becomes ready.}
@item{@elemtag["poll-guard-evt"]{@scheme[_poll-guard]} --- an event
returned by @scheme[poll-guard-evt] applied to @scheme[_proc]
generates a new event every time that @scheme[poll-guard] is used
with @scheme[sync] (or whenever it is part of a choice event used
with @scheme[sync], etc.); the generated event is the result of
calling @scheme[_proc] with a boolean: @scheme[#t] if the event will
be used for a poll, @scheme[#f] for a blocking synchronization.
@item{@elemtag["poll-guard-evt"]{@racket[_poll-guard]} --- an event
returned by @racket[poll-guard-evt] applied to @racket[_proc]
generates a new event every time that @racket[poll-guard] is used
with @racket[sync] (or whenever it is part of a choice event used
with @racket[sync], etc.); the generated event is the result of
calling @racket[_proc] with a boolean: @racket[#t] if the event will
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
event produces a result, the event will certainly be chosen for its
result.}
@item{@scheme[_struct] --- a structure whose type has the
@scheme[prop:evt] property identifies/generates an event through the
@item{@racket[_struct] --- a structure whose type has the
@racket[prop:evt] property identifies/generates an event through the
property.}
@item{@scheme[always-evt] --- a constant event that is always
ready. @ResultItself{@scheme[always-evt]}.}
@item{@racket[always-evt] --- a constant event that is always
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
produced by @scheme[system-idle-evt] is ready when, if this event
were replaced by @scheme[never-evt], no thread in the system would
@item{@elemtag["system-idle-evt"]{@racket[_idle]} --- an event
produced by @racket[system-idle-evt] is ready when, if this event
were replaced by @racket[never-evt], no thread in the system would
be available to run. In other words, all threads must be suspended
or blocked on events with timeouts that have not yet expired. The
event's result is @|void-const|.}
@ -187,20 +187,20 @@ types can generate events (see @scheme[prop:evt]).
@defproc[(evt? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] is a @tech{synchronizable event},
@scheme[#f] otherwise.}
Returns @racket[#t] if @racket[v] is a @tech{synchronizable event},
@racket[#f] otherwise.}
@defproc[(sync [evt evt?] ...+) any]{
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
result} (often @scheme[evt] itself) is returned. If multiple
@scheme[evt]s are ready, one of the @scheme[evt]s is chosen
When at least one @racket[evt] is ready, its @tech{synchronization
result} (often @racket[evt] itself) is returned. If multiple
@racket[evt]s are ready, one of the @racket[evt]s is chosen
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.}
@ -208,23 +208,23 @@ random-number generator that controls this choice.}
[evt evt?] ...+)
any]{
Like @scheme[sync], but returns @scheme[#f] if @scheme[timeout-secs]
is not @scheme[#f] and if @scheme[timeout-secs] seconds pass without a
Like @racket[sync], but returns @racket[#f] if @racket[timeout-secs]
is not @racket[#f] and if @racket[timeout-secs] seconds pass without a
successful synchronization.
If @scheme[timeout-secs] is @scheme[0], each @scheme[evt] is checked
at least once, so a @scheme[timeout-secs] value of @scheme[0] can be
If @racket[timeout-secs] is @racket[0], each @racket[evt] is checked
at least once, so a @racket[timeout-secs] value of @racket[0] can be
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]{
Like @scheme[sync], but breaking is enabled (see
@secref["breakhandler"]) while waiting on the @scheme[evt]s. If
breaking is disabled when @scheme[sync/enable-break] is called, then
either all @scheme[evt]s remain unchosen or the @scheme[exn:break]
Like @racket[sync], but breaking is enabled (see
@secref["breakhandler"]) while waiting on the @racket[evt]s. If
breaking is disabled when @racket[sync/enable-break] is called, then
either all @racket[evt]s remain unchosen or the @racket[exn:break]
exception is raised, but not both.}
@ -232,34 +232,34 @@ exception is raised, but not both.}
[evt evt?] ...+)
any]{
Like @scheme[sync/enable-break], but with a timeout in seconds (or
@scheme[#f]), as for @scheme[sync/timeout].}
Like @racket[sync/enable-break], but with a timeout in seconds (or
@racket[#f]), as for @racket[sync/timeout].}
@defproc[(choice-evt [evt evt?] ...) evt?]{
Creates and returns a single event that combines the
@scheme[evt]s. Supplying the result to @scheme[sync] is the same as
supplying each @scheme[evt] to the same call.}
@racket[evt]s. Supplying the result to @racket[sync] is the same as
supplying each @racket[evt] to the same call.}
@defproc[(wrap-evt [evt (and/c evt? (not/c handle-evt?))]
[wrap (any/c . -> . any)])
evt?]{
Creates an event that is in a ready when @scheme[evt] is ready, but
whose result is determined by applying @scheme[wrap] to the result of
@scheme[evt]. The call to @scheme[wrap] is
@scheme[parameterize-break]ed to disable breaks initially. The
@scheme[evt] cannot be an event created by @scheme[handle-evt] or any
combination of @scheme[choice-evt] involving an event from
@scheme[handle-evt].}
Creates an event that is in a ready when @racket[evt] is ready, but
whose result is determined by applying @racket[wrap] to the result of
@racket[evt]. The call to @racket[wrap] is
@racket[parameterize-break]ed to disable breaks initially. The
@racket[evt] cannot be an event created by @racket[handle-evt] or any
combination of @racket[choice-evt] involving an event from
@racket[handle-evt].}
@defproc[(handle-evt [evt (and/c evt? (not/c handle-evt?))]
[handle (any/c . -> . any)])
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
breaks explicitly disabled.}
@ -293,27 +293,27 @@ itself as its result.}
@defproc[(system-idle-evt) evt?]{Returns an event that is ready when
the system is otherwise idle; see @elemref["system-idle-evt"]{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]{
Returns a synchronizable event that is not ready when
@scheme[(current-inexact-milliseconds)] would return a value that is
less than @scheme[msecs], and it is ready when
@scheme[(current-inexact-milliseconds)] would return a value that is
more than @scheme[msecs].}
@racket[(current-inexact-milliseconds)] would return a value that is
less than @racket[msecs], and it is ready when
@racket[(current-inexact-milliseconds)] would return a value that is
more than @racket[msecs].}
@defproc[(handle-evt? [evt evt?]) boolean?]{
Returns @scheme[#t] if @scheme[evt] was created by @scheme[handle-evt]
or by @scheme[choice-evt] applied to another event for which
@scheme[handle-evt?] produces @scheme[#t]. Such events are illegal as
an argument to @scheme[handle-evt] or @scheme[wrap-evt], because they
cannot be wrapped further. For any other event, @scheme[handle-evt?]
produces @scheme[#f], and the event is a legal argument to
@scheme[handle-evt] or @scheme[wrap-evt] for further wrapping.}
Returns @racket[#t] if @racket[evt] was created by @racket[handle-evt]
or by @racket[choice-evt] applied to another event for which
@racket[handle-evt?] produces @racket[#t]. Such events are illegal as
an argument to @racket[handle-evt] or @racket[wrap-evt], because they
cannot be wrapped further. For any other event, @racket[handle-evt?]
produces @racket[#f], and the event is a legal argument to
@racket[handle-evt] or @racket[wrap-evt] for further wrapping.}
@;------------------------------------------------------------------------
@defthing[prop:evt struct-type-property?]{
@ -324,16 +324,16 @@ A @tech{structure type property} that identifies structure types whose
@itemize[
@item{An event @scheme[_evt]: In this case, using the structure as an
event is equivalent to using @scheme[_evt].}
@item{An event @racket[_evt]: In this case, using the structure as an
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
by @scheme[guard-evt], except that the would-be guard
procedure @scheme[_proc] receives the structure as an argument, instead
by @racket[guard-evt], except that the would-be guard
procedure @racket[_proc] receives the structure as an argument, instead
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
(exclusive, not counting supertype fields): The integer identifies a
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
@scheme[prop:output-port] property are also synchronizable by virtue
Instances of a structure type with the @racket[prop:input-port] or
@racket[prop:output-port] property are also synchronizable by virtue
of being a port. If the structure type has more than one of
@scheme[prop:evt], @scheme[prop:input-port], and
@scheme[prop:output-port], then the @scheme[prop:evt] value (if any)
@racket[prop:evt], @racket[prop:input-port], and
@racket[prop:output-port], then the @racket[prop:evt] value (if any)
takes precedence for determing the instance's behavior as an event,
and the @scheme[prop:input-port] property takes precedence over
@scheme[prop:output-port] for synchronization.
and the @racket[prop:input-port] property takes precedence over
@racket[prop:output-port] for synchronization.
@examples[
(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?]{
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]{
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
returned.}
@ -13,11 +13,11 @@ returned.}
@defparam[exit-handler proc (any/c . -> . any)]{
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
takes any argument and shuts down the OS-level Scheme process. The
The default @tech{exit handler} in the Racket executable
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
between @scheme[1] and @scheme[255] (which normally means
``failure''); otherwise, the exit code is @scheme[0], (which normally
between @racket[1] and @racket[255] (which normally means
``failure''); otherwise, the exit code is @racket[0], (which normally
means ``success'').}

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

@ -5,42 +5,42 @@
@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
@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
handler} for a primitive error is always an instance of the
@scheme[exn] structure type. Every @scheme[exn] structure value has a
@scheme[message] field that is a string, the primitive error message.
@racket[exn] structure type. Every @racket[exn] structure value has a
@racket[message] field that is a string, the primitive error message.
The default exception handler recognizes exception values with the
@scheme[exn?] predicate and passes the error message to the current
@tech{error display handler} (see @scheme[error-display-handler]).
@racket[exn?] predicate and passes the error message to the current
@tech{error display handler} (see @racket[error-display-handler]).
Primitive procedures that accept a procedure argument with a
particular required arity (e.g., @scheme[call-with-input-file],
@scheme[call/cc]) check the argument's arity immediately, raising
@scheme[exn:fail:contract] if the arity is incorrect.
particular required arity (e.g., @racket[call-with-input-file],
@racket[call/cc]) check the argument's arity immediately, raising
@racket[exn:fail:contract] if the arity is incorrect.
@;------------------------------------------------------------------------
@section[#:tag "errorproc"]{Raising Exceptions}
@defproc[(raise [v any/c][barrier? any/c #t]) any]{
Raises an exception, where @scheme[v] represents the exception being
raised. The @scheme[v] argument can be anything; it is passed to the
Raises an exception, where @racket[v] represents the exception being
raised. The @racket[v] argument can be anything; it is passed to the
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
multiple returns/escapes are impossible. All exceptions raised by
@schememodname[scheme] functions effectively use @scheme[raise] with a
@scheme[#t] value for @scheme[barrier?].
@racketmodname[racket] functions effectively use @racket[raise] with a
@racket[#t] value for @racket[barrier?].
Breaks are disabled from the time the exception is raised until the
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.
@examples[
@ -60,73 +60,73 @@ exception handler obtains control, and the handler itself is
[(error [msg 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
ways:
@itemize[
@item{@scheme[(error sym)] creates a message string by concatenating
@scheme["error: "] with the string form of @scheme[sym].}
@item{@racket[(error sym)] creates a message string by concatenating
@racket["error: "] with the string form of @racket[sym].}
@item{@scheme[(error msg v ...)] creates a message string by
concatenating @scheme[msg] with string versions of the @scheme[v]s
@item{@racket[(error msg v ...)] creates a message string by
concatenating @racket[msg] with string versions of the @racket[v]s
(as produced by the current error value conversion handler; see
@scheme[error-value->string-handler]). A space is inserted before
each @scheme[v].}
@racket[error-value->string-handler]). A space is inserted before
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
@schemeblock[
@racketblock[
(format (string-append "~s: " frmat) src v ...)
]}
]
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[
(error 'failed)
(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]
[(raise-user-error [msg string?][v any/c] ...) any]
[(raise-user-error [src symbol?][format string?][v any/c] ...) any])]{
Like @scheme[error], but constructs an exception with
@scheme[make-exn:fail:user] instead of @scheme[make-exn:fail]. The
Like @racket[error], but constructs an exception with
@racket[make-exn:fail:user] instead of @racket[make-exn:fail]. The
default @tech{error display handler} does not show a ``stack trace'' for
@scheme[exn:fail:user] exceptions (see @secref["contmarks"]), so
@scheme[raise-user-error] should be used for errors that are intended
@racket[exn:fail:user] exceptions (see @secref["contmarks"]), so
@racket[raise-user-error] should be used for errors that are intended
for end users.
@examples[
(raise-user-error 'failed)
(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]
[(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
an exception. The @scheme[name] argument is used as the source
procedure's name in the error message. The @scheme[expected] argument
Creates an @racket[exn:fail:contract] value and @racket[raise]s it as
an exception. The @racket[name] argument is used as the source
procedure's name in the error message. The @racket[expected] argument
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.
In the second form, the bad argument is indicated by an index
@scheme[bad-pos] (counting from @math{0}), and all of the original
arguments @scheme[v] are provided (in order). The resulting error
@racket[bad-pos] (counting from @math{0}), and all of the original
arguments @racket[v] are provided (in order). The resulting error
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].
@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]{
Creates an @scheme[exn:fail:contract] value and @scheme[raise]s it as
an exception. The @scheme[name] is used as the source procedure's
name in the error message. The @scheme[message] is the error
message. The @scheme[v] argument is the improper argument received by
the procedure. The printed form of @scheme[v] is appended to
@scheme[message] (using the error value conversion handler; see
@scheme[error-value->string-handler]).}
Creates an @racket[exn:fail:contract] value and @racket[raise]s it as
an exception. The @racket[name] is used as the source procedure's
name in the error message. The @racket[message] is the error
message. The @racket[v] argument is the improper argument received by
the procedure. The printed form of @racket[v] is appended to
@racket[message] (using the error value conversion handler; see
@racket[error-value->string-handler]).}
@defproc[(raise-arity-error [name (or/c symbol? procedure?)]
[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] ...)
any]{
Creates an @scheme[exn:fail:contract:arity] value and @scheme[raise]s
it as an exception. The @scheme[name] is used for the source
Creates an @racket[exn:fail:contract:arity] value and @racket[raise]s
it as an exception. The @racket[name] is used for the source
procedure's name in the error message.
The @scheme[arity-v] value must
be a possible result from @scheme[procedure-arity], except
that it does not have to be normalized (see @scheme[procedure-arity?] for
the details of normalized arities); @scheme[raise-arity-error]
The @racket[arity-v] value must
be a possible result from @racket[procedure-arity], except
that it does not have to be normalized (see @racket[procedure-arity?] for
the details of normalized arities); @racket[raise-arity-error]
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.
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
conversion handler; see @scheme[error-value->string-handler]); also,
the number of supplied @scheme[arg-v]s is explicitly mentioned in the
conversion handler; see @racket[error-value->string-handler]); also,
the number of supplied @racket[arg-v]s is explicitly mentioned in the
message.}
@defproc[(raise-syntax-error [name (or/c symbol? #f)]
@ -186,50 +186,50 @@ message.}
[extra-sources (listof syntax?) null])
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.
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
@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
object or S-expression (but the expression @scheme[#f] cannot be
The optional @racket[expr] argument is the erroneous source syntax
object or S-expression (but the expression @racket[#f] cannot be
represented by itself; it must be wrapped as a @tech{syntax
object}). The optional @scheme[sub-expr] argument is a syntax object
or S-expression (again, @scheme[#f] cannot represent itself) within
@scheme[expr] that more precisely locates the error. Both may appear
object}). The optional @racket[sub-expr] argument is a syntax object
or S-expression (again, @racket[#f] cannot represent itself) within
@racket[expr] that more precisely locates the error. Both may appear
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
@scheme[sub-expr] or @scheme[expr] when at least one is a syntax
object and @scheme[error-print-source-location] is @scheme[#t].
@racket[sub-expr] or @racket[expr] when at least one is a syntax
object and @racket[error-print-source-location] is @racket[#t].
If @scheme[sub-expr] is provided and not @scheme[#f], it is used (in
syntax form) for the @scheme[exprs] field of the generated exception
record, else the @scheme[expr] is used if provided and not
@scheme[#f]. In either case, the syntax object is @scheme[cons]ed onto
@scheme[extra-sources] to produce the @scheme[exprs] field, or
@scheme[extra-sources] is used directly for @scheme[exprs] if neither
@scheme[expr] nor @scheme[sub-expr] is provided and not @scheme[#f].
If @racket[sub-expr] is provided and not @racket[#f], it is used (in
syntax form) for the @racket[exprs] field of the generated exception
record, else the @racket[expr] is used if provided and not
@racket[#f]. In either case, the syntax object is @racket[cons]ed onto
@racket[extra-sources] to produce the @racket[exprs] field, or
@racket[extra-sources] is used directly for @racket[exprs] if neither
@racket[expr] nor @racket[sub-expr] is provided and not @racket[#f].
The form name used in the generated error message is determined
through a combination of the @scheme[name], @scheme[expr], and
@scheme[sub-expr] arguments:
through a combination of the @racket[name], @racket[expr], and
@racket[sub-expr] arguments:
@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
its first element, then the form name from the error message is the
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
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.}
]}
@ -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]{
Installs @scheme[f] as the @tech{exception handler} for the
@tech{dynamic extent} of the call to @scheme[thunk]. If an exception
is raised during the evaluation of @scheme[thunk] (in an extension of
Installs @racket[f] as the @tech{exception handler} for the
@tech{dynamic extent} of the call to @racket[thunk]. If an exception
is raised during the evaluation of @racket[thunk] (in an extension of
the current continuation that does not have its own exception
handler), then @scheme[f] is applied to the @scheme[raise]d value in
the continuation of the @scheme[raise] call (but normally extended
handler), then @racket[f] is applied to the @racket[raise]d value in
the continuation of the @racket[raise] call (but normally extended
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
the exception handler returns a value when invoked by @scheme[raise],
then @scheme[raise] propagates the value to the ``previous'' exception
handler (still in the dynamic extent of the call to @scheme[raise],
the exception handler returns a value when invoked by @racket[raise],
then @racket[raise] propagates the value to the ``previous'' exception
handler (still in the dynamic extent of the call to @racket[raise],
and under the same barrier, if any). The previous exception handler is
the exception handler associated with the rest of the continuation
after the point where the called exception handler was associated with
the continuation; if no previous handler is available, the
uncaught-exception handler is used (see below). In all cases, a call
to an exception handler is @scheme[parameterize-break]ed to disable
breaks, and it is wrapped with @scheme[call-with-exception-handler] to
to an exception handler is @racket[parameterize-break]ed to disable
breaks, and it is wrapped with @racket[call-with-exception-handler] to
install the an exception handler that reports both the original and
newly raised exceptions.}
@defparam[uncaught-exception-handler f (any/c . -> . any)]{
A @tech{parameter} that determines an exception handler used by
@scheme[raise] when the relevant continuation has no exception handler
installed with @scheme[call-with-exception-handler] or
@scheme[with-handlers]. Unlike exception handlers installed with
@scheme[call-with-exception-handler], the handler for uncaught
exceptions must not return a value when called by @scheme[raise]; if
@racket[raise] when the relevant continuation has no exception handler
installed with @racket[call-with-exception-handler] or
@racket[with-handlers]. Unlike exception handlers installed with
@racket[call-with-exception-handler], the handler for uncaught
exceptions must not return a value when called by @racket[raise]; if
it returns, an exception is raised (to be handled by an exception
handler that reports both the original and newly raised exception).
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
@scheme[error-escape-handler]). The call to each handler is
@scheme[parameterize]d to set @scheme[error-display-handler] to the
default @tech{error display handler}, and it is @scheme[parameterize-break]ed
@racket[error-escape-handler]). The call to each handler is
@racket[parameterize]d to set @racket[error-display-handler] to the
default @tech{error display handler}, and it is @racket[parameterize-break]ed
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.
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] ...)
body ...+)]{
Evaluates each @scheme[pred-expr] and and @scheme[handler-expr] in the
order that they are specified, and then evaluates the @scheme[body]s
Evaluates each @racket[pred-expr] and and @racket[handler-expr] in the
order that they are specified, and then evaluates the @racket[body]s
with a new exception handler during the its dynamic extent.
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
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
@scheme[handler-expr] procedures, the result of the entire
@scheme[with-handlers] expression is the return value of the handler.
@racket[handler-expr] procedures, the result of the entire
@racket[with-handlers] expression is the return value of the handler.
When an exception is raised during the evaluation of @scheme[body]s,
each predicate procedure @scheme[pred-expr] is applied to the
When an exception is raised during the evaluation of @racket[body]s,
each predicate procedure @racket[pred-expr] is applied to 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
they are specified.
Before any predicate or handler procedure is invoked, the continuation
of the entire @scheme[with-handlers] expression is restored, but also
@scheme[parameterize-break]ed to disable breaks. Thus, breaks are
of the entire @racket[with-handlers] expression is restored, but also
@racket[parameterize-break]ed to disable breaks. Thus, breaks are
disabled by default during the predicate and handler procedures (see
@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
catch all error exceptions. Avoid using @scheme[(lambda (x) #t)] as a
predicate, because the @scheme[exn:break] exception typically should
The @racket[exn:fail?] procedure is useful as a handler predicate to
catch all error exceptions. Avoid using @racket[(lambda (x) #t)] as a
predicate, because the @racket[exn:break] exception typically should
not be caught (unless it will be re-raised to cooperatively
break). Beware, also, of catching and discarding exceptions, because
discarding an error message can make debugging unnecessarily
@ -328,9 +328,9 @@ difficult.}
@defform[(with-handlers* ([pred-expr handler-expr] ...)
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
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}
@ -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
arguments and escapes from the dynamic context of an exception. The
default error escape handler escapes using
@scheme[(abort-current-continuation (default-continuation-prompt-tag)
@racket[(abort-current-continuation (default-continuation-prompt-tag)
void)].
The error escape handler is normally called directly by an exception
handler, in a @tech{parameterization} that sets the @tech{error
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
@scheme[raise] or @scheme[error].
@racket[raise] or @racket[error].
Due to a @tech{continuation barrier} around exception-handling calls,
an error escape handler cannot invoke a full continuation that was
created prior to the exception, but it can abort to a prompt (see
@scheme[call-with-continuation-prompt]) or invoke an escape
continuation (see @scheme[call-with-escape-continuation]).}
@racket[call-with-continuation-prompt]) or invoke an escape
continuation (see @racket[call-with-escape-continuation]).}
@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
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
@scheme[current-error-port] parameter) and extracts a stack trace (see
@scheme[continuation-mark-set->context]) to display from the second
argument if it is an @scheme[exn] value but not an
@scheme[exn:fail:user] value.
@racket[current-error-port] parameter) and extracts a stack trace (see
@racket[continuation-mark-set->context]) to display from the second
argument if it is an @racket[exn] value but not an
@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.}
To report a run-time error, use @scheme[raise] or procedures like
@scheme[error], instead of calling the error display handler
To report a run-time error, use @racket[raise] or procedures like
@racket[error], instead of calling the error display handler
directly.}
@defparam[error-print-width width (and exact-integer? (>=/c 3))]{
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.}
@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}
as the maximum number of lines of context (or ``stack trace'') to
print; a single ``...'' line is printed if more lines are available
after the first @scheme[cnt] lines. A @scheme[0] value for
@scheme[cnt] disables context printing entirely.}
after the first @racket[cnt] lines. A @racket[0] value for
@racket[cnt] disables context printing entirely.}
@defparam[error-value->string-handler proc (any/c exact-nonnegative-integer?
. -> .
string?)]{
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.
The integer argument to the handler specifies the maximum number of
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
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
characters of the return string are set to ``...''.
If the string returned by an error value conversion handler is longer
than requested, the string is destructively ``truncated'' by setting
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
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
enable printing of unreadable values (see @scheme[print-unreadable]).}
enable printing of unreadable values (see @racket[print-unreadable]).}
@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
module-defined variable is accessed before its definition is executed;
the parameter determines whether the message includes a module
name. Only the message field of an @scheme[exn:fail:read],
@scheme[exn:fail:syntax], or @scheme[exn:fail:contract:variable]
structure is affected by the parameter. The default is @scheme[#t].}
name. Only the message field of an @racket[exn:fail:read],
@racket[exn:fail:syntax], or @racket[exn:fail:contract:variable]
structure is affected by the parameter. The default is @racket[#t].}
@;------------------------------------------------------------------------
@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?])
#:inspector #f]{
The base @tech{structure type} for exceptions. The @scheme[message]
field contains an error message, and the @scheme[continuation-marks]
field contains the value produced by @scheme[(current-continuation-marks)]
The base @tech{structure type} for exceptions. The @racket[message]
field contains an error message, and the @racket[continuation-marks]
field contains the value produced by @racket[(current-continuation-marks)]
immediately before the exception was raised.}
@defstruct[(exn:fail exn) ()
#:inspector #f]{
Raised for exceptions that represent errors, as opposed to
@scheme[exn:break].}
@racket[exn:break].}
@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) ()
#: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) ()
#:inspector #f]{
@ -485,27 +485,27 @@ or @tech{module-level variable}.}
@defstruct[(exn:fail:syntax exn:fail) ([exprs (listof syntax?)])
#:inspector #f]{
Raised for a syntax error that is not a @scheme[read] error. The
@scheme[exprs] indicate the relevant source expressions,
Raised for a syntax error that is not a @racket[read] error. The
@racket[exprs] indicate the relevant source expressions,
least-specific to most-specific.}
@defstruct[(exn:fail:read exn:fail) ([srclocs (listof srcloc?)])
#: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.}
@defstruct[(exn:fail:read:eof exn:fail:read) ()
#: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.}
@defstruct[(exn:fail:read:non-char exn:fail:read) ()
#: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
input stream.}
@ -556,32 +556,32 @@ context when printing the error message.}
#:inspector #f]{
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.}
@defthing[prop:exn:srclocs struct-type-property?]{
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.
The property value must be a procedure that accepts a single
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.}
@defproc[(exn:srclocs? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] has the @scheme[prop:exn:srclocs]
property, @scheme[#f] otherwise.}
Returns @racket[#t] if @racket[v] has the @racket[prop:exn:srclocs]
property, @racket[#f] otherwise.}
@defproc[(exn:srclocs-accessor [v exn:srclocs?])
(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]
@ -591,23 +591,23 @@ Returns the @scheme[srcloc]-getting procedure associated with @scheme[v].}
[span (or/c exact-nonnegative-integer? #f)])
#:inspector #f]{
The fields of an @scheme[srcloc] instance are as follows:
The fields of an @racket[srcloc] instance are as follows:
@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"]).}
@item{@scheme[line] --- The line number (counts from 1) or
@scheme[#f] (unknown).}
@item{@racket[line] --- The line number (counts from 1) or
@racket[#f] (unknown).}
@item{@scheme[column] --- The column number (counts from 0) or
@scheme[#f] (unknown).}
@item{@racket[column] --- The column number (counts from 0) or
@racket[#f] (unknown).}
@item{@scheme[position] --- The starting position (counts from 1) or
@scheme[#f] (unknown).}
@item{@racket[position] --- The starting position (counts from 1) or
@racket[#f] (unknown).}
@item{@scheme[span] --- The number of covered positions (counts from
0) or @scheme[#f] (unknown).}
@item{@racket[span] --- The number of covered positions (counts from
0) or @racket[#f] (unknown).}
]}

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

@ -36,11 +36,11 @@
@title[#:tag "file-ports"]{File Ports}
A port created by @scheme[open-input-file], @scheme[open-output-file],
@scheme[subprocess], and related functions is a @deftech{file-stream
port}. The initial input, output, and error ports in stand-alone
MzScheme are also file-stream ports. The @scheme[file-stream-port?]
predicate recognizes file-stream ports.
A port created by @racket[open-input-file], @racket[open-output-file],
@racket[subprocess], and related functions is a @deftech{file-stream
port}. The initial input, output, and error ports in @exec{racket}
are also file-stream ports. The @racket[file-stream-port?] predicate
recognizes file-stream ports.
When an input or output file-stream port is created, it is placed into
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])
input-port?]{
Opens the file specified by @scheme[path] for input. The
@scheme[mode-flag] argument specifies how the file's bytes are
Opens the file specified by @racket[path] for input. The
@racket[mode-flag] argument specifies how the file's bytes are
translated on input:
@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.}
@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
specific manner:
@ -74,25 +74,25 @@ translated on input:
]}
]
Under Windows, @scheme['text] mode works only with regular files;
attempting to use @scheme['text] with other kinds of files triggers an
@scheme[exn:fail:filesystem] exception.
Under Windows, @racket['text] mode works only with regular files;
attempting to use @racket['text] with other kinds of files triggers an
@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
as @filepath{aux} under Windows or @filepath{/dev/null} under Unix. In all
cases, the port is buffered by default.
The port produced by @scheme[open-input-file] should be explicitly
closed, either though @scheme[close-input-port] or indirectly via
@scheme[custodian-shutdown-all], to release the OS-level file
The port produced by @racket[open-input-file] should be explicitly
closed, either though @racket[close-input-port] or indirectly via
@racket[custodian-shutdown-all], to release the OS-level file
handle. The input port will not be closed automatically if it is
otherwise available for garbage collection (see
@secref["gc-model"]); a @tech{will} could be associated input port
to close it more automatically (see @secref["willexecutor"]).
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[
;; 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])
output-port?]{
Opens the file specified by @scheme[path] for output. The
@scheme[mode-flag] argument specifies how bytes written to the port
Opens the file specified by @racket[path] for output. The
@racket[mode-flag] argument specifies how bytes written to the port
are translated when written to the file:
@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.}
@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
file; no filtering occurs for returns.}
]
Under Windows, @scheme['text] mode works only with regular files;
attempting to use @scheme['text] with other kinds of files triggers an
@scheme[exn:fail:filesystem] exception.
Under Windows, @racket['text] mode works only with regular files;
attempting to use @racket['text] with other kinds of files triggers an
@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:
@itemize[
@item{@indexed-scheme['error] --- raise @scheme[exn:fail:filesystem]
@item{@indexed-racket['error] --- raise @racket[exn:fail:filesystem]
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.}
@item{@indexed-scheme['truncate] --- remove all old data, if the file
@item{@indexed-racket['truncate] --- remove all old data, if the file
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
@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
@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
@exnraise[exn:fail:filesystem]. Use @scheme[file-position]
@exnraise[exn:fail:filesystem]. Use @racket[file-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.}
@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,
@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
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
@filepath{aux} under Windows or @filepath{/dev/null} under Unix. The output
port is block-buffered by default, unless the file corresponds to a
terminal, in which case is it line buffered bu default.
The port produced by @scheme[open-output-port] should be explicitly
closed, either though @scheme[close-output-port] or indirectly via
@scheme[custodian-shutdown-all], to release the OS-level file
The port produced by @racket[open-output-port] should be explicitly
closed, either though @racket[close-output-port] or indirectly via
@racket[custodian-shutdown-all], to release the OS-level file
handle. The output port will not be closed automatically if it is
otherwise available for garbage collection (see
@secref["gc-model"]); a @tech{will} could be associated input port
to close it more automatically (see @secref["willexecutor"]).
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[
(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])
(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
share the underlying file device. This procedure is intended for use
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
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
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.}
@defproc[(call-with-input-file [path path-string?]
[proc (input-port? . -> . any)]
[#:mode mode-flag (or/c 'binary 'text) 'binary])
any]{
Calls @scheme[open-input-file] with the @scheme[path] and
@scheme[mode-flag] arguments, and passes the resulting port
to @scheme[proc]. The result of @scheme[proc] is the result of the
@scheme[call-with-input-file] call, but the newly opened port is closed
when @scheme[thunk] return.
Calls @racket[open-input-file] with the @racket[path] and
@racket[mode-flag] arguments, and passes the resulting port
to @racket[proc]. The result of @racket[proc] is the result of the
@racket[call-with-input-file] call, but the newly opened port is closed
when @racket[thunk] return.
@file-examples[
(with-output-to-file some-file
@ -230,9 +230,9 @@ when @scheme[thunk] return.
[#:exists exists-flag (or/c 'error 'append 'update
'replace 'truncate 'truncate/replace) 'error])
any]{
Analogous to @scheme[call-with-input-file], but passing @scheme[path],
@scheme[mode-flag] and @scheme[exists-flag] to
@scheme[open-output-file].
Analogous to @racket[call-with-input-file], but passing @racket[path],
@racket[mode-flag] and @racket[exists-flag] to
@racket[open-output-file].
@file-examples[
(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)]
[#:mode mode-flag (or/c 'binary 'text) 'binary])
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
@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.}
@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
'replace 'truncate 'truncate/replace) 'error])
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
@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.}
@defproc[(with-input-from-file [path path-string?]
[thunk (-> any)]
[#:mode mode-flag (or/c 'binary 'text) 'binary])
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
the current input port (see @scheme[current-input-port]) using
@scheme[parameterize] around the call to @scheme[thunk].
the current input port (see @racket[current-input-port]) using
@racket[parameterize] around the call to @racket[thunk].
@file-examples[
(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
'replace 'truncate 'truncate/replace) 'error])
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
the current output port (see @scheme[current-output-port]) using
@scheme[parameterize] around the call to @scheme[thunk].
the current output port (see @racket[current-output-port]) using
@racket[parameterize] around the call to @racket[thunk].
@file-examples[
(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
the identity of the device and file read or written by
@scheme[port]. For two ports whose open times overlap, the
result of @scheme[port-file-identity] is the same for both ports if
@racket[port]. For two ports whose open times overlap, the
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
open times do not overlap, no guarantee can be provided for the port
identities (even if the ports actually access the same file)---except
as can be inferred through relationships with other ports. If
@scheme[port] is closed, the @exnraise[exn:fail]. Under
Windows 95, 98, and Me, if @scheme[port] is connected to a
@racket[port] is closed, the @exnraise[exn:fail]. Under
Windows 95, 98, and Me, if @racket[port] is connected to a
pipe instead of a file, the @exnraise[exn:fail:filesystem].
@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.}
@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.}
@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
name is platform-specific:
@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
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
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
executable; this may be different from result for
@racket['exec-file] because an alternate path was provided through a
@DFlag{name} or @Flag{N} command-line flag to the @exec{mzracket}
(or @exec{mred}) executable, or because an embedding executable
@DFlag{name} or @Flag{N} command-line flag to the Racket
(or GRacket) executable, or because an embedding executable
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.}
@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
the two results should be combined with
@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.}
@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
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
this case, @racket[program] is the name used to start Racket and
@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]
@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
x86/x86_64. To enable support for other platforms, use
@DFlag{enable-futures} with @exec{configure} when building PLT
Scheme.}
@DFlag{enable-futures} with @exec{configure} when building
Racket.}
The @scheme[future] and @scheme[touch] functions from
@schememodname[racket/future] provide access to parallelism as
The @racket[future] and @racket[touch] functions from
@racketmodname[racket/future] provide access to parallelism as
supported by the hardware and operation system.
In contrast to @scheme[thread], which provides concurrency for
arbitrary computations without parallelism, @scheme[future] provides
In contrast to @racket[thread], which provides concurrency for
arbitrary computations without parallelism, @racket[future] provides
parallelism for limited computations. A future executes its work in
parallel (assuming that support for parallelism is available) until it
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
suspended if it depends in some way on the current continuation, such
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
provided by the system must be able to enforce contracts and produce
results as documented. ``Safe'' does not preclude concurrent access to
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
visible in other futures and threads. Furthermore, guarantees about
the visibility of effects and ordering are determined by the operating
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
have a complex enough implementation internally that they cannot run
in parallel. See also @guidesecref["effective-futures"].
@ -49,16 +49,16 @@ in parallel. See also @guidesecref["effective-futures"].
@defproc[(touch [f future?]) any]
)]{
The @scheme[future] procedure returns a future value that
encapsulates @scheme[thunk]. The @scheme[touch] function forces the
evaluation of the @scheme[thunk] inside the given future, returning
the values produced by @scheme[thunk]. After @scheme[touch] forces
the evaluation of a @scheme[thunk], the resulting values are retained
by the future descriptor in place of @scheme[thunk], and additional
@scheme[touch]es of the future descriptor return those values.
The @racket[future] procedure returns a future value that
encapsulates @racket[thunk]. The @racket[touch] function forces the
evaluation of the @racket[thunk] inside the given future, returning
the values produced by @racket[thunk]. After @racket[touch] forces
the evaluation of a @racket[thunk], the resulting values are retained
by the future descriptor in place of @racket[thunk], and additional
@racket[touch]es of the future descriptor return those values.
Between a call to @scheme[future] and @scheme[touch] for a given
future, the given @scheme[thunk] may run speculatively in parallel to
Between a call to @racket[future] and @racket[touch] for a given
future, the given @racket[thunk] may run speculatively in parallel to
other computations, as described above.
@interaction[
@ -69,8 +69,8 @@ in parallel. See also @guidesecref["effective-futures"].
@defproc[(future? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] is a future-descriptor value,
@scheme[#f] otherwise.
Returns @racket[#t] if @racket[v] is a future-descriptor value,
@racket[#f] otherwise.
}
@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.
@schemeblock[
(require racket/gui) (code:comment @#,t{does not work in @exec{mzscheme}})
(require (for-label racket/gui)) (code:comment @#,t{ok 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{racket}})
(help frame%)
]

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

@ -5,14 +5,14 @@
@title{Init Libraries}
@defmodule*/no-declare[(racket/init)]{The @schememodname[racket/init]
library is the default start-up library for MzScheme. It re-exports
the @schememodname[scheme], @schememodname[racket/enter] and
@schememodname[racket/help] libraries, and it sets
@scheme[current-print] to use @scheme[pretty-print].}
@defmodule*/no-declare[(racket/init)]{The @racketmodname[racket/init]
library is the default start-up library for Racket. It re-exports
the @racketmodname[racket], @racketmodname[racket/enter] and
@racketmodname[racket/help] libraries, and it sets
@racket[current-print] to use @racket[pretty-print].}
@defmodule*/no-declare[(racket/gui/init)]{The
@schememodname[racket/gui/init] library is the default start-up
library for MrEd. It re-exports the @schememodname[racket/init] and
@schememodname[racket/gui/base] libraries, and it sets
@scheme[current-load] to use @scheme[text-editor-load-handler].}
@racketmodname[racket/gui/init] library is the default start-up
library for GRacket. It re-exports the @racketmodname[racket/init] and
@racketmodname[racket/gui/base] libraries, and it sets
@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
@(require "mz.ss")
@title[#:tag "load-lang"]{The @schememodname[racket/load] Language}
@title[#:tag "load-lang"]{The @racketmodname[racket/load] Language}
@defmodulelang[racket/load]
The @schememodname[racket/load] language supports traditional Scheme
evaluation, where each top-level form in the module body is separately
passed to @scheme[eval] in the same way as for @scheme[load].
The @racketmodname[racket/load] language supports evaluation where
each top-level form in the module body is separately passed to
@racket[eval] in the same way as for @racket[load].
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
@schememodname[scheme]. A single namespace is created for each
instance of the @schememodname[racket/load] module (i.e., multiple
modules using the @schememodname[racket/load] language share a
namespace). The @scheme[racket/load] library exports only
@schemeidfont{#%module-begin} and @schemeidfont{#%top-interaction}
@racketmodname[racket]. A single namespace is created for each
instance of the @racketmodname[racket/load] module (i.e., multiple
modules using the @racketmodname[racket/load] language share a
namespace). The @racket[racket/load] library exports only
@racketidfont{#%module-begin} and @racketidfont{#%top-interaction}
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
include @scheme[module] forms, so that running the following module
prints @schemeresultfont{5}:
For example, the body of a module using @racket[racket/load] can
include @racket[module] forms, so that running the following module
prints @racketresultfont{5}:
@schememod[
@racketmod[
racket/load
(module m racket/base
@ -38,22 +38,22 @@ racket/load
(require 'n)
]
Definitions in a module using @scheme[racket/load] are evaluated in
the current namespace, which means that @scheme[load] and
@scheme[eval] can see the definitions. For example, running the
following module prints @schemeresultfont{6}:
Definitions in a module using @racket[racket/load] are evaluated in
the current namespace, which means that @racket[load] and
@racket[eval] can see the definitions. For example, running the
following module prints @racketresultfont{6}:
@schememod[
@racketmod[
racket/load
(define x 6)
(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
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
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.

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
| (MCONS pat pat) @match mutable pair of pats
| (BOX pat) @match boxed pat
| (struct-id pat ...) @match struct-id instance
| (STRUCT struct-id (pat ...)) @match struct-id instance
| (REGEXP rx-expr) @match string
| (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}
The @scheme[match] form and related forms support general pattern
matching on Scheme values. See also @secref["regexp"] for information
The @racket[match] form and related forms support general pattern
matching on Racket values. See also @secref["regexp"] for information
on regular-expression matching on strings, bytes, and streams.
@note-lib[racket/match #:use-sources (racket/match)]
@ -20,24 +20,24 @@ on regular-expression matching on strings, bytes, and streams.
([clause [pat expr ...+]
[pat (=> id) expr ...+]])]{
Finds the first @scheme[pat] that matches the result of
@scheme[val-expr], and evaluates the corresponding @scheme[expr]s with
bindings introduced by @scheme[pat] (if any). The last @scheme[expr]
Finds the first @racket[pat] that matches the result of
@racket[val-expr], and evaluates the corresponding @racket[expr]s with
bindings introduced by @racket[pat] (if any). The last @racket[expr]
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
@scheme[clause] matches, then the @exnraise[exn:misc:match?].
The @racket[clause]s are tried in order to find a match. If no
@racket[clause] matches, then the @exnraise[exn:misc:match?].
An optional @scheme[(=> id)] between a @scheme[pat] and the
@scheme[expr]s is bound to a @defterm{failure procedure} of zero
An optional @racket[(=> id)] between a @racket[pat] and the
@racket[expr]s is bound to a @defterm{failure procedure} of zero
arguments. If this procedure is invoked, it escapes back to the
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,
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).
@|match-grammar|
@ -46,16 +46,16 @@ In more detail, patterns match as follows:
@itemize[
@item{@scheme[_id], excluding the reserved names @schemeidfont{_},
@schemeidfont{...}, @schemeidfont{.._},
@schemeidfont{..}@scheme[_k], and
@schemeidfont{..}@scheme[_k] for non-negative integers
@scheme[_k] --- matches anything, and binds @scheme[id] to the
matching values. If an @scheme[_id] is used multiple times
@item{@racket[_id], excluding the reserved names @racketidfont{_},
@racketidfont{...}, @racketidfont{.._},
@racketidfont{..}@racket[_k], and
@racketidfont{..}@racket[_k] for non-negative integers
@racket[_k] --- matches anything, and binds @racket[id] to the
matching values. If an @racket[_id] is used multiple times
within a pattern, the corresponding matches must be the same
according to @scheme[(match-equality-test)], except that
instances of an @scheme[_id] in different @schemeidfont{or} and
@schemeidfont{not} sub-patterns are independent.
according to @racket[(match-equality-test)], except that
instances of an @racket[_id] in different @racketidfont{or} and
@racketidfont{not} sub-patterns are independent.
@examples[
#:eval match-eval
@ -67,7 +67,7 @@ In more detail, patterns match as follows:
[(list a b c) (list c b a)])
]}
@item{@schemeidfont{_} --- matches anything, without binding any
@item{@racketidfont{_} --- matches anything, without binding any
identifiers.
@examples[
@ -76,9 +76,9 @@ In more detail, patterns match as follows:
[(list _ _ a) a])
]}
@item{@scheme[#t], @scheme[#f], @scheme[_string], @scheme[_bytes],
@scheme[_number], @scheme[_char], or @scheme[(#,(schemeidfont
"quote") _datum)] --- matches an @scheme[equal?] constant.
@item{@racket[#t], @racket[#f], @racket[_string], @racket[_bytes],
@racket[_number], @racket[_char], or @racket[(#,(racketidfont
"quote") _datum)] --- matches an @racket[equal?] constant.
@examples[
#:eval match-eval
@ -87,17 +87,17 @@ In more detail, patterns match as follows:
["yes" #t])
]}
@item{@scheme[(#,(schemeidfont "list") _lvp ...)] --- matches a list
of elements. In the case of @scheme[(#,(schemeidfont "list")
@item{@racket[(#,(racketidfont "list") _lvp ...)] --- matches a list
of elements. In the case of @racket[(#,(racketidfont "list")
_pat ...)], the pattern matches a list with as many element as
@scheme[_pat]s, and each element must match the corresponding
@scheme[_pat]. In the more general case, each @scheme[_lvp]
@racket[_pat]s, and each element must match the corresponding
@racket[_pat]. In the more general case, each @racket[_lvp]
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
@schemeidfont{..}@scheme[_k] and @schemeidfont{__}@scheme[_k]
forms are also synonyms, specifying @scheme[_k] or more
@racketidfont{..}@racket[_k] and @racketidfont{__}@racket[_k]
forms are also synonyms, specifying @racket[_k] or more
matches. Pattern variables that precede these splicing
operators are bound to lists of matching forms.
@ -121,11 +121,11 @@ In more detail, patterns match as follows:
[_ 'else])
]}
@item{@scheme[(#,(schemeidfont "list-rest") _lvp ... _pat)] ---
similar to a @schemeidfont{list} pattern, but the final
@scheme[_pat] matches the ``rest'' of the list after the last
@scheme[_lvp]. In fact, the matched value can be a non-list
chain of pairs (i.e., an ``improper list'') if @scheme[_pat]
@item{@racket[(#,(racketidfont "list-rest") _lvp ... _pat)] ---
similar to a @racketidfont{list} pattern, but the final
@racket[_pat] matches the ``rest'' of the list after the last
@racket[_lvp]. In fact, the matched value can be a non-list
chain of pairs (i.e., an ``improper list'') if @racket[_pat]
matches non-list values.
@examples[
@ -136,9 +136,9 @@ In more detail, patterns match as follows:
[(list-rest a ... d) (list a d)])
]}
@item{@scheme[(#,(schemeidfont "list-no-order") _pat ...)] ---
similar to a @schemeidfont{list} pattern, but the elements to
match each @scheme[_pat] can appear in the list in any order.
@item{@racket[(#,(racketidfont "list-no-order") _pat ...)] ---
similar to a @racketidfont{list} pattern, but the elements to
match each @racket[_pat] can appear in the list in any order.
@examples[
#:eval match-eval
@ -146,8 +146,8 @@ In more detail, patterns match as follows:
[(list-no-order 3 2 x) x])
]}
@item{@scheme[(#,(schemeidfont "list-no-order") _pat ... _lvp)] ---
generalizes @schemeidfont{list-no-order} to allow a pattern
@item{@racket[(#,(racketidfont "list-no-order") _pat ... _lvp)] ---
generalizes @racketidfont{list-no-order} to allow a pattern
that matches multiple list elements that are interspersed in
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])
]}
@item{@scheme[(#,(schemeidfont "vector") _lvp ...)] --- like a
@schemeidfont{list} pattern, but matching a vector.
@item{@racket[(#,(racketidfont "vector") _lvp ...)] --- like a
@racketidfont{list} pattern, but matching a vector.
@examples[
#:eval match-eval
@ -166,8 +166,8 @@ In more detail, patterns match as follows:
[(vector 1 (list a) ..3 5) a])
]}
@item{@scheme[(#,(schemeidfont "hash-table") (_pat _pat) ...)] ---
similar to @schemeidfont{list-no-order}, but matching against
@item{@racket[(#,(racketidfont "hash-table") (_pat _pat) ...)] ---
similar to @racketidfont{list-no-order}, but matching against
hash table's key--value pairs.
@examples[
@ -176,8 +176,8 @@ In more detail, patterns match as follows:
[(hash-table ("b" b) ("a" a)) (list b a)])
]}
@item{@scheme[(#,(schemeidfont "hash-table") (_pat _pat) ...+ _ooo)]
--- Generalizes @schemeidfont{hash-table} to support a final
@item{@racket[(#,(racketidfont "hash-table") (_pat _pat) ...+ _ooo)]
--- Generalizes @racketidfont{hash-table} to support a final
repeating pattern.
@examples[
@ -186,7 +186,7 @@ In more detail, patterns match as follows:
[(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[
#:eval match-eval
@ -194,7 +194,7 @@ In more detail, patterns match as follows:
[(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[
#:eval match-eval
@ -203,7 +203,7 @@ In more detail, patterns match as follows:
[(mcons a b) 'mutable])
]}
@item{@scheme[(#,(schemeidfont "box") _pat)] --- matches a boxed value.
@item{@racket[(#,(racketidfont "box") _pat)] --- matches a boxed value.
@examples[
#:eval match-eval
@ -211,37 +211,38 @@ In more detail, patterns match as follows:
[(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
@scheme[_struct-id], where each field in the instance matches
the corresponding @scheme[_pat].
@racket[_struct-id], where each field in the instance matches
the corresponding @racket[_pat]. See also @scheme[struct*].
Usually, @scheme[_struct-id] is defined with
@scheme[define-struct]. More generally, @scheme[_struct-id]
Usually, @racket[_struct-id] is defined with
@racket[struct]. More generally, @racket[_struct-id]
must be bound to expansion-time information for a structure
type (see @secref["structinfo"]), where the information
includes at least a predicate binding and field accessor
bindings corresponding to the number of field
@scheme[_pat]s. In particular, a module import or a
@scheme[unit] import with a signature containing a
@scheme[struct] declaration can provide the structure type
@racket[_pat]s. In particular, a module import or a
@racket[unit] import with a signature containing a
@racket[struct] declaration can provide the structure type
information.
@defexamples[
#:eval match-eval
(define-struct tree (val left right))
(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 _)] ---
matches any instance of @scheme[_struct-id], without regard to
@item{@racket[(#,(racketidfont "struct") _struct-id _)] ---
matches any instance of @racket[_struct-id], without regard to
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
@scheme[_rx-expr]; see @secref["regexp"] for more information
@racket[_rx-expr]; see @secref["regexp"] for more information
about regexps.
@examples[
@ -254,10 +255,10 @@ In more detail, patterns match as follows:
[_ 'no])
]}
@item{@scheme[(#,(schemeidfont "regexp") _rx-expr _pat)] --- extends
the @schemeidfont{regexp} form to further constrain the match
where the result of @scheme[regexp-match] is matched against
@scheme[_pat].
@item{@racket[(#,(racketidfont "regexp") _rx-expr _pat)] --- extends
the @racketidfont{regexp} form to further constrain the match
where the result of @racket[regexp-match] is matched against
@racket[_pat].
@examples[
#:eval match-eval
@ -269,16 +270,16 @@ In more detail, patterns match as follows:
[_ 'no])
]}
@item{@scheme[(#,(schemeidfont "pregexp") _rx-expr)] or
@scheme[(#,(schemeidfont "regexp") _rx-expr _pat)] --- like the
@schemeidfont{regexp} patterns, but if @scheme[_rx-expr]
@item{@racket[(#,(racketidfont "pregexp") _rx-expr)] or
@racket[(#,(racketidfont "regexp") _rx-expr _pat)] --- like the
@racketidfont{regexp} patterns, but if @racket[_rx-expr]
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
of the @scheme[_pat]s match. This pattern is often used as
@scheme[(#,(schemeidfont "and") _id _pat)] to bind @scheme[_id]
to the entire value that matches @scheme[pat].
@item{@racket[(#,(racketidfont "and") _pat ...)] --- matches if all
of the @racket[_pat]s match. This pattern is often used as
@racket[(#,(racketidfont "and") _id _pat)] to bind @racket[_id]
to the entire value that matches @racket[pat].
@examples[
#:eval match-eval
@ -286,12 +287,12 @@ In more detail, patterns match as follows:
[(list _ (and a (list _ ...)) _) a])
]}
@item{@scheme[(#,(schemeidfont "or") _pat ...)] --- matches if any of
the @scheme[_pat]s match. @bold{Beware}: the result expression
can be duplicated once for each @scheme[_pat]! Identifiers in
@scheme[_pat] are bound only in the corresponding copy of the
@item{@racket[(#,(racketidfont "or") _pat ...)] --- matches if any of
the @racket[_pat]s match. @bold{Beware}: the result expression
can be duplicated once for each @racket[_pat]! Identifiers in
@racket[_pat] are bound only in the corresponding copy of the
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.
@examples[
@ -300,8 +301,8 @@ In more detail, patterns match as follows:
[(or (list a 1) (list a 2)) a])
]}
@item{@scheme[(#,(schemeidfont "not") _pat ...)] --- matches when
none of the @scheme[_pat]s match, and binds no identifiers.
@item{@racket[(#,(racketidfont "not") _pat ...)] --- matches when
none of the @racket[_pat]s match, and binds no identifiers.
@examples[
#:eval match-eval
@ -313,9 +314,9 @@ In more detail, patterns match as follows:
[_ 'no])
]}
@item{@scheme[(#,(schemeidfont "app") _expr _pat)] --- applies
@scheme[_expr] to the value to be matched; the result of the
application is matched againt @scheme[_pat].
@item{@racket[(#,(racketidfont "app") _expr _pat)] --- applies
@racket[_expr] to the value to be matched; the result of the
application is matched againt @racket[_pat].
@examples[
#:eval match-eval
@ -323,11 +324,11 @@ In more detail, patterns match as follows:
[(app length 2) 'yes])
]}
@item{@scheme[(#,(schemeidfont "?") _expr _pat ...)] --- applies
@scheme[_expr] to the value to be matched, and checks whether
the result is a true value; the additional @scheme[_pat]s must
also match (i.e., @schemeidfont{?} combines a predicate
application and an @schemeidfont{and} pattern).
@item{@racket[(#,(racketidfont "?") _expr _pat ...)] --- applies
@racket[_expr] to the value to be matched, and checks whether
the result is a true value; the additional @racket[_pat]s must
also match (i.e., @racketidfont{?} combines a predicate
application and an @racketidfont{and} pattern).
@examples[
#:eval match-eval
@ -335,10 +336,10 @@ In more detail, patterns match as follows:
[(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
@scheme[quasiquote] expression form, @schemeidfont{unquote}
and @schemeidfont{unquote-splicing} escape back to normal
@racket[quasiquote] expression form, @racketidfont{unquote}
and @racketidfont{unquote-splicing} escape back to normal
patterns.
@examples[
@ -347,8 +348,8 @@ In more detail, patterns match as follows:
[`(1 ,a ,(? odd? b)) (list a b)])
]}
@item{@scheme[_derived-pattern] --- matches a pattern defined by a
macro extension via @scheme[define-match-expander].}
@item{@racket[_derived-pattern] --- matches a pattern defined by a
macro extension via @racket[define-match-expander].}
]}
@ -358,20 +359,20 @@ In more detail, patterns match as follows:
@defform[(match-lambda clause ...)]{
Equivalent to @scheme[(lambda (id) (match id clause ...))].
Equivalent to @racket[(lambda (id) (match id 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 ...+)]{
Generalizes @scheme[let] to support pattern bindings. Each
@scheme[expr] is matched against its corresponding @scheme[pat] (the
match must succeed), and the bindings that @scheme[pat] introduces are
visible in the @scheme[body]s.
Generalizes @racket[let] to support pattern bindings. Each
@racket[expr] is matched against its corresponding @racket[pat] (the
match must succeed), and the bindings that @racket[pat] introduces are
visible in the @racket[body]s.
@examples[
#:eval match-eval
@ -382,9 +383,9 @@ visible in the @scheme[body]s.
@defform[(match-let* ([pat expr] ...) body ...+)]{
Like @scheme[match-let], but generalizes @scheme[let*], so that the
bindings of each @scheme[pat] are available in each subsequent
@scheme[expr].
Like @racket[match-let], but generalizes @racket[let*], so that the
bindings of each @racket[pat] are available in each subsequent
@racket[expr].
@examples[
#:eval match-eval
@ -395,13 +396,13 @@ bindings of each @scheme[pat] are available in each subsequent
@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)]{
Defines the names bound by @scheme[pat] to the values produced by
matching against the result of @scheme[expr].
Defines the names bound by @racket[pat] to the values produced by
matching against the result of @racket[expr].
@examples[
#: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)
(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
transformer that produces a @scheme[_pat] for @scheme[match].
Whenever @scheme[id] appears as the beginning of a pattern, this
The first @racket[proc-expr] subexpression must evaluate to a
transformer that produces a @racket[_pat] for @racket[match].
Whenever @racket[id] appears as the beginning of a pattern, this
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.
A transformer produced by a second @scheme[proc-expr] subexpression is
used when @scheme[id] is used in an expression context. Using the
second @scheme[proc-expr], @scheme[id] can be given meaning both
A transformer produced by a second @racket[proc-expr] subexpression is
used when @racket[id] is used in an expression context. Using the
second @racket[proc-expr], @racket[id] can be given meaning both
inside and outside patterns.}
@defparam[match-equality-test comp-proc (any/c any/c . -> . any)]{
A parameter that determines the comparison procedure used to check
whether multiple uses of an identifier match the ``same'' value. The
default is @scheme[equal?].}
default is @racket[equal?].}
@; ----------------------------------------------------------------------
@section{Library Extensions}
@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[
#: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["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
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
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["custodians"]).
@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]{
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
@scheme[weak-box] was reachable only through a weak reference, then
@scheme[#f] is returned.}
@racket[weak-box] was reachable only through a weak reference, then
@racket[#f] is returned.}
@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}
@ -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
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
references (see @secref["weakbox"]); and}
@ -65,20 +65,20 @@ key.
@defproc[(make-ephemeron [key any/c][v any/c]) ephemeron?]{
Returns a new @tech{ephemeron} whose key is @scheme[key] and whose
value is initially @scheme[v].}
Returns a new @tech{ephemeron} whose key is @racket[key] and whose
value is initially @racket[v].}
@defproc[(ephemeron-value [ephemeron ephemeron?]) any]{
Returns the value contained in @scheme[ephemeron]. If the garbage
collector has proven that the key for @scheme[ephemeron] is only
weakly reachable, then the result is @scheme[#f].}
Returns the value contained in @racket[ephemeron]. If the garbage
collector has proven that the key for @racket[ephemeron] is only
weakly reachable, then the result is @racket[#f].}
@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.}
@;------------------------------------------------------------------------
@ -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
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
executor. Wills are not executed automatically, because certain
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
corresponding will procedure is executed. Thus, if the content value
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
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?]{
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.}
@defproc[(will-register [executor will-executor?][v any/c][proc (any/c . -> . any)])
void?]{
Registers the value @scheme[v] with the will procedure @scheme[proc]
in the will executor @scheme[executor]. When @scheme[v] is proven
unreachable, then the procedure @scheme[proc] is ready to be called
with @scheme[v] as its argument via @scheme[will-execute] or
@scheme[will-try-execute]. The @scheme[proc] argument is strongly
Registers the value @racket[v] with the will procedure @racket[proc]
in the will executor @racket[executor]. When @racket[v] is proven
unreachable, then the procedure @racket[proc] is ready to be called
with @racket[v] as its argument via @racket[will-execute] or
@racket[will-try-execute]. The @racket[proc] argument is strongly
referenced until the will procedure is executed.}
@defproc[(will-execute [executor will-executor?]) any]{
Invokes the will procedure for a single ``unreachable'' value
registered with the executor @scheme[executable]. The values returned
by the will procedure are the result of the @scheme[will-execute]
registered with the executor @racket[executable]. The values returned
by the will procedure are the result of the @racket[will-execute]
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]{
Like @scheme[will-execute] if a will is ready for immediate
execution. Otherwise, @scheme[#f] is returned.}
Like @racket[will-execute] if a will is ready for immediate
execution. Otherwise, @racket[#f] is returned.}
@;------------------------------------------------------------------------
@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
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
this procedure is never called.}
@defproc[(current-memory-use [cust custodian? #f]) exact-nonnegative-integer?]{
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;
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.
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;
see also @scheme[custodian-memory-accounting-available?].}
see also @racket[custodian-memory-accounting-available?].}
@defproc[(dump-memory-stats) any]{

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

@ -1,12 +1,12 @@
#lang scribble/doc
@(require "mz.ss"
scribble/scheme
scribble/racket
(for-label racket/mpair))
@title[#:tag "mpairs"]{Mutable Pairs and Lists}
A @deftech{mutable pair} is like a pair created by @scheme[cons], but
it supports @scheme[set-mcar!] and @scheme[set-mcdr!] mutation
A @deftech{mutable pair} is like a pair created by @racket[cons], but
it supports @racket[set-mcar!] and @racket[set-mcdr!] mutation
operations to change the parts of the mutable pair (like traditional Lisp and
Scheme pairs).
@ -23,31 +23,31 @@ always better choices.
@; ----------------------------------------
@section{Mutable Pair Constructors and Selectors}
@defproc[(mpair? [v any/c]) boolean?]{Returns @scheme[#t] if @scheme[v] is
a @tech{mutable pair}, @scheme[#f] otherwise.}
@defproc[(mpair? [v any/c]) boolean?]{Returns @racket[#t] if @racket[v] is
a @tech{mutable pair}, @racket[#f] otherwise.}
@defproc[(mcons [a any/c] [d any/c]) pair?]{Returns a newly allocated
@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
@tech{mutable pair} @scheme[p].}
@tech{mutable pair} @racket[p].}
@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])
void?]{
Changes the @tech{mutable pair} @scheme[p] so that its first element is
@scheme[v].}
Changes the @tech{mutable pair} @racket[p] so that its first element is
@racket[v].}
@defproc[(set-mcdr! [p mpair?] [v any/v])
void?]{
Changes the @tech{mutable pair} @scheme[p] so that its second element is
@scheme[v].}
Changes the @tech{mutable pair} @racket[p] so that its second element is
@racket[v].}
@; ----------------------------------------
@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,
supplying any other kind of value (or mutating a value that starts as
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
@scheme[v] is a @tech{mutable list}: either the empty list, or a
@defproc[(mlist? [v any/c]) boolean?]{Returns @racket[#t] if
@racket[v] is a @tech{mutable list}: either the empty list, or a
@tech{mutable pair} whose second element is a @tech{mutable list}.}
@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?]{
Returns a newly allocated @tech{mutable list} with the same elements as
@scheme[lst].}
@racket[lst].}
@defproc[(mlist->list [mlst mlist?]) list?]{
Returns a newly allocated @tech{mutable list} with the same elements as
@scheme[nlst].}
@racket[nlst].}
@defproc[(mlength [mlst mlist?])
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?])
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?])
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?]
[(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?]
[(mappend! [mlst mlist?] ... [v any/c]) any/c])]{
The @scheme[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 @racket[mappend!] procedure appends the given @tech{mutable lists} by mutating
the tail of each to refer to the next, using @racket[set-mcdr!]. Empty
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
arguments.}
@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?]{
Like @scheme[mreverse], but destructively reverses the
Like @racket[mreverse], but destructively reverses the
@tech{mutable list} by using
all of the mutable pairs in @scheme[mlst] and changing them with
@scheme[set-mcdr!].}
all of the mutable pairs in @racket[mlst] and changing them with
@racket[set-mcdr!].}
@defproc[(mmap [proc procedure?] [mlst 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?] ...+)
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?])
(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?])
(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?])
(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?)])
(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?)])
(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?)])
(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)])
(any/c . -> . boolean?)]{
Returns a procedure that returns @scheme[#t] when given a @tech{mutable list}
for which @scheme[pred] returns a true value for all elements.}
Returns a procedure that returns @racket[#t] when given a @tech{mutable list}
for which @racket[pred] returns a true value for all elements.}

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

@ -58,7 +58,7 @@
" and "
(schememodname racket/init)
" 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)
" or " (schememodname racket) "."
. 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?]{
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
@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
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.)
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}
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
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
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.
Otherwise, the listener accepts connections only at the interface(s)
associated with the given hostname. For example, providing
@scheme["127.0.0.1"] as @scheme[hostname] creates a listener that
accepts only connections to @scheme["127.0.0.1"] (the loopback
@racket["127.0.0.1"] as @racket[hostname] creates a listener that
accepts only connections to @racket["127.0.0.1"] (the loopback
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
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
be configured to listen to only IPv6 connections: if IPv6 is not
supported or IPv6 sockets are not configurable, then the IPv6
addresses are ignored; otherwise, each IPv6 listener accepts only IPv6
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
@scheme[tcp-accept], @scheme[tcp-accept-ready?], and
@scheme[tcp-close]. Each new TCP listener value is placed into the
@racket[tcp-accept], @racket[tcp-accept-ready?], and
@racket[tcp-close]. Each new TCP listener value is placed into the
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].}
@ -74,38 +74,38 @@ If the server cannot be started by @scheme[tcp-listen], the
(values input-port? output-port?)]{
Attempts to connect as a client to a listening server. The
@scheme[hostname] argument is the server host's Internet address name,
and @scheme[port-no] is the port number where the server is listening.
@racket[hostname] argument is the server host's Internet address name,
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
@scheme["localhost"] generally specifies the local machine.)
@racket["localhost"] generally specifies the local machine.)
The optional @scheme[local-hostname] and @scheme[local-port-no]
specify the client's address and port. If both are @scheme[#f] (the
The optional @racket[local-hostname] and @racket[local-port-no]
specify the client's address and port. If both are @racket[#f] (the
default), the client's address and port are selected automatically. If
@scheme[local-hostname] is not @scheme[#f], then
@scheme[local-port-no] must be non-@scheme[#f]. If
@scheme[local-port-no] is non-@scheme[#f] and @scheme[local-hostname]
is @scheme[#f], then the given port is used but the address is
@racket[local-hostname] is not @racket[#f], then
@racket[local-port-no] must be non-@racket[#f]. If
@racket[local-port-no] is non-@racket[#f] and @racket[local-hostname]
is @racket[#f], then the given port is used but the address is
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
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
client with @scheme[tcp-accept]. These ports are placed into the
a Racket program, it can obtain ports to communicate to the
client with @racket[tcp-accept]. These ports are placed into the
management of the current custodian (see @secref["custodians"]).
Initially, the returned input port is block-buffered, and the returned
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
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
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
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
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].}
@defproc[(tcp-connect/enable-break [hostname string?]
@ -129,49 +129,49 @@ If a connection cannot be established by @scheme[tcp-connect], the
#f)])
(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
disabled when @scheme[tcp-connect/enable-break] is called, then either
ports are returned or the @scheme[exn:break] exception is raised, but
disabled when @racket[tcp-connect/enable-break] is called, then either
ports are returned or the @racket[exn:break] exception is raised, but
not both.}
@defproc[(tcp-accept [listener tcp-listener?])
(values input-port? output-port?)]{
Accepts a client connection for the server associated with
@scheme[listener]. If no client connection is waiting on the
listening port, the call to @scheme[tcp-accept] will block. (See also
@scheme[tcp-accept-ready?].)
@racket[listener]. If no client connection is waiting on the
listening port, the call to @racket[tcp-accept] will block. (See also
@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
port and sent to the client through the output port. These ports are
placed into the management of the current custodian (see
@secref["custodians"]).
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].}
@defproc[(tcp-accept/enable-break [listener tcp-listener?])
(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
breaking is disabled when @scheme[tcp-accept/enable-break] is called,
then either ports are returned or the @scheme[exn:break] exception is
breaking is disabled when @racket[tcp-accept/enable-break] is called,
then either ports are returned or the @racket[exn:break] exception is
raised, but not both.}
@defproc[(tcp-accept-ready? [listener tcp-listener?]) boolean?]{
Tests whether an unaccepted client has connected to the server
associated with @scheme[listener]. If a client is
waiting, the return value is @scheme[#t], otherwise it is
@scheme[#f]. A client is accepted with the @scheme[tcp-accept]
associated with @racket[listener]. If a client is
waiting, the return value is @racket[#t], otherwise it is
@racket[#f]. A client is accepted with the @racket[tcp-accept]
procedure, which returns ports for communicating with the client and
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?]{
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
to accepted clients are unaffected.
If the listener has already been closed, the @exnraise[exn:fail:network].
The listener's port number may not become immediately available for
new listeners (with the default @scheme[reuse?] argument of
@scheme[tcp-listen]). For further information, see Stevens's
new listeners (with the default @racket[reuse?] argument of
@racket[tcp-listen]). For further information, see Stevens's
explanation of the @tt{TIME_WAIT} TCP state.}
@defproc[(tcp-listener? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] is a @tech{TCP listener} created by
@scheme[tcp-listen], @scheme[#f] otherwise.}
Returns @racket[#t] if @racket[v] is a @tech{TCP listener} created by
@racket[tcp-listen], @racket[#f] otherwise.}
@defproc[(tcp-accept-evt [listener tcp-listener?]) evt?]{
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
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
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?]{
Like @scheme[close-output-port] or @scheme[close-input-port]
(depending on whether @scheme[tcp-port] is an input or output port),
but if @scheme[tcp-port] is an output port and its associated input
Like @racket[close-output-port] or @racket[close-input-port]
(depending on whether @racket[tcp-port] is an input or output port),
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
not receive a TCP close message until the input port is also
closed.
The TCP protocol does not include a ``no longer reading'' state on
connections, so @scheme[tcp-abandon-port] is equivalent to
@scheme[close-input-port] on input @tech{TCP ports}.}
connections, so @racket[tcp-abandon-port] is equivalent to
@racket[close-input-port] on input @tech{TCP ports}.}
@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)
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
machine a viewed by the given @tech{TCP port}'s connection. (For most
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
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
@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
@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].}
@defproc[(tcp-port? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] is a @deftech{TCP port}---which is a
port returned by @scheme[tcp-accept], @scheme[tcp-connect],
@scheme[tcp-accept/enable-break], or
@scheme[tcp-connect/enable-break]---@scheme[#f] otherwise.}
Returns @racket[#t] if @racket[v] is a @deftech{TCP port}---which is a
port returned by @racket[tcp-accept], @racket[tcp-connect],
@racket[tcp-accept/enable-break], or
@racket[tcp-connect/enable-break]---@racket[#f] otherwise.}
@;------------------------------------------------------------------------
@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
bound or connected to any address or port.
If @scheme[family-hostname] or @scheme[family-port-no] is not
@scheme[#f], then the socket's protocol family is determined from
If @racket[family-hostname] or @racket[family-port-no] is not
@racket[#f], then the socket's protocol family is determined from
these arguments. The socket is @italic{not} bound to 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
ensures that the socket's protocol family is consistent with the
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
neither @scheme[family-hostname] nor @scheme[family-port-no] is
non-@scheme[#f], then the socket's protocol family is IPv4.}
neither @racket[family-hostname] nor @racket[family-port-no] is
non-@racket[#f], then the socket's protocol family is IPv4.}
@defproc[(udp-bind! [udp-socket udp?]
[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))])
void?]{
Binds an unbound @scheme[udp-socket] to the local port number
@scheme[port-no]. If @scheme[port-no] is 0 the @scheme[udp-socket] is
Binds an unbound @racket[udp-socket] to the local port number
@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
@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
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
name. For example, providing @scheme["127.0.0.1"] as
@scheme[hostname-string] typically creates a listener that
accepts only connections to @scheme["127.0.0.1"] from the local
name. For example, providing @racket["127.0.0.1"] as
@racket[hostname-string] typically creates a listener that
accepts only connections to @racket["127.0.0.1"] from the local
machine.
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
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
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
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:
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
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].}
@ -328,21 +328,21 @@ If @scheme[udp-socket] is already bound or closed, the
void?]{
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.
If @scheme[hostname-string] is @scheme[#f], then @scheme[port-no] also
must be @scheme[#f], and the port is disconnected (if connected). If
one of @scheme[hostname-string] or @scheme[port-no] is @scheme[#f] and
If @racket[hostname-string] is @racket[#f], then @racket[port-no] also
must be @racket[#f], and the port is disconnected (if connected). If
one of @racket[hostname-string] or @racket[port-no] is @racket[#f] and
the other is not, the @exnraise[exn:fail:contract].
A connected socket can be used with @scheme[udp-send] (not
@scheme[udp-send-to]), and it accepts datagrams only from the
A connected socket can be used with @racket[udp-send] (not
@racket[udp-send-to]), and it accepts datagrams only from the
connected address and port. A socket need not be connected to receive
datagrams. A socket can be connected, re-connected, and disconnected
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?]
@ -354,19 +354,19 @@ If @scheme[udp-socket] is closed, the @exnraise[exn:fail:network].}
[end-pos exact-nonnegative-integer? (bytes-length bstr)])
void]{
Sends @scheme[(subbytes bytes start-pos end-pos)] as a datagram from
the unconnected @scheme[udp-socket] to the socket at the remote
machine @scheme[hostname-address] on the port @scheme[port-no]. The
@scheme[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
Sends @racket[(subbytes bytes start-pos end-pos)] as a datagram from
the unconnected @racket[udp-socket] to the socket at the remote
machine @racket[hostname-address] on the port @racket[port-no]. The
@racket[udp-socket] need not be bound or connected; if it is not
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,
@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 @scheme[end-pos] is less than @scheme[start-pos] or greater than
the length of @scheme[bstr], the @exnraise[exn:fail:contract].
If @racket[start-pos] is greater than the length of @racket[bstr], or
if @racket[end-pos] is less than @racket[start-pos] or greater than
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].}
@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)])
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
@scheme[udp-socket] is closed or unconnected, the
@racket[udp-socket] is closed or unconnected, the
@exnraise[exn:fail:network].}
@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)])
boolean?]{
Like @scheme[udp-send-to], but never blocks; if the socket's outgoing
queue is too full to support the send, @scheme[#f] is returned,
otherwise the datagram is queued and the result is @scheme[#t].}
Like @racket[udp-send-to], but never blocks; if the socket's outgoing
queue is too full to support the send, @racket[#f] is returned,
otherwise the datagram is queued and the result is @racket[#t].}
@defproc[(udp-send* [udp-socket udp?]
[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)])
boolean?]{
Like @scheme[udp-send], except that (like @scheme[udp-send-to]) it
never blocks and returns @scheme[#f] or @scheme[#t].}
Like @racket[udp-send], except that (like @racket[udp-send-to]) it
never blocks and returns @racket[#f] or @racket[#t].}
@defproc[(udp-send-to/enable-break [udp-socket udp?]
[hostname string?]
@ -411,10 +411,10 @@ never blocks and returns @scheme[#f] or @scheme[#t].}
[end-pos exact-nonnegative-integer? (bytes-length bstr)])
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
breaking is disabled when @scheme[udp-send-to/enable-break] is called,
then either the datagram is sent or the @scheme[exn:break] exception
breaking is disabled when @racket[udp-send-to/enable-break] is called,
then either the datagram is sent or the @racket[exn:break] exception
is raised, but not both.}
@ -424,8 +424,8 @@ is raised, but not both.}
[end-pos exact-nonnegative-integer? (bytes-length bstr)])
void]{
Like @scheme[udp-send], except that breaks are enabled like
@scheme[udp-send-to/enable-break].}
Like @racket[udp-send], except that breaks are enabled like
@racket[udp-send-to/enable-break].}
@defproc[(udp-receive! [udp-socket udp?]
@ -436,24 +436,24 @@ Like @scheme[udp-send], except that breaks are enabled like
string?
(integer-in 1 65535))]{
Accepts up to @math{@scheme[end-pos]-@scheme[start-pos]} bytes of
@scheme[udp-socket]'s next incoming datagram into @scheme[bstr],
writing the datagram bytes starting at position @scheme[start-pos]
within @scheme[bstr]. The @scheme[udp-socket] must be bound to a local
Accepts up to @math{@racket[end-pos]-@racket[start-pos]} bytes of
@racket[udp-socket]'s next incoming datagram into @racket[bstr],
writing the datagram bytes starting at position @racket[start-pos]
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
is immediately available, @scheme[udp-receive!] blocks until one is
is immediately available, @racket[udp-receive!] blocks until one is
available.
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
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.
If @scheme[start-pos] is greater than the length of @scheme[bstr], or
if @scheme[end-pos] is less than @scheme[start-pos] or greater than
the length of @scheme[bstr], the @exnraise[exn:fail:contract].}
If @racket[start-pos] is greater than the length of @racket[bstr], or
if @racket[end-pos] is less than @racket[start-pos] or greater than
the length of @racket[bstr], the @exnraise[exn:fail:contract].}
@defproc[(udp-receive!* [udp-socket udp?]
[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 (integer-in 1 65535) #f))]{
Like @scheme[udp-receive!], except that it never blocks. If no
datagram is available, the three result values are all @scheme[#f].}
Like @racket[udp-receive!], except that it never blocks. If no
datagram is available, the three result values are all @racket[#f].}
@defproc[(udp-receive!/enable-break [udp-socket udp?]
[bstr (and/c bytes? (not immutable?))]
@ -474,48 +474,48 @@ datagram is available, the three result values are all @scheme[#f].}
string?
(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
breaking is disabled when @scheme[udp-receive!/enable-break] is
called, then either a datagram is received or the @scheme[exn:break]
breaking is disabled when @racket[udp-receive!/enable-break] is
called, then either a datagram is received or the @racket[exn:break]
exception is raised, but not both.}
@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].}
@defproc[(udp? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] is a socket created by
@scheme[udp-open-socket], @scheme[#f] otherwise.}
Returns @racket[#t] if @racket[v] is a socket created by
@racket[udp-open-socket], @racket[#f] otherwise.}
@defproc[(udp-bound? [udp-socket udp?]) boolean?]{
Returns @scheme[#t] if @scheme[udp-socket] is bound to a local address
and port, @scheme[#f] otherwise.}
Returns @racket[#t] if @racket[udp-socket] is bound to a local address
and port, @racket[#f] otherwise.}
@defproc[(udp-connected? [udp-socket udp?]) boolean?]{
Returns @scheme[#t] if @scheme[udp-socket] is connected to a remote
address and port, @scheme[#f] otherwise.}
Returns @racket[#t] if @racket[udp-socket] is connected to a remote
address and port, @racket[#f] otherwise.}
@defproc[(udp-send-ready-evt [udp-socket udp?]) evt?]{
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.}
@defproc[(udp-receive-ready-evt [udp-socket udp?]) evt?]{
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.}
@defproc[(udp-send-to-evt [udp-socket udp?]
@ -528,9 +528,9 @@ would block.}
evt?]{
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
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
@|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?]{
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
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
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
attempt.}
@ -557,12 +557,12 @@ attempt.}
evt?]{
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
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
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.)}
@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)
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
machine a viewed by the given @tech{UDP socket}'s connection. (For most
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
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
@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
@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].}

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))
@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]
@ -18,34 +18,34 @@
(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"].}
The @scheme[define-package] form is similar to @scheme[module], except
that it can appear in any definition context. The @scheme[form]s
within a @scheme[define-package] form can be definitions or
The @racket[define-package] form is similar to @racket[module], except
that it can appear in any definition context. The @racket[form]s
within a @racket[define-package] form can be definitions or
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
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]
forms are equivalent: exactly the listed @scheme[id]s are
exported. The @scheme[#:all-defined] form exports all definitions from
the package body, and @scheme[#:all-defined-except (id ...)] exports
all definitions except the listed @scheme[id]s.
The @racket[(id ...)] and @racket[#:only (id ...)] @racket[exports]
forms are equivalent: exactly the listed @racket[id]s are
exported. The @racket[#:all-defined] form exports all definitions from
the package body, and @racket[#:all-defined-except (id ...)] exports
all definitions except the listed @racket[id]s.
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
refer to each other). However, @scheme[define-package] handles
@scheme[define*], @scheme[define*-syntax], @scheme[define*-values],
@scheme[define*-syntaxes], and
@scheme[open*-package] specially: the bindings introduced by those
forms within a @scheme[define-package] body are visible only to
@scheme[form]s that appear later in the body, and they can shadow any
binding from preceding @scheme[form]s (even if the preceding binding
did not use one of the special @schemeidfont{*} definition forms). If
refer to each other). However, @racket[define-package] handles
@racket[define*], @racket[define*-syntax], @racket[define*-values],
@racket[define*-syntaxes], and
@racket[open*-package] specially: the bindings introduced by those
forms within a @racket[define-package] body are visible only to
@racket[form]s that appear later in the body, and they can shadow any
binding from preceding @racket[form]s (even if the preceding binding
did not use one of the special @racketidfont{*} definition forms). If
an exported identifier is defined multiple times, the last definition
is the exported one.
@ -70,17 +70,17 @@ little-russian-doll
@defform[(package-begin form ...)]{
Similar to @scheme[define-package], but it only limits the visible of
definitions without binding a package name. If the last @scheme[form]
Similar to @racket[define-package], but it only limits the visible of
definitions without binding a package name. If the last @racket[form]
is an expression, then the expression is in @tech{tail position} for
the @scheme[package-begin] form, so that its result is the
@scheme[package-begin] result.
the @racket[package-begin] form, so that its result is the
@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
definitions are essentially spliced into the enclosing context (though
the defined bindings remain hidden outside the
@scheme[package-begin]).
@racket[package-begin]).
@examples[
#:eval pack-eval
@ -98,10 +98,10 @@ secret
@defidform[open*-package]
)]{
Equivalent to @scheme[define], @scheme[define-values],
@scheme[define-syntax], @scheme[define-syntaxes],
and @scheme[open-package], except within a
@scheme[define-package] or @scheme[package-begin] form, where they
Equivalent to @racket[define], @racket[define-values],
@racket[define-syntax], @racket[define-syntaxes],
and @racket[open-package], except within a
@racket[define-package] or @racket[package-begin] form, where they
create bindings that are visible only to later body forms.
@examples[
@ -127,19 +127,19 @@ cookies
@defproc[(package-original-identifiers [id identifier?]) (listof identifier?)]
)]{
The @scheme[package?], @scheme[package-exported-identifiers], and
@scheme[package-original-identifiers] functions are exported
@scheme[for-syntax] by @schememodname[racket/package].
The @racket[package?], @racket[package-exported-identifiers], and
@racket[package-original-identifiers] functions are exported
@racket[for-syntax] by @racketmodname[racket/package].
The @scheme[package?] predicate returns @scheme[#t] if @scheme[v] is a
package value as obtained by @scheme[syntax-local-value] on an
The @racket[package?] predicate returns @racket[#t] if @racket[v] is a
package value as obtained by @racket[syntax-local-value] on an
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
bindings that would be introduced by opening the package in 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.}
@; ----------------------------------------------------------------------

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,
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?]{
@ -31,18 +28,18 @@ This includes multiple values and exceptions.}
@defform[(lazy body ...+)]{
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
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.
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.
This form useful for implementing lazy libraries and languages, where
tail-calls can be wrapped in a promise.}
The @scheme[lazy] form useful for implementing lazy libraries and
languages, where tail calls can be wrapped in a promise.}
@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
@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.}
@ -78,56 +72,74 @@ Returns @scheme[#t] if @scheme[promise] is currently being forced.
@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
cached. It is essentially a thunk, wrapped in a way that
@scheme[force] recognizes. Note that if a @scheme[delay/name] promise
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.
cached. This kind of promise is essentially a thunk that is wrapped
in a way that @scheme[force] recognizes.
Note that this promise is never considered ``running'' or ``forced''
in the sense of @scheme[promise-running?] and
@scheme[promise-forced?].}
If a @scheme[delay/name] promise forces itself, no exception is
raised, the promise is never considered ``running'' or ``forced'' in
the sense of @scheme[promise-running?] and @scheme[promise-forced?].}
@defform[(delay/sync body ...+)]{
Conventional promises are not useful when multiple threads attempt to
force them: when a promise is running, any additional threads that
@scheme[force] it will get an exception. @scheme[delay/sync] is
useful for such cases: if a second thread attempts to @scheme[force]
such a promise, it will get blocked until the computation is done and
an answer is available. If @scheme[force] is used with the promise as
it is forced from the same thread, an exception is raised.
Produces a promise where an attempt to @scheme[force] the promise by a
thread other than one currently running the promise causes the
@scheme[force] to block until a result is available. This kind of
promise is also a @tech{synchronizable event} for use with
@racket[sync]; @racket[sync]ing on the promise does not @scheme[force]
it, but merely waits until a value is forced by another thread.
In addition, these promises can be used with @scheme[sync], which
blocks until it has been forced. Note that using @scheme[sync] this
way is passive in the sense that it does not trigger evaluation of the
promise.}
If a promise created by @scheme[delay/sync] is forced on a thread that
is already running the promise, an exception is raised in the same way
as for promises created with @scheme[delay].}
@defform[(delay/thread body ...+)]{
@; TODO: document #:group keyword
@defform/subs[(delay/thread body/option ...+)
([body/option body
(code:line #:group thread-group-expr)])]{
This kind of promise begins the computation immediately, but this
happens on a separate thread. When the computation is done, the result
is cached as usual. Note that exceptions are caught as usual, and will
only be raised when @scheme[force]d. If such a promise is
@scheme[force]d before a value is ready, the calling thread will be
blocked until the computation terminates. These promises can also be
used with @scheme[sync].}
Like @scheme[delay/sync], but begins the computation immediately on a
newly created thread. The thread is created under the @tech{thread
group} specified by @scheme[thread-group-expr], which defaults to
@scheme[(make-thread-group)]. A @racket[#:group] specification can
appear at most once.
@defform[(delay/idle body ...+)]{
@; TODO: document #:wait-for, #:work-while, #:tick, #:use keywords
Exceptions raised by the @racket[body]s are caught as usual and raised
only when the promise is @scheme[force]d.}
Similar to @scheme[delay/thread], but the computation thread gets to
work only when the process is otherwise idle, as determined by
@scheme[system-idle-evt], and the work is done in small runtime
fragements, making it overall not raise total CPU use or hurt
responsiveness. If the promise is @scheme[forced] before the
computation is done, it will run the rest of the computation immediately
without slicing the runtime. Using @scheme[sync] on these promises
blocks as is the case with @scheme[delay/sync], and this happens in a
passive way too, so the computation continues to work in low-priority.
@defform/subs[(delay/idle body/option ...+)
([body/option body
(code:line #:wait-for wait-evt-expr)
(code:line #:work-while while-evt-expr)
(code:line #:tick tick-secs-expr)
(code:line #:use use-ratio-expr)])]{
Like @scheme[delay/thread], but with the following differences:
@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:

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 bytecode from files that are specified with
@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]
argument. (Note that this applies for loading bytecode files only,
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
of directly configuring the environment, so that the indicated modules
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
the @filepath{mzlib} @tech{collection}. A @filepath{.ss}
suffix is converted to @filepath{.rkt}. (This convention is for
compatibility with older version of PLT Racket.)
compatibility with older version of Racket.)
@examples[
(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
automatically, but a @filepath{.ss} suffix is converted to
@filepath{.rkt}. (This convention is for compatibility with older
version of PLT Racket.)
version of Racket.)
@examples[
(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}
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"].
When a thread is created, it is placed into the management of the
@tech{current custodian} and added to the current thread group (see
@secref["threadgroups"]). A thread can have any number of custodian
managers added through @racket[thread-resume].
@tech{current custodian} and added to the current @tech{thread
group}. A thread can have any number of custodian managers added
through @racket[thread-resume].
A thread that has not terminated can be garbage collected (see
@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]
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,
@scheme[vector-ref] checks its arguments to ensure that the first
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
system can crash or become corrupted.
All of the exported bindings of @schememodname[scheme] are protected
in the sense of @scheme[protect-out], so access to unsafe operations
can be prevented by adjusting the code inspector (see
All of the exported bindings of @schememodname[racket/unsafe/ops] are
protected in the sense of @scheme[protect-out], so access to unsafe
operations can be prevented by adjusting the code inspector (see
@secref["modprotect"]).
@section{Unsafe Numeric Operations}