some doc clarifications and hyperlinks
svn: r12682
This commit is contained in:
Matthew Flatt
parent
2648a3b03f
commit
f11b46828c
|
|
@ -335,7 +335,7 @@ string.
|
|||
@defproc[(bytes-open-converter [from-name string?][to-name string?])
|
||||
bytes-converter?]{
|
||||
|
||||
Produces a string converter to go from the encoding named by
|
||||
Produces a @deftech{byte converter} to go from the encoding named by
|
||||
@scheme[from-name] to the encoding named by @scheme[to-name]. If the
|
||||
requested conversion pair is not available, @scheme[#f] is returned
|
||||
instead of a converter.
|
||||
|
|
@ -534,8 +534,8 @@ The result of @scheme[bytes-convert-end] is two values:
|
|||
|
||||
@defproc[(bytes-converter? [v any/c]) boolean?]{
|
||||
|
||||
Returns @scheme[#t] if @scheme[v] is a byte converter produced by
|
||||
@scheme[bytes-open-converter], @scheme[#f] otherwise.}
|
||||
Returns @scheme[#t] if @scheme[v] is a @tech{byte converter} produced
|
||||
by @scheme[bytes-open-converter], @scheme[#f] otherwise.}
|
||||
|
||||
|
||||
@defproc[(locale-string-encoding) any]{
|
||||
|
|
|
|||
|
|
@ -1,6 +1,8 @@
|
|||
#lang scribble/doc
|
||||
@(require "mz.ss")
|
||||
|
||||
@(define eventspaces @tech[#:doc '(lib "scribblings/gui/gui.scrbl")]{eventspaces})
|
||||
|
||||
@title[#:tag "custodians"]{Custodians}
|
||||
|
||||
See @secref["custodian-model"] for basic information on the PLT
|
||||
|
|
@ -22,8 +24,13 @@ automatically directed to shut down its managed values as well.}
|
|||
|
||||
@defproc[(custodian-shutdown-all [cust custodian?]) void?]{
|
||||
|
||||
Closes all open ports and closes all active TCP listeners and UDP
|
||||
sockets that are managed by @scheme[cust]. It also removes
|
||||
@margin-note{In MrEd, @|eventspaces| managed by @scheme[cust] are also
|
||||
shut down.}
|
||||
|
||||
Closes all @tech{file-stream ports}, @tech{TCP ports}, @tech{TCP
|
||||
listeners}, and @tech{UDP sockets} that are managed by @scheme[cust]
|
||||
(and its subordinates), and empties all @tech{custodian box}es
|
||||
associated with @scheme[cust] (and its subordinates). It also removes
|
||||
@scheme[cust] (and its subordinates) as managers of all threads; when
|
||||
a thread has no managers, it is killed (or suspended; see
|
||||
@scheme[thread/suspend-to-kill]) If the current thread is to be
|
||||
|
|
@ -33,18 +40,20 @@ thread.}
|
|||
|
||||
@defparam[current-custodian cust custodian?]{
|
||||
|
||||
@margin-note{In MrEd, custodians also manage @|eventspaces|.}
|
||||
|
||||
A parameter that determines a custodian that assumes responsibility
|
||||
for newly created threads, ports, TCP listeners, UDP sockets, and
|
||||
byte converters.}
|
||||
for newly created threads, @tech{file-stream ports}, TCP ports,
|
||||
@tech{TCP listeners}, @tech{UDP sockets}, and @tech{byte converters}.}
|
||||
|
||||
|
||||
@defproc[(custodian-managed-list [cust custodian?][super custodian?]) list?]{
|
||||
|
||||
Returns a list of immediately managed objects and subordinate
|
||||
custodians for @scheme[cust], where @scheme[cust] is itself
|
||||
subordinate to @scheme[super] (directly or indirectly). If
|
||||
@scheme[cust] is not strictly subordinate to @scheme[super], the
|
||||
@exnraise[exn:fail:contract].}
|
||||
Returns a list of immediately managed objects (not including
|
||||
@tech{custodian box}es) and subordinate custodians for @scheme[cust],
|
||||
where @scheme[cust] is itself subordinate to @scheme[super] (directly
|
||||
or indirectly). If @scheme[cust] is not strictly subordinate to
|
||||
@scheme[super], the @exnraise[exn:fail:contract].}
|
||||
|
||||
@defproc[(custodian-memory-accounting-available?) boolean?]{
|
||||
|
||||
|
|
@ -81,6 +90,11 @@ after garbage collection (see @secref["gc-model"]) where
|
|||
@scheme[limit-cust] owns more than @scheme[limit-amt] bytes, then
|
||||
@scheme[stop-cust] is shut down.
|
||||
|
||||
@margin-note{A custodian's limit is checked only after a garbage
|
||||
collection, except that it may also be checked during
|
||||
certain large allocations that are individually larger
|
||||
than the custodian's limit.}
|
||||
|
||||
For reliable shutdown, @scheme[limit-amt] for
|
||||
@scheme[custodian-limit-memory] must be much lower than the total
|
||||
amount of memory available (minus the size of memory that is
|
||||
|
|
@ -93,7 +107,7 @@ immediate allocations can be rejected with an
|
|||
|
||||
@defproc[(make-custodian-box [cust custodian?][v any/c]) custodian-box?]{
|
||||
|
||||
Returns a @deftech{custodian box} that contains @scheme[v] as long as
|
||||
Returns a @tech{custodian box} that contains @scheme[v] as long as
|
||||
@scheme[cust] has not been shut down.}
|
||||
|
||||
@defproc[(custodian-box? [v any/c]) boolean?]{Returns @scheme[#t] if
|
||||
|
|
|
|||
|
|
@ -744,12 +744,12 @@ outermost frame of the continuation for any new thread.
|
|||
|
||||
@margin-note/ref{See @secref["custodians"] for custodian functions.}
|
||||
|
||||
A @deftech{custodian} manages a collection of threads, file-stream
|
||||
ports, TCP ports, TCP listeners, UDP sockets, and byte converters.
|
||||
Whenever a thread, file-stream port, TCP port, TCP listener, or UDP
|
||||
socket is created, it is placed under the management of the
|
||||
@deftech{current custodian} as determined by the
|
||||
@scheme[current-custodian] @tech{parameter}.
|
||||
A @deftech{custodian} manages a collection of threads,
|
||||
@tech{file-stream ports}, TCP ports, @tech{TCP listeners}, @tech{UDP
|
||||
sockets}, and @tech{byte converters}. Whenever a thread, etc. is
|
||||
created, it is placed under the management of the @deftech{current
|
||||
custodian} as determined by the @scheme[current-custodian]
|
||||
@tech{parameter}.
|
||||
|
||||
@margin-note{In MrEd, custodians also manage eventspaces.}
|
||||
|
||||
|
|
@ -785,7 +785,7 @@ collected, at which point its subordinates become immediately
|
|||
subordinate to the collected custodian's superordinate custodian.
|
||||
|
||||
In addition to the other entities managed by a custodian, a
|
||||
@defterm{custodian box} created with @scheme[make-custodian-box]
|
||||
@deftech{custodian box} created with @scheme[make-custodian-box]
|
||||
strongly holds onto a value placed in the box until the box's
|
||||
custodian is shut down. The custodian only weakly retains the box
|
||||
itself, however (so the box and its content can be collected if there
|
||||
|
|
|
|||
|
|
@ -51,11 +51,11 @@ 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 TCP listener value. 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 management of the current custodian
|
||||
(see @secref["custodians"]).
|
||||
The return value of @scheme[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
|
||||
management of the current custodian (see @secref["custodians"]).
|
||||
|
||||
If the server cannot be started by @scheme[tcp-listen], the
|
||||
@exnraise[exn:fail:network].}
|
||||
|
|
@ -137,8 +137,7 @@ not both.}
|
|||
(values input-port? output-port?)]{
|
||||
|
||||
Accepts a client connection for the server associated with
|
||||
@scheme[listener], which is a TCP listener value returned by
|
||||
@scheme[tcp-listen]. If no client connection is waiting on the
|
||||
@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?].)
|
||||
|
||||
|
|
@ -168,8 +167,7 @@ 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]. The @scheme[listener] argument is a
|
||||
TCP listener value returned by @scheme[tcp-listen]. If a client is
|
||||
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]
|
||||
procedure, which returns ports for communicating with the client and
|
||||
|
|
@ -180,10 +178,9 @@ 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]. The
|
||||
@scheme[listener] argument is a TCP listener value returned by
|
||||
@scheme[tcp-listen]. All unaccepted clients receive an end-of-file
|
||||
from the server; connections to accepted clients are unaffected.
|
||||
Shuts down the server associated with @scheme[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].
|
||||
|
||||
|
|
@ -195,7 +192,7 @@ explanation of the @tt{TIME_WAIT} TCP state.}
|
|||
|
||||
@defproc[(tcp-listener? [v any/c]) boolean?]{
|
||||
|
||||
Returns @scheme[#t] if @scheme[v] is a TCP listener value created by
|
||||
Returns @scheme[#t] if @scheme[v] is a @tech{TCP listener} created by
|
||||
@scheme[tcp-listen], @scheme[#f] otherwise.}
|
||||
|
||||
|
||||
|
|
@ -220,7 +217,7 @@ 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 TCP ports.}
|
||||
@scheme[close-input-port] on input @tech{TCP ports}.}
|
||||
|
||||
|
||||
@defproc[(tcp-addresses [tcp-port tcp-port?]
|
||||
|
|
@ -231,7 +228,7 @@ connections, so @scheme[tcp-abandon-port] is equivalent to
|
|||
|
||||
Returns two strings when @scheme[port-numbers?] is @scheme[#f] (the
|
||||
default). The first string is the Internet address for the local
|
||||
machine a viewed by the given TCP port's connection. (For most
|
||||
machine a viewed by the given @tech{TCP port}'s connection. (For most
|
||||
machines, the answer corresponds to the current machine's only
|
||||
Internet address, but when a machine serves multiple addresses, the
|
||||
result is connection-specific.) The second string is the Internet
|
||||
|
|
@ -248,10 +245,10 @@ 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 port returned by
|
||||
@scheme[tcp-accept], @scheme[tcp-connect],
|
||||
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.}
|
||||
@scheme[tcp-connect/enable-break]---@scheme[#f] otherwise.}
|
||||
|
||||
@;------------------------------------------------------------------------
|
||||
@section[#:tag "udp"]{UDP}
|
||||
|
|
@ -265,7 +262,7 @@ Volume 1} by W. Richard Stevens.
|
|||
[family-port-no (or/c string? #f) #f])
|
||||
udp?]{
|
||||
|
||||
Creates and returns a UDP socket to send and receive
|
||||
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.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user