From f11b46828ca86f74408142063d02005ccc0a2352 Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Tue, 2 Dec 2008 20:26:32 +0000 Subject: [PATCH] some doc clarifications and hyperlinks svn: r12682 --- collects/scribblings/reference/bytes.scrbl | 6 +-- .../scribblings/reference/custodians.scrbl | 34 ++++++++++++----- .../scribblings/reference/eval-model.scrbl | 14 +++---- .../scribblings/reference/networking.scrbl | 37 +++++++++---------- 4 files changed, 51 insertions(+), 40 deletions(-) diff --git a/collects/scribblings/reference/bytes.scrbl b/collects/scribblings/reference/bytes.scrbl index b1343663f6..a8273f9e88 100644 --- a/collects/scribblings/reference/bytes.scrbl +++ b/collects/scribblings/reference/bytes.scrbl @@ -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]{ diff --git a/collects/scribblings/reference/custodians.scrbl b/collects/scribblings/reference/custodians.scrbl index dbe7a5db2d..69e5a66a76 100644 --- a/collects/scribblings/reference/custodians.scrbl +++ b/collects/scribblings/reference/custodians.scrbl @@ -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 diff --git a/collects/scribblings/reference/eval-model.scrbl b/collects/scribblings/reference/eval-model.scrbl index 2c75b4300c..4cd934cbe6 100644 --- a/collects/scribblings/reference/eval-model.scrbl +++ b/collects/scribblings/reference/eval-model.scrbl @@ -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 diff --git a/collects/scribblings/reference/networking.scrbl b/collects/scribblings/reference/networking.scrbl index 71f30d3a66..64e918e35a 100644 --- a/collects/scribblings/reference/networking.scrbl +++ b/collects/scribblings/reference/networking.scrbl @@ -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.