doc work on reference

svn: r6879

collects/scribblings/reference/data.scrbl

@@ -80,7 +80,7 @@ although they may print the same as other symbols.
 Regular (interned) symbols are only weakly held by the internal symbol
 table. This weakness can never affect the result of an @scheme[eq?],
 @scheme[eqv?], or @scheme[equal?] test, but a symbol may disappear
-when placed into a weak box (see @secref["weakbox"]) used as the key
+when placed into a weak box (see @secref["mz:weakbox"]) used as the key
 in a weak hash table (see @secref["mz:hashtables"]), or used as an
 ephemeron key (see @secref["mz:ephemerons"]).
 

collects/scribblings/reference/file-ports.scrbl

@@ -56,7 +56,7 @@ closed, either though @scheme[close-input-port] or indirectly via
 handle. The input port will not closed automatically if it is
 otherwise available for garbage collection (see
 @secref["mz:gc-model"]); a @tech{will} could be associated input port
-to close it more automatically (see @secref["mz:wills"]).
+to close it more automatically (see @secref["mz:willexecutor"]).
 
 A @tech{path} value that is the expanded version of @scheme[path] is
 used as the name of the opened port.}
@@ -122,7 +122,7 @@ closed, either though @scheme[close-output-port] or indirectly via
 handle. The output port will not closed automatically if it is
 otherwise available for garbage collection (see
 @secref["mz:gc-model"]); a @tech{will} could be associated input port
-to close it more automatically (see @secref["mz:wills"]).
+to close it more automatically (see @secref["mz:willexecutor"]).
 
 A @tech{path} value that is the expanded version of @scheme[path] is
 used as the name of the opened port.}

collects/scribblings/reference/memory.scrbl

@@ -0,0 +1,185 @@
+#reader(lib "docreader.ss" "scribble")
+@require["mz.ss"]
+
+@title[#:tag "mz:memory" #:style 'toc]{Memory Management}
+
+@local-table-of-contents[]
+
+@section[#:tag "mz:weakbox"]{Weak Boxes}
+
+A @deftech{weak box} is similar to a normal box (see
+@secref["mz:boxes"]), but when the garbage collector (see
+@secref["mz: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 @deftech{weak reference} is a reference
+through a weak box, through a key reference in a weak hash table (see
+@secref["mz:hashtables"]), through a value in an ephemeron where the
+value can be replaced by @scheme[#f] (see @secref["mz:ephemeron"]), or
+through a custodian (see @secref["mz:custodians"]).
+
+@defproc[(make-weak-box [v any/c]) weak-box?]{
+
+Returns a new weak box that initially contains @scheme[v].}
+
+
+@defproc[(weak-box-value [weak-box weak-box?]) any]{
+
+Returns the value contained in @scheme[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.}
+
+@defproc[(weak-box? [v any/c]) boolean?]{
+
+Returns @scheme[#t] if @scheme[v] is a weak box, @scheme[#f] otherwise.}
+
+@;------------------------------------------------------------------------
+@section[#:tag "mz:ephemeron"]{Ephemerons}
+
+An @deftech{ephemeron} is similar to a weak box (see
+@secref["mz:weakbox"]), except that
+
+@itemize{
+
+ @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
+ either the ephemeron or the key is reachable only through weak
+ references (see @secref["mz:weakbox"]); and}
+
+ @item{nothing reachable from the value in an ephemeron counts toward
+ the reachability of an ephemeron key (whether for the same ephemeron
+ or another), unless the same value is reachable through a non-weak
+ reference, or unless the value's ephemeron key is reachable through a
+ non-weak reference (see @secref["mz:weakbox"] for information on weak
+ references).}
+
+}
+
+In particular, an ephemeron can be combined with a weak hash table
+(see @secref["mz:hashtables"]) to produce a mapping where the memory
+manager can reclaim key--value pairs even when the value refers to the
+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].}
+
+
+@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].}
+
+
+@defproc[(ephemeron? [v any/c]) boolean?]{
+
+Returns @scheme[#t] if @scheme[v] is an @tech{ephemeron}, @scheme[#f]
+otherwise.}
+
+@;------------------------------------------------------------------------
+@section[#:tag "mz:willexecutor"]{Wills and Executors}
+
+A @deftech{will executor} manages a collection of values and
+associated @deftech{will} procedures. The will procedure for each
+value is ready to be executed when the value has been proven (by the
+garbage collector) to be unreachable, except through weak references
+(see @secref["mz:weakbox"]) or as the registrant for other will
+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]
+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
+create a thread whose sole job is to execute wills for a particular
+executor.
+
+If a value is registered with multiple wills (in one or multiple
+executors), the wills are readied in the reverse order of
+registration. Since readying a will procedure makes the value
+reachable again, the will must be executed and the value must be
+proven again unreachable through only weak references before another
+of the wills is readied or executed.  However, wills for distinct
+unreachable values are readied at the same time, regardless of whether
+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["mz:weakbox"]) is registered with a will
+executor, the weak box's content is not changed to @scheme[#f] until
+all wills have been executed for the value and the value has been
+proven again reachable through only weak references.
+
+
+@defproc[(make-will-executor) will-executor?]{
+
+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]
+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
+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]
+call.  If no will is ready for immediate execution,
+@scheme[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.}
+
+@;------------------------------------------------------------------------
+@section[#:tag "mz:garbagecollection"]{Garbage Collection}
+
+@defproc[(collect-garbage) void?]{
+
+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
+timing of collections, but garbage will obviously be collected even if
+this procedure is never called.}
+
+@defproc[(current-memory-use [cust custodian? #f]) nonnegative-exact-integer?]{
+
+Returns an estimate of the number of bytes of memory occupied by
+reachable data from @scheme[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
+estimate is a total reachable from any custodians.
+
+When PLT Scheme 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?].}
+
+@defproc[(dump-memory-stats) any]{
+
+Dumps information about memory usage to the (low-level) standard
+output port.}
+

collects/scribblings/reference/model.scrbl

@@ -309,7 +309,7 @@ program. A program representation created with
 existing @tech{objects}.
 
 @;------------------------------------------------------------------------
-@section{Object Identity and Comparisons}
+@section[#:tag "mz:model-eq"]{Object Identity and Comparisons}
 
 The @scheme[eq?] operator compares two @tech{values}, returning
 @scheme[#t] when the values refer to the same @tech{object}. This form

collects/scribblings/reference/namespaces.scrbl

@@ -101,7 +101,7 @@ mapping is also adjusted (see @secref["mz:namespace-model"]) so that
          void?]{
 
 Removes the @scheme[sym] variable, if any, in the top-level
-environment of @scheme[namespace] at @tech{phase level 0}. The
+environment of @scheme[namespace] at @tech{phase level} 0. The
 namespace's identifier mapping (see @secref["mz:namespace-model"]) is
 unaffected.}
 

collects/scribblings/reference/port-buffers.scrbl

@@ -46,7 +46,7 @@ In addition, the initial current output and error ports are
 automatically flushed when @scheme[read], @scheme[read-line],
 @scheme[read-bytes], @scheme[read-string], etc. are performed on the
 initial standard input port; more precisely, flushing is performed by
-the default port read handler (see @secref["mz:portreadhandler"]).
+the default port read handler (see @scheme[port-read-handler]).
 
 @defproc[(flush-output [out output-port? (current-output-port)]) void?]{
 

collects/scribblings/reference/procedures.scrbl

@@ -172,7 +172,7 @@ immutability of procedure fields disallows cycles in the procedure
 graph, so that the procedure call will eventually continue with a
 non-structure procedure.) That procedure receives all of the arguments
 from the application expression. The procedure's name (see
-@secref["mz:infernames"]) and arity (see @secref["mz:arity"]) are also
+@scheme[object-name]) and arity (see @scheme[procedure-arity]) are also
 used for the name and arity of the structure. If the value in the
 designated field is not a procedure, then the instance behaves like
 @scheme[(case-lambda)] (i.e., a procedure which does not accept any
@@ -203,7 +203,7 @@ called with the instance as the first argument. The remaining
 arguments to the property-value procedure are the arguments from the
 application expression. Thus, if the application expression contained
 five arguments, the property-value procedure is called with six
-arguments. The name of the instance (see @secref["mz:infernames"]) is
+arguments. The name of the instance (see @scheme[object-name]) is
 unaffected by the property-value procedure, but the instance's arity
 is determined by subtracting one from every possible argument count of
 the property-value procedure. If the property-value procedure cannot

collects/scribblings/reference/reference.scrbl

@@ -24,6 +24,7 @@ language.
 @include-section["security.scrbl"]
 @include-section["io.scrbl"]
 @include-section["os.scrbl"]
+@include-section["memory.scrbl"]
 
 @;------------------------------------------------------------------------
 

collects/scribblings/reference/regexps.scrbl

@@ -111,7 +111,7 @@ is used multiple times, it is faster to compile the string once to a
 regexp value and use it for repeated matches instead of using the
 string each time.
 
-The @scheme[object-name] procedure (see @secref["mz:infernames"]) returns
+The @scheme[object-name] procedure returns
 the source string for a regexp value.
 
 @examples[
@@ -147,7 +147,7 @@ Takes a byte-string representation of a regular expression (using the
 syntax in @secref["mz:regexp-syntax"]) and compiles it into a
 byte-regexp value.
 
-The @scheme[object-name] procedure (see @secref["mz:infernames"])
+The @scheme[object-name] procedure
 returns the source byte string for a regexp value.
 
 @examples[

collects/scribblings/reference/syntax.scrbl

@@ -1076,7 +1076,7 @@ the symbolic form of the identifier bound within the module:
 
 If @scheme[provide] wraps a @scheme[provide-spec], then the exports of
 the @scheme[provide-spec] are protected; see
-@secref["mz:protected-exports"]. The @scheme[provide-spec] must
+@secref["mz:modprotect"]. The @scheme[provide-spec] must
 specify only bindings that are defined within the exporting module.
 
 Each export specified within a module must have a distinct symbolic

collects/scribblings/reference/threads.scrbl

@@ -30,7 +30,7 @@ thread-safe because they are @defterm{atomic}. For example,
 to all threads, so that no thread can see a ``half-assigned''
 variable. Similarly, @scheme[vector-set!] assigns to a vector
 atomically. The @scheme[hash-table-put!] procedure is not atomic, but
-the table is protected by a lock; see @secref["mz:hashtable"] for more
+the table is protected by a lock; see @secref["mz:hashtables"] for more
 information. Port operations are generally not atomic, but they are
 thread-safe in the sense that a byte consumed by one thread from an
 input port will not be returned also to another thread, and procedures

collects/scribblings/reference/write.scrbl

@@ -161,7 +161,7 @@ A parameter that controls printing box values; defaults to
 @defboolparam[print-vector-length on?]{
 
 A parameter that controls printing vectors; defaults to
-@scheme[#t]. See @secref["mz:print-vector"] for more information.}
+@scheme[#t]. See @secref["mz:print-vectors"] for more information.}
 
 @defboolparam[print-hash-table on?]{