diff --git a/collects/scribblings/reference/data.scrbl b/collects/scribblings/reference/data.scrbl index a4985df0b9..b1f94b4b60 100644 --- a/collects/scribblings/reference/data.scrbl +++ b/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"]). diff --git a/collects/scribblings/reference/file-ports.scrbl b/collects/scribblings/reference/file-ports.scrbl index 724d5529d3..93243f9e97 100644 --- a/collects/scribblings/reference/file-ports.scrbl +++ b/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.} diff --git a/collects/scribblings/reference/memory.scrbl b/collects/scribblings/reference/memory.scrbl new file mode 100644 index 0000000000..5fe5a3aeec --- /dev/null +++ b/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.} + diff --git a/collects/scribblings/reference/model.scrbl b/collects/scribblings/reference/model.scrbl index 9a3909ef85..e47e3f1082 100644 --- a/collects/scribblings/reference/model.scrbl +++ b/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 diff --git a/collects/scribblings/reference/namespaces.scrbl b/collects/scribblings/reference/namespaces.scrbl index 1eb7157c66..2c58c1c2ac 100644 --- a/collects/scribblings/reference/namespaces.scrbl +++ b/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.} diff --git a/collects/scribblings/reference/port-buffers.scrbl b/collects/scribblings/reference/port-buffers.scrbl index af8f9aaa82..84d11b10fe 100644 --- a/collects/scribblings/reference/port-buffers.scrbl +++ b/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?]{ diff --git a/collects/scribblings/reference/procedures.scrbl b/collects/scribblings/reference/procedures.scrbl index da45e757b0..0115b4c9c1 100644 --- a/collects/scribblings/reference/procedures.scrbl +++ b/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 diff --git a/collects/scribblings/reference/reference.scrbl b/collects/scribblings/reference/reference.scrbl index 67a0770409..f95b14bad1 100644 --- a/collects/scribblings/reference/reference.scrbl +++ b/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"] @;------------------------------------------------------------------------ diff --git a/collects/scribblings/reference/regexps.scrbl b/collects/scribblings/reference/regexps.scrbl index 006d143a35..3e921262db 100644 --- a/collects/scribblings/reference/regexps.scrbl +++ b/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[ diff --git a/collects/scribblings/reference/syntax.scrbl b/collects/scribblings/reference/syntax.scrbl index 8f5275b6a4..fadd0566db 100644 --- a/collects/scribblings/reference/syntax.scrbl +++ b/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 diff --git a/collects/scribblings/reference/threads.scrbl b/collects/scribblings/reference/threads.scrbl index 7bdabb7cb3..859b95014d 100644 --- a/collects/scribblings/reference/threads.scrbl +++ b/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 diff --git a/collects/scribblings/reference/write.scrbl b/collects/scribblings/reference/write.scrbl index d2691c8bf8..1bfc702445 100644 --- a/collects/scribblings/reference/write.scrbl +++ b/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?]{