diff --git a/pkgs/racket-doc/scribblings/reference/memory.scrbl b/pkgs/racket-doc/scribblings/reference/memory.scrbl index ec2aff18a9..685883cd78 100644 --- a/pkgs/racket-doc/scribblings/reference/memory.scrbl +++ b/pkgs/racket-doc/scribblings/reference/memory.scrbl @@ -1,5 +1,6 @@ -#lang scribble/doc -@(require "mz.rkt") +#lang scribble/manual +@(require "mz.rkt" + scribble/bnf) @title[#:tag "memory" #:style 'toc]{Memory Management} @@ -215,28 +216,74 @@ with additional fields: #:prefab) ] -The @racket[major?] field indicates whether the collection was a -``major'' collection that inspects all memory or a ``minor'' -collection that mostly inspects just recent allocations. The -@racket[pre-amount] field reports place-local memory use (i.e., not -counting the memory use of child places) in bytes at the time that the -@tech{garbage collection} started. The @racket[pre-admin-amount] is a -larger number that includes memory use for the garbage collector's -overhead (such as space on memory pages that is not yet used). The -@racket[code-amount] field reports additional memory use for generated -native code (which is the same just before and after a garbage -collection, since it is released via finalization). The -@racket[post-amount] and @racket[post-admin-amount] fields correspond -to @racket[pre-amount] and @racket[pre-admin-amount], but after garbage -collection. The @racket[start-process-time] and -@racket[end-process-time] fields report processor time (in the sense -of @racket[current-process-milliseconds]) at the start and end of -garbage collection; the difference is the processor time consumed by -collection. The @racket[start-time] and @racket[end-time] fields -report real time (in the sense of -@racket[current-inexact-milliseconds]) at the start and end of garbage -collection; the difference is the real time consumed by garbage -collection. +@itemlist[ + + @item{The @racket[major?] field indicates whether the collection was + a ``major'' collection that inspects all memory or a ``minor'' + collection that mostly inspects just recent allocations.} + + @item{The @racket[pre-amount] field reports place-local memory use + (i.e., not counting the memory use of child places) in bytes at + the time that the @tech{garbage collection} started.} + + @item{The @racket[pre-admin-amount] is a larger number that includes + memory use for the garbage collector's overhead, such as space + on memory pages that are mapped but not currently used.} + + @item{The @racket[code-amount] field reports additional memory use + for generated native code (which is the same just before and + after a garbage collection, since it is released via + finalization).} + + @item{The @racket[post-amount] and @racket[post-admin-amount] fields + correspond to @racket[pre-amount] and + @racket[pre-admin-amount], but after garbage collection. In + typical configurations, the difference between + @racket[post-amount] and @racket[pre-amount] contributes to + @racket[post-admin-amount], since reclaimed pages tend to stay + in reserve with the expectation that they'll be needed again + (but the pages are released if multiple collections pass + without need for the pages).} + + @item{The @racket[start-process-time] and @racket[end-process-time] + fields report processor time (in the sense of + @racket[current-process-milliseconds]) at the start and end of + garbage collection. The difference between the times is the + processor time consumed by collection.} + + @item{The @racket[start-time] and @racket[end-time] fields report + real time (in the sense of + @racket[current-inexact-milliseconds]) at the start and end of + garbage collection. The difference between the times is the + real time consumed by garbage collection.} + +] + +The format of the logged message's text is subject to change. +Currently, after a prefix that indicates the @tech{place} and +collection mode, the text has the format + +@nested[#:style 'inset]{ + @tt{@nonterm{used}(@nonterm{admin})[@nonterm{code}]; @; + free @nonterm{reclaimed}(@nonterm{adjust}) @nonterm{elapsed} @"@" @nonterm{timestamp}} + +@tabular[ + #:sep (hspace 1) + (list (list @nonterm{used} + @elem{Collectable memory in use just prior to garbage collection}) + (list @nonterm{admin} + @elem{Additional memory used as to manage collectable memory}) + (list @nonterm{code} + @elem{Additional memory used for generated machine code}) + (list @nonterm{reclaimed} + @elem{Collectable memory reclaimed by garbage collection}) + (list @nonterm{adjust} + @elem{Negation of change to administrative memory minus @nonterm{reclaimed}}) + (list @nonterm{elapsed} + @elem{Processor time used to perform garbage collection}) + (list @nonterm{timestamp} + @elem{Processor time since startup of garbage collection's start})) +]} @defproc[(collect-garbage) void?]{