docs: update BC and CS references
Replace "3m and/or CGC" with "BC", use "implementation" instead of "variant", add a section on implementations to the reference, update corners where the documentation suggests that BC/3m is the default, and generally order CS first.
This commit is contained in:
Matthew Flatt
parent
32d3c8b607
commit
936ac2bf75
|
|
@ -453,7 +453,8 @@ convenience) can be used directly as a pointer value (unlike character
|
|||
strings, which are always copied for UTF-8 encoding or decoding).
|
||||
|
||||
For more information about memory management and garbage collection,
|
||||
see @secref[#:doc InsideRacket-doc "im:memoryalloc"] in
|
||||
see @secref[#:doc InsideRacket-doc "cs-memory"]
|
||||
and @secref[#:doc InsideRacket-doc "im:memoryalloc"] in
|
||||
@|InsideRacket|.
|
||||
|
||||
@; --------------------------------------------------
|
||||
|
|
|
|||
|
|
@ -61,10 +61,10 @@ memory that is (assumed to be) managed by the garbage collector,
|
|||
@racket[#f] otherwise.
|
||||
|
||||
For a pointer based on @racket[_gcpointer] as a result type,
|
||||
@racket[cpointer-gcable?] will return @racket[#t]. In the @3m[] and
|
||||
@CGC[] variants of Racket, @racket[cpointer-gcable?] will return
|
||||
@racket[cpointer-gcable?] will return @racket[#t]. In the @BC[]
|
||||
implementation of Racket, @racket[cpointer-gcable?] will return
|
||||
@racket[#f] for a pointer based on @racket[_pointer] as a result type.
|
||||
The @CS[] variant is mostly the sane, except that if a pointer is
|
||||
The @CS[] implementation is mostly the same, except that if a pointer is
|
||||
extracted using the @racket[_pointer] type from memory allocated as
|
||||
@racket['nonatomic], @racket[cpointer-gcable?] will report @racket[#t]
|
||||
for the extracted pointer.}
|
||||
|
|
@ -262,7 +262,7 @@ specification is required at minimum:
|
|||
garbage collector. The initial content of the memory is
|
||||
unspecified.
|
||||
|
||||
For the @3m[] and @CGC[] Racket variants, this allocation mode corresponds
|
||||
For the @BC[] Racket implementation, this allocation mode corresponds
|
||||
to @cpp{scheme_malloc_atomic} in the C API.}
|
||||
|
||||
@item{@indexed-racket['nonatomic] --- Allocates memory that can
|
||||
|
|
@ -270,10 +270,10 @@ specification is required at minimum:
|
|||
garbage collector as holding only pointers, and is initially
|
||||
filled with zeros.
|
||||
|
||||
For the @3m[] and @CGC[] Racket variants, this allocation mode corresponds
|
||||
For the @BC[] Racket implementation, this allocation mode corresponds
|
||||
to @cpp{scheme_malloc} in the C API.
|
||||
|
||||
For the @CS[] Racket variant, this mode is of limited use,
|
||||
For the @CS[] Racket implementation, this mode is of limited use,
|
||||
because a pointer allocated this way cannot be passed to
|
||||
foreign functions that expect a pointer to pointers. The result
|
||||
can only be used with functions like @racket[ptr-set!] and
|
||||
|
|
@ -284,7 +284,7 @@ specification is required at minimum:
|
|||
the garbage collector as long as the allocated object is
|
||||
retained.
|
||||
|
||||
For the @3m[] and @CGC[] Racket variants, a reference can point
|
||||
For the @BC[] Racket implementation, a reference can point
|
||||
to the interior of the object, instead of its starting address.
|
||||
This allocation mode corresponds to
|
||||
@cpp{scheme_malloc_atomic_allow_interior} in the C API.}
|
||||
|
|
@ -294,7 +294,7 @@ specification is required at minimum:
|
|||
by the garbage collector as long as the allocated object is
|
||||
retained.
|
||||
|
||||
This mode is supported only for the @3m[] and @CGC[] Racket variants, and
|
||||
This mode is supported only for the @BC[] Racket implementation, and
|
||||
it corresponds to @cpp{scheme_malloc_allow_interior} in the C
|
||||
API.}
|
||||
|
||||
|
|
@ -302,14 +302,14 @@ specification is required at minimum:
|
|||
start with a @tt{short} value that is registered as a tag with
|
||||
the garbage collector.
|
||||
|
||||
This mode is supported only for the @3m[] and @CGC[] Racket variants, and
|
||||
This mode is supported only for the @BC[] Racket implementation, and
|
||||
it corresponds to @cpp{scheme_malloc_tagged} in the C API.}
|
||||
|
||||
@item{@indexed-racket['stubborn] --- Like @racket['nonatomic],
|
||||
but supports a hint to the GC via @racket[end-stubborn-change]
|
||||
after all changes to the object have been made.
|
||||
|
||||
This mode is supported only for the @3m[] and @CGC[] Racket variants, and
|
||||
This mode is supported only for the @BC[] Racket implementation, and
|
||||
it corresponds to @cpp{scheme_malloc_stubborn} in the C API.}
|
||||
|
||||
@item{@indexed-racket['eternal] --- Like @racket['raw], except the
|
||||
|
|
@ -468,8 +468,8 @@ use by such finalizers.}
|
|||
bytes?]{
|
||||
|
||||
Returns a byte string made of the given pointer and the given length
|
||||
in the @3m[] and @CGC[] variants of Racket; no copying is performed.
|
||||
In the @CS[] variant, the @racket[exn:fail:unsupported] exception is
|
||||
in the @BC[] implementation of Racket; no copying is performed.
|
||||
In the @CS[] implementation, the @racket[exn:fail:unsupported] exception is
|
||||
raised.
|
||||
|
||||
Beware that the representation of a Racket byte string normally
|
||||
|
|
|
|||
|
|
@ -284,15 +284,15 @@ converting between byte strings and C's @cpp{char*} type.
|
|||
A type for UCS-4 format strings that include a nul terminator. As
|
||||
usual, the type treats @racket[#f] as @cpp{NULL} and vice versa.
|
||||
|
||||
For the @3m[] and @CGC[] variants of Racket, the conversion of a
|
||||
For the @CS[] implementation of Racket, the conversion of a Racket string for
|
||||
the foreign side is a copy of the Racket representation, where the
|
||||
copy is managed by the garbage collector.
|
||||
|
||||
For the @BC[] implementation of Racket, the conversion of a
|
||||
Racket string for the foreign side shares memory with the Racket
|
||||
string representation, since UCS-4 is the native representation format
|
||||
for those variants. The foreign pointer corresponds to the
|
||||
@cpp{mzchar*} type in Racket's C API.
|
||||
|
||||
For the @CS[] variant of Racket, the conversion of a Racket string for
|
||||
the foreign side is a copy of the Racket representation, where the
|
||||
copy is managed by the garbage collector.}
|
||||
@cpp{mzchar*} type in Racket's C API.}
|
||||
|
||||
|
||||
@deftogether[(
|
||||
|
|
@ -313,9 +313,9 @@ Simple @cpp{char*} strings that are nul terminated, corresponding to
|
|||
Racket's @tech[#:doc reference.scrbl]{path or string}. As usual, the
|
||||
type treats @racket[#f] as @cpp{NULL} and vice versa.
|
||||
|
||||
For the @3m[] and @CGC[] variants of Racket, the conversion of a
|
||||
For the @BC[] implementation of Racket, the conversion of a
|
||||
Racket path for the foreign side shares memory with the Racket path
|
||||
representation. Otherwise (for the @CS[] variant or for Racket
|
||||
representation. Otherwise (for the @CS[] implementation or for Racket
|
||||
strings), conversion for the foreign side creates a copy that is
|
||||
managed by the garbage collector.
|
||||
|
||||
|
|
@ -332,15 +332,15 @@ Simple @cpp{char*} strings as Racket symbols (encoded in UTF-8 and nul
|
|||
terminated), intended as read-only for the foreign side. Return values
|
||||
using this type are interned as symbols.
|
||||
|
||||
For the @3m[] and @CGC[] variants of Racket, the conversion of a
|
||||
For the @CS[] implementation of Racket, the conversion of a Racket symbol for
|
||||
the foreign side is a copy of the Racket representation, where the
|
||||
copy is managed by the garbage collector.
|
||||
|
||||
For the @BC[] implementation of Racket, the conversion of a
|
||||
Racket symbol for the foreign side shares memory with the Racket
|
||||
symbol representation, but points to the middle of the symbol's
|
||||
allocated memory---so the string pointer must not be used across a
|
||||
garbage collection.
|
||||
|
||||
For the @CS[] variant of Racket, the conversion of a Racket symbol for
|
||||
the foreign side is a copy of the Racket representation, where the
|
||||
copy is managed by the garbage collector.}
|
||||
garbage collection.}
|
||||
|
||||
|
||||
@subsection{Fixed Auto-Converting String Types}
|
||||
|
|
@ -446,7 +446,7 @@ The same as @racket[_pointer] as an argument type, but as a result
|
|||
type, @racket[_gcpointer] corresponds to a C pointer value that refers
|
||||
to memory managed by the garbage collector.
|
||||
|
||||
In the @3m[] and @CGC[] variants of Racket, a @racket[_gcpointer] result
|
||||
In the @BC[] implementation of Racket, a @racket[_gcpointer] result
|
||||
pointer can reference to memory that is not
|
||||
managed by the garbage collector, but beware of using an address that
|
||||
might eventually become managed by the garbage collector. For example,
|
||||
|
|
@ -615,7 +615,7 @@ For @tech{callouts} to foreign functions with the generated type:
|
|||
@item{If @racket[blocking?] is true, then a foreign @tech{callout}
|
||||
deactivates tracking of the calling OS thread---to the degree
|
||||
supported by the Racket variant---during the foreign call. The
|
||||
value of @racket[blocking?] affects only the @CS[] variant of
|
||||
value of @racket[blocking?] affects only the @CS[] implementation of
|
||||
Racket, where it enable activity
|
||||
such as garbage collection in other OS threads while the
|
||||
@tech{callout} blocks. If the blocking @tech{callout} can
|
||||
|
|
@ -705,7 +705,7 @@ For @tech{callbacks} to Racket functions with the generated type:
|
|||
@racket[keep] is based on the original function for the
|
||||
callback, not the result of @racket[wrapper].}
|
||||
|
||||
@item{If @racket[atomic?] is true or when using the @CS[] variant of
|
||||
@item{If @racket[atomic?] is true or when using the @CS[] implementation of
|
||||
Racket, then when a Racket procedure is given this type and
|
||||
called as a @tech{callback} from foreign code, then the Racket
|
||||
process is put into atomic mode while evaluating the Racket
|
||||
|
|
@ -721,9 +721,9 @@ For @tech{callbacks} to Racket functions with the generated type:
|
|||
to avoid C-level stack overflow; otherwise, the process may
|
||||
crash or misbehave.
|
||||
|
||||
Callbacks are always atomic in the @CS[] variant of Racket,
|
||||
Callbacks are always atomic in the @CS[] implementation of Racket,
|
||||
because Racket threads do not capture C-stack context. Even on
|
||||
the @3m[] or @CGC[] variants of Racket, atomic mode is
|
||||
the @BC[] implementation of Racket, atomic mode is
|
||||
typically needed for callbacks, because capturing by copying a
|
||||
portion of the C stack is often incompatible with C libraries.}
|
||||
|
||||
|
|
@ -1198,10 +1198,10 @@ type; a byte string is passed as @racket[_bytes] without any copying.
|
|||
Beware that a Racket byte string is not necessarily nul terminated;
|
||||
see also @racket[_bytes/nul-terminated].
|
||||
|
||||
In the @3m[] and @CGC[] variants of Racket, a C non-NULL result value
|
||||
In the @BC[] implementation of Racket, a C non-NULL result value
|
||||
is converted to a Racket byte string without copying; the pointer is
|
||||
treated as potentially managed by the garbage collector (see
|
||||
@racket[_gcpointer] for caveats). In the @CS[] variant of Racket,
|
||||
@racket[_gcpointer] for caveats). In the @CS[] implementation of Racket,
|
||||
conversion requires copying to represent a C @cpp{char*}
|
||||
result as a Racket byte string, and the original pointer is @emph{not}
|
||||
treated as managed by the garbage collector. In both cases, the C result must have
|
||||
|
|
@ -1209,10 +1209,10 @@ a nul terminator to determine the Racket byte string's length.
|
|||
|
||||
A @racket[(_bytes o len-expr)] form is a @tech{custom function type}.
|
||||
As an argument, a byte string is allocated with the given length; in
|
||||
the @3m[] and @CGC[] variants, that byte string includes an extra byte
|
||||
the @BC[] implementation, that byte string includes an extra byte
|
||||
for the nul terminator, and @racket[(_bytes o len-expr)] as a result
|
||||
wraps a C non-NULL @cpp{char*} pointer as a byte string of the given
|
||||
length. For the @CS[] variant, the allocated argument does not include
|
||||
length. For the @CS[] implementation, the allocated argument does not include
|
||||
a nul terminator and a copy is made for a result string.
|
||||
|
||||
As usual, @racket[_bytes] treats @racket[#f] as @cpp{NULL} and vice
|
||||
|
|
|
|||
|
|
@ -101,11 +101,11 @@ A predicate for callback values that are created by @racket[ffi-callback].
|
|||
|
||||
Creates a ``late'' will executor that readies a will for a value
|
||||
@scheme[_v] only if no normal will executor has a will registered for
|
||||
@scheme[_v]. In addition, for the @3m[] and @CGC[] variants of Racket,
|
||||
@scheme[_v]. In addition, for the @BC[] implementation of Racket,
|
||||
normal weak references to @scheme[_v] are cleared before a will for
|
||||
@racket[_v] is readied by the late will executor, but late weak
|
||||
references created by @racket[make-late-weak-box] and
|
||||
@racket[make-late-weak-hasheq] are not. For the @CS[] variant of
|
||||
@racket[make-late-weak-hasheq] are not. For the @CS[] implementation of
|
||||
Racket, a will is readied for @racket[_v] only when it is not reachable
|
||||
from any value that has a late will; if a value @racket[_v] is
|
||||
reachable from itself (i.e., through any field of @racket[_v], as
|
||||
|
|
|
|||
|
|
@ -19,7 +19,7 @@
|
|||
reference.scrbl
|
||||
->>
|
||||
tech-place
|
||||
3m CGC CS
|
||||
CS BC 3m CGC
|
||||
(all-from-out scribble/manual)
|
||||
(for-label (all-from-out racket/base
|
||||
racket/contract
|
||||
|
|
@ -46,6 +46,7 @@
|
|||
(define (tech-place)
|
||||
(tech "place" #:doc '(lib "scribblings/reference/reference.scrbl")))
|
||||
|
||||
(define (CS) (tech #:doc guide.scrbl "CS"))
|
||||
(define (BC) (tech #:doc guide.scrbl "BC"))
|
||||
(define (CGC) (tech #:doc guide.scrbl "CGC"))
|
||||
(define (3m) (tech #:doc guide.scrbl "3m"))
|
||||
(define (CS) (tech #:doc guide.scrbl "CS"))
|
||||
|
|
|
|||
|
|
@ -52,8 +52,8 @@ Non-interactive mode should be used instead of the
|
|||
|
||||
@section[#:tag "virtual-machines"]{Racket Virtual Machine Implementations}
|
||||
|
||||
Racket is available in three implementation variants: @deftech{CS},
|
||||
@deftech{3m}, and @deftech{CGC}:
|
||||
Racket is available in two implementations, @deftech{CS} and
|
||||
@deftech{BC}:
|
||||
|
||||
@itemlist[
|
||||
|
||||
|
|
@ -61,46 +61,54 @@ Racket is available in three implementation variants: @deftech{CS},
|
|||
a newer implementation that builds on
|
||||
@hyperlink["https://www.scheme.com/"]{Chez Scheme} as its core
|
||||
virtual machine. This implementation performs better than
|
||||
the @tech{3m} implementation for most programs.
|
||||
the @tech{BC} implementation for most programs.
|
||||
|
||||
For this variant, @racket[(system-type 'vm)] reports
|
||||
For this implementation, @racket[(system-type 'vm)] reports
|
||||
@racket['chez-scheme] and @racket[(system-type 'gc)] reports
|
||||
@racket['cs].}
|
||||
|
||||
@item{@tech{3m} is an older variant, and was the default until version 8.0.
|
||||
@item{@tech{BC} is an older implementation, and was the default until version 8.0.
|
||||
The implementation features a compiler and runtime written in C,
|
||||
with a precise garbage collector and a just-in-time compiler (JIT)
|
||||
on most platforms.
|
||||
|
||||
For this variant, @racket[(system-type 'vm)] reports
|
||||
@racket['racket] and @racket[(system-type 'gc)] reports
|
||||
@racket['3m].}
|
||||
For this implementation, @racket[(system-type 'vm)] reports
|
||||
@racket['racket].
|
||||
|
||||
@item{@tech{CGC} is an older variant. It's the same basic
|
||||
implementation as @tech{3m} (i.e., the same virtual machine),
|
||||
but compiled to rely on a ``conservative'' garbage collector,
|
||||
which affects the way that Racket interacts with C code. (See
|
||||
@secref["CGC versus 3m" #:doc inside-doc] in
|
||||
@other-manual[inside-doc] for more information.)
|
||||
The BC implementation itself has two variants, @deftech{3m} and
|
||||
@deftech{CGC}:
|
||||
|
||||
For this variant, @racket[(system-type 'vm)] reports
|
||||
@racket['racket] and @racket[(system-type 'gc)] reports
|
||||
@racket['cgc].}
|
||||
@itemlist[
|
||||
|
||||
@item{@tech{3m} is the normal BC variant with a precise
|
||||
garbage collector.
|
||||
|
||||
For this variant, @racket[(system-type 'gc)] reports
|
||||
@racket['3m].}
|
||||
|
||||
|
||||
@item{@tech{CGC} is the oldest variant. It's the same basic
|
||||
implementation as @tech{3m} (i.e., the same virtual
|
||||
machine), but compiled to rely on a ``conservative''
|
||||
garbage collector, which affects the way that Racket
|
||||
interacts with C code. See @secref["CGC versus 3m"
|
||||
#:doc inside-doc] in @other-manual[inside-doc] for more
|
||||
information.
|
||||
|
||||
For this variant, @racket[(system-type 'gc)] reports
|
||||
@racket['cgc].}
|
||||
|
||||
]}
|
||||
|
||||
]
|
||||
|
||||
The @tech{3m} and @tech{CGC} variants are collectively known as the
|
||||
@deftech{BC} (``before CS'') variant.
|
||||
|
||||
In general, Racket programs should run the same in all variants.
|
||||
Furthermore, the performance characteristics of Racket program should
|
||||
be similar in the @tech{3m} and @tech{CS} variants. The cases where a
|
||||
program may depends on the variant will typically involve interactions
|
||||
with foreign libraries; in particular, the Racket C API described in
|
||||
@other-doc[inside-doc] is different for the @tech{3m} and @tech{CGC}
|
||||
variants versus the @tech{CS} variant.
|
||||
be similar in the @tech{CS} and @tech{BC} implementations. The cases
|
||||
where a program may depends on the implementation will typically
|
||||
involve interactions with foreign libraries; in particular, the Racket
|
||||
C API described in @other-doc[inside-doc] is different for the
|
||||
@tech{CS} implementation versus the @tech{BC} implementation.
|
||||
|
||||
@; ----------------------------------------------------------------------
|
||||
|
||||
|
|
@ -121,16 +129,16 @@ elimination. For example, in an environment where @racket[+] has its
|
|||
usual binding, the expression @racket[(let ([x 1] [y (lambda () 4)]) (+
|
||||
1 (y)))] is compiled the same as the constant @racket[5].
|
||||
|
||||
For the @tech{CS} variant of Racket, the main bytecode format is
|
||||
non-portable machine code. For the @tech{3m} and @tech{CGC} variants
|
||||
of Racket, bytecode is portable in the sense that it is
|
||||
For the @tech{CS} implementation of Racket, the main bytecode format
|
||||
is non-portable machine code. For the @tech{BC} implementation of
|
||||
Racket, bytecode is portable in the sense that it is
|
||||
machine-independent. Setting @racket[current-compile-target-machine]
|
||||
to @racket[#f] selects a separate machine-independent and
|
||||
variant-independent format on all Racket variants, but running code in
|
||||
that format requires an additional internal conversion step to the
|
||||
variant's main bytecode format.
|
||||
variant-independent format on all Racket implementations, but running
|
||||
code in that format requires an additional internal conversion step to
|
||||
the implementation's main bytecode format.
|
||||
|
||||
Machine-independent bytecode for @tech{3m} or @tech{CGC} is further
|
||||
Machine-independent bytecode for @tech{BC} implementation is further
|
||||
compiled to native code via a @deftech{just-in-time} or @deftech{JIT}
|
||||
compiler. The @tech{JIT} compiler substantially speeds programs that
|
||||
execute tight loops, arithmetic on small integers, and arithmetic on
|
||||
|
|
@ -139,7 +147,7 @@ for x86, x86_64 (a.k.a. AMD64), 32-bit ARM, and 32-bit PowerPC processors.
|
|||
The @tech{JIT} compiler can be disabled via the
|
||||
@racket[eval-jit-enabled] parameter or the @DFlag{no-jit}/@Flag{j}
|
||||
command-line flag for @exec{racket}. Setting @racket[eval-jit-enabled]
|
||||
to @racket[#f] has not effect on the @tech{CS} variant of Racket.
|
||||
to @racket[#f] has not effect on the @tech{CS} implementation of Racket.
|
||||
|
||||
The @tech{JIT} compiler works incrementally as functions are applied,
|
||||
but the @tech{JIT} compiler makes only limited use of run-time
|
||||
|
|
@ -151,7 +159,7 @@ overhead for @tech{JIT} compilation is normally so small that it is
|
|||
difficult to detect.
|
||||
|
||||
For information about viewing intermediate Racket code
|
||||
representations, especially for the @tech{CS} variant, see
|
||||
representations, especially for the @tech{CS} implementation, see
|
||||
@refsecref["compiler-inspect"].
|
||||
|
||||
@; ----------------------------------------------------------------------
|
||||
|
|
@ -397,7 +405,7 @@ flonum-specific operation with two arguments.}
|
|||
Finally, the compiler can detect some flonum-valued loop
|
||||
accumulators and avoid boxing of the accumulator.
|
||||
@margin-note*{Unboxing of local bindings and accumulators is not
|
||||
supported by the @tech{3m} variant's JIT for PowerPC.}
|
||||
supported by the @tech{BC} implementation's JIT for PowerPC.}
|
||||
|
||||
For some loop patterns, the compiler may need hints to enable
|
||||
unboxing. For example:
|
||||
|
|
@ -419,7 +427,7 @@ changing the result @racket[sum] to @racket[(fl+ sum)] gives the
|
|||
compiler hints and license to unbox @racket[sum].
|
||||
|
||||
The bytecode decompiler (see @secref[#:doc '(lib
|
||||
"scribblings/raco/raco.scrbl") "decompile"]) for the @tech{3m} variant
|
||||
"scribblings/raco/raco.scrbl") "decompile"]) for the @tech{BC} implementation
|
||||
annotates combinations where the JIT can avoid boxes with
|
||||
@racketidfont{#%flonum}, @racketidfont{#%as-flonum}, and
|
||||
@racketidfont{#%from-flonum}. For the @tech{CS} variant, the
|
||||
|
|
@ -509,10 +517,10 @@ string or byte string, write a constant @tech{regexp} using an
|
|||
|
||||
@section[#:tag "gc-perf"]{Memory Management}
|
||||
|
||||
The @tech{3m} (default) and @tech{CS} Racket
|
||||
The @tech{CS} (default) and @tech{BC} Racket
|
||||
@seclink["virtual-machines"]{virtual machines} each use a modern,
|
||||
@deftech{generational garbage collector} that makes allocation
|
||||
relatively cheap for short-lived objects. The @tech{CGC} variant uses
|
||||
relatively cheap for short-lived objects. The @tech{CGC} variant of @tech{BC} uses
|
||||
a @deftech{conservative garbage collector} which facilitates
|
||||
interaction with C code at the expense of both precision and speed for
|
||||
Racket memory management.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
#lang scribble/doc
|
||||
@(require "utils.rkt")
|
||||
|
||||
@title[#:tag "contmarks"]{Continuation Marks}
|
||||
@bc-title[#:tag "contmarks"]{Continuation Marks}
|
||||
|
||||
A mark can be attached to the current continuation frame using
|
||||
@cppi{scheme_set_cont_mark}. To force the creation of a new frame
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
@(require "utils.rkt"
|
||||
scribble/bnf)
|
||||
|
||||
@title[#:tag "cs-embedding"]{Embedding into a Program}
|
||||
@cs-title[#:tag "cs-embedding"]{Embedding into a Program}
|
||||
|
||||
@section-index["embedding Racket CS"]
|
||||
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
@(require "utils.rkt"
|
||||
(for-label ffi/unsafe/vm))
|
||||
|
||||
@title[#:tag "cs-eval"]{Evaluation and Running Modules}
|
||||
@cs-title[#:tag "cs-eval"]{Evaluation and Running Modules}
|
||||
|
||||
The @cppi{racket_apply} function provides basic evaluation support,
|
||||
but @cppi{racket_eval}, @cppi{racket_dynamic_require}, and
|
||||
|
|
|
|||
|
|
@ -1,9 +1,9 @@
|
|||
#lang scribble/doc
|
||||
@(require "utils.rkt")
|
||||
|
||||
@title[#:tag "cs-overview"]{Overview}
|
||||
@cs-title[#:tag "cs-overview"]{Overview}
|
||||
|
||||
The Racket CS run-time system is implemented by a wrapper around the
|
||||
The Racket CS runtime system is implemented by a wrapper around the
|
||||
Chez Scheme kernel. The wrapper implements additional glue to the
|
||||
operating system (e.g., for I/O and networking) and provides entry
|
||||
points into the Racket layer's evaluator.
|
||||
|
|
@ -23,7 +23,7 @@ the Racket wrapper.
|
|||
@index['("allocation")]{Racket} values may be moved or garbage
|
||||
collected any time that @cpp{racket_...} functions are used to run
|
||||
Racket code. Do not retain a reference to any Racket value across such
|
||||
a call. This requirement contrasts with the 3m and CGC variants of
|
||||
a call. This requirement contrasts with the BC implementation of
|
||||
Racket, which provide a way for C code to more directly cooperate with
|
||||
the memory manager.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
#lang scribble/doc
|
||||
@(require "utils.rkt")
|
||||
|
||||
@title[#:tag "cs-procs"]{Calling Procedures}
|
||||
@cs-title[#:tag "cs-procs"]{Calling Procedures}
|
||||
|
||||
As an entry point into Racket, C programs should normally call Racket
|
||||
procedures by using @cppi{racket_apply}, which calls the procedure in
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
#lang scribble/doc
|
||||
@(require "utils.rkt")
|
||||
|
||||
@title[#:tag "cs-start"]{Starting and Declaring Initial Modules}
|
||||
@cs-title[#:tag "cs-start"]{Starting and Declaring Initial Modules}
|
||||
|
||||
As sketched in @secref["cs-embedding"], and embedded instance of
|
||||
Racket CS is started with @cppi{racket_boot}. Functions such as
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
#lang scribble/doc
|
||||
@(require "utils.rkt")
|
||||
|
||||
@title[#:tag "cs-thread"]{Managing OS-Level Threads}
|
||||
@cs-title[#:tag "cs-thread"]{Managing OS-Level Threads}
|
||||
|
||||
Chez Scheme functionality can only be accessed from OS-level threads
|
||||
that are known to the Chez Scheme runtime system. Otherwise, there's a
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
(for-label racket/unsafe/ops
|
||||
ffi/unsafe))
|
||||
|
||||
@title[#:tag "cs-values+types"]{Values and Types}
|
||||
@cs-title[#:tag "cs-values+types"]{Values and Types}
|
||||
|
||||
A Racket value is represented by a pointer-sized value. The low bits
|
||||
of the value indicate the encoding that it uses. For example, two (on
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
@(require "utils.rkt"
|
||||
(for-label ffi/unsafe/custodian))
|
||||
|
||||
@title{Custodians}
|
||||
@bc-title[#:tag "Custodians"]{Custodians}
|
||||
|
||||
When an extension allocates resources that must be explicitly freed
|
||||
(in the same way that a port must be explicitly closed), a Racket
|
||||
|
|
|
|||
|
|
@ -4,7 +4,7 @@
|
|||
|
||||
@(define cgc-v-3m "CGC versus 3m")
|
||||
|
||||
@title[#:tag "embedding"]{Embedding into a Program}
|
||||
@bc-title[#:tag "embedding"]{Embedding into a Program}
|
||||
|
||||
@section-index["embedding Racket BC"]
|
||||
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
#lang scribble/doc
|
||||
@(require "utils.rkt")
|
||||
|
||||
@title{Evaluation}
|
||||
@bc-title[#:tag "Evaluation"]{Evaluation}
|
||||
|
||||
A Racket S-expression is evaluated by calling @cppi{scheme_eval}.
|
||||
This function takes an S-expression (as a @cpp{Scheme_Object*}) and a
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
#lang scribble/doc
|
||||
@(require "utils.rkt")
|
||||
|
||||
@title[#:tag "exceptions"]{Exceptions and Escape Continuations}
|
||||
@bc-title[#:tag "exceptions"]{Exceptions and Escape Continuations}
|
||||
|
||||
When Racket encounters an error, it raises an exception. The default
|
||||
exception handler invokes the error display handler and then the error
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
#lang scribble/doc
|
||||
@(require "utils.rkt")
|
||||
|
||||
@title[#:tag "Writing Racket Extensions"]{Writing Racket Extensions}
|
||||
@bc-title[#:tag "Writing Racket Extensions"]{Writing Racket Extensions}
|
||||
|
||||
@section-index["extending Racket"]
|
||||
|
||||
|
|
|
|||
|
|
@ -6,11 +6,18 @@
|
|||
|
||||
@author["Matthew Flatt"]
|
||||
|
||||
The Racket runtime system is responsible for the implementation of
|
||||
primitive datatypes such as numbers and strings, the macro expansion
|
||||
and compilation of Racket from source, the allocation and reclamation
|
||||
of memory used during evaluation, and the scheduling of concurrent
|
||||
threads and parallel tasks.
|
||||
|
||||
This manual describes the C interface of Racket's runtime system,
|
||||
which varies depending on the variant of Racket (see @secref[#:doc
|
||||
'(lib "scribblings/guide/guide.scrbl") "virtual-machines"]): the CS
|
||||
variant of Racket has one interface, while the BC (3m and CGC)
|
||||
variants of Racket have another.
|
||||
which varies depending on the implementation of Racket (see
|
||||
@secref[#:doc '(lib "scribblings/guide/guide.scrbl")
|
||||
"virtual-machines"]): the CS implementation of Racket has one
|
||||
interface, while the BC (3m and CGC) implementation of Racket has
|
||||
another.
|
||||
|
||||
The C interface is relevant to some degree when interacting with
|
||||
foreign libraries as described in @other-manual['(lib
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
@(require "utils.rkt" (for-label ffi/unsafe
|
||||
ffi/unsafe/collect-callback))
|
||||
|
||||
@title[#:tag "im:memoryalloc"]{Memory Allocation}
|
||||
@bc-title[#:tag "im:memoryalloc"]{Memory Allocation}
|
||||
|
||||
@section-index{memory}
|
||||
@section-index{garbage collection}
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
@(require "utils.rkt"
|
||||
(for-label ffi/unsafe/global))
|
||||
|
||||
@title{Miscellaneous Utilities}
|
||||
@bc-title[#:tag "Miscellaneous Utilities"]{Miscellaneous Utilities}
|
||||
|
||||
The @cppi{MZSCHEME_VERSION} preprocessor macro is defined as a string
|
||||
describing the version of Racket. The @cppi{MZSCHEME_VERSION_MAJOR}
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
#lang scribble/doc
|
||||
@(require "utils.rkt")
|
||||
|
||||
@title[#:tag "im:env"]{Namespaces and Modules}
|
||||
@bc-title[#:tag "im:env"]{Namespaces and Modules}
|
||||
|
||||
A Racket namespace (a top-level environment) is represented by a value
|
||||
of type @cppi{Scheme_Env*} --- which is also a Racket value, castable
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
#lang scribble/doc
|
||||
@(require "utils.rkt")
|
||||
|
||||
@title{Bignums, Rationals, and Complex Numbers}
|
||||
@bc-title[#:tag "Bignums, Rationals, and Complex Numbers"]{Bignums, Rationals, and Complex Numbers}
|
||||
|
||||
Racket supports integers of an arbitrary magnitude; when an integer
|
||||
cannot be represented as a fixnum (i.e., 30 or 62 bits plus a sign
|
||||
|
|
|
|||
|
|
@ -1,14 +1,12 @@
|
|||
#lang scribble/doc
|
||||
@(require "utils.rkt")
|
||||
|
||||
@title[#:tag "overview"]{Overview}
|
||||
@bc-title[#:tag "overview"]{Overview}
|
||||
|
||||
The Racket run-time system is responsible for the implementation of
|
||||
primitive datatypes such as numbers and strings, the evaluation and/or
|
||||
JIT compilation of Racket bytecode, the macro expansion and
|
||||
compilation of Racket from source to bytecode, the allocation and
|
||||
reclamation of memory used during evaluation, and the scheduling of
|
||||
concurrent threads and parallel tasks.
|
||||
The Racket BC runtime system is implemented in C and provides the
|
||||
compiler from source to bytecode format, the JIT compiler from
|
||||
bytecode to machine code, I/O functionality, threads, and memory
|
||||
management.
|
||||
|
||||
@section{``Scheme'' versus ``Racket''}
|
||||
|
||||
|
|
@ -22,19 +20,19 @@ all should be renamed to start @cpp{racket_}.
|
|||
|
||||
@section[#:tag "CGC versus 3m"]{CGC versus 3m}
|
||||
|
||||
Before mixing any C code with Racket, first decide whether to use the
|
||||
Before mixing any C code with Racket BC, first decide whether to use the
|
||||
@bold{3m} variant of Racket, the @bold{CGC} variant of Racket, or
|
||||
both:
|
||||
|
||||
@itemize[
|
||||
|
||||
@item{@bold{@as-index{3m}} : the main variant of Racket, which uses
|
||||
@item{@bold{@as-index{3m}} : the main variant of Racket BC, which uses
|
||||
@defterm{precise} garbage collection and requires explicit
|
||||
registration of pointer roots and allocation shapes. The precise
|
||||
garbage collector may move its objects in memory during a
|
||||
collection.}
|
||||
|
||||
@item{@bold{@as-index{CGC}} : the original variant of Racket, where
|
||||
@item{@bold{@as-index{CGC}} : the original variant of Racket BC, where
|
||||
memory management depends on a @defterm{conservative} garbage
|
||||
collector. The conservative garbage collector can automatically find
|
||||
references to managed values from C local variables and (on some
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
#lang scribble/doc
|
||||
@(require "utils.rkt")
|
||||
|
||||
@title[#:tag "config"]{Parameterizations}
|
||||
@bc-title[#:tag "config"]{Parameterizations}
|
||||
|
||||
A @defterm{parameterization} is a set of parameter values. Each thread
|
||||
has its own initial parameterization, which is extended functionally
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
#lang scribble/doc
|
||||
@(require "utils.rkt")
|
||||
|
||||
@title{Ports and the Filesystem}
|
||||
@bc-title[#:tag "Ports and the Filesystem"]{Ports and the Filesystem}
|
||||
|
||||
Ports are represented as Racket values with the types
|
||||
@cppi{scheme_input_port_type} and @cppi{scheme_output_port_type}. The
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
#lang scribble/doc
|
||||
@(require "utils.rkt")
|
||||
|
||||
@title{Procedures}
|
||||
@bc-title[#:tag "Procedure"]{Procedures}
|
||||
|
||||
A @defterm{primitive procedure} is a Racket-callable procedure that is
|
||||
implemented in C. Primitive procedures are created in Racket with
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
#lang scribble/doc
|
||||
@(require "utils.rkt")
|
||||
|
||||
@title[#:tag "security"]{Security Guards}
|
||||
@bc-title[#:tag "security"]{Security Guards}
|
||||
|
||||
Before a primitive procedure accesses the filesystem or creates a
|
||||
network connection, it should first consult the current security guard
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
#lang scribble/doc
|
||||
@(require "utils.rkt")
|
||||
|
||||
@title[#:tag "im:encodings"]{String Encodings}
|
||||
@bc-title[#:tag "im:encodings"]{String Encodings}
|
||||
|
||||
The @cpp{scheme_utf8_decode} function decodes a @cpp{char} array as
|
||||
UTF-8 into either a UCS-4 @cpp{mzchar} array or a UTF-16 @cpp{short}
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
#lang scribble/doc
|
||||
@(require "utils.rkt")
|
||||
|
||||
@title{Structures}
|
||||
@bc-title[#:tag "Structures"]{Structures}
|
||||
|
||||
A new Racket structure type is created with
|
||||
@cppi{scheme_make_struct_type}. This creates the structure type, but
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
@(require "utils.rkt"
|
||||
(for-label racket/system))
|
||||
|
||||
@title{Subprocesses}
|
||||
@bc-title[#:tag "Subprocesses"]{Subprocesses}
|
||||
|
||||
On Unix and Mac OS, subprocess handling involves
|
||||
@as-index[@cpp{fork}], @as-index[@cpp{waitpid}], and
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
#lang scribble/doc
|
||||
@(require "utils.rkt" (for-label scheme/tcp))
|
||||
|
||||
@title[#:tag "threads"]{Threads}
|
||||
@bc-title[#:tag "threads"]{Threads}
|
||||
|
||||
The initializer function @cppi{scheme_basic_env} creates the main
|
||||
Racket thread; all other threads are created through calls to
|
||||
|
|
|
|||
|
|
@ -7,7 +7,8 @@
|
|||
(for-syntax scheme/base)
|
||||
(for-label scheme/base))
|
||||
|
||||
(provide Racket
|
||||
(provide cs-title bc-title
|
||||
Racket
|
||||
mzc cpp cppi cppdef (rename-out [*var var])
|
||||
function subfunction together
|
||||
FormatD
|
||||
|
|
@ -16,6 +17,12 @@
|
|||
(except-out (all-from-out scribble/manual) var)
|
||||
(for-label (all-from-out scheme/base)))
|
||||
|
||||
(define (cs-title #:tag tag . content)
|
||||
(apply title #:tag tag (append content (list " (CS)"))))
|
||||
|
||||
(define (bc-title #:tag tag . content)
|
||||
(apply title #:tag tag (append content (list " (BC)"))))
|
||||
|
||||
(define (as-cpp-defn name s)
|
||||
(make-target-element #f
|
||||
(list (as-index s))
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
#lang scribble/doc
|
||||
@(require "utils.rkt")
|
||||
|
||||
@title[#:tag "im:values+types"]{Values and Types}
|
||||
@bc-title[#:tag "im:values+types"]{Values and Types}
|
||||
|
||||
A Racket value is represented by a pointer-sized value. The low bit is
|
||||
a mark bit: a 1 in the low bit indicates an immediate integer, a 0
|
||||
|
|
|
|||
|
|
@ -22,17 +22,17 @@ parameter to @racket[#f] or supplying the @DFlag{compile-any}/@Flag{M}
|
|||
flag on startup. See @racket[current-compile-target-machine] for more
|
||||
information.
|
||||
|
||||
Other compilation modes depend on the Racket variant
|
||||
(3m/CGC versus CS).
|
||||
Other compilation modes depend on the Racket variant (see
|
||||
@secref["implementations"]).
|
||||
|
||||
|
||||
@subsection[#:tag "3m-compiler-modes"]{3m and CGC Compilation Modes}
|
||||
@subsection[#:tag "3m-compiler-modes"]{BC Compilation Modes}
|
||||
|
||||
The 3m and CGC variants of Racket support two
|
||||
The @tech{BC} implementation of Racket supports two
|
||||
compilation modes: bytecode and machine-independent. The bytecode
|
||||
format is also machine-independent in the sense that it works the same
|
||||
on all operating systems for the 3m and/or CGC variants
|
||||
of Racket, but it does not work with the CS variant of Racket.
|
||||
on all operating systems for the BC implementation
|
||||
of Racket, but it does not work with the CS implementation of Racket.
|
||||
|
||||
Bytecode is further compiled to machine code at run time, unless the
|
||||
JIT compiler is disabled. See @racket[eval-jit-enabled].
|
||||
|
|
@ -40,10 +40,10 @@ JIT compiler is disabled. See @racket[eval-jit-enabled].
|
|||
|
||||
@subsection[#:tag "cs-compiler-modes"]{CS Compilation Modes}
|
||||
|
||||
The CS variant of Racket supports several compilation modes:
|
||||
The @tech{CS} implementation of Racket supports several compilation modes:
|
||||
machine code, machine-independent, interpreted, and JIT. Machine code
|
||||
is the primary mode, and the machine-independent mode is the same as
|
||||
for 3m and CGC. Interpreted mode uses an interpreter at
|
||||
for BC. Interpreted mode uses an interpreter at
|
||||
the level of core @tech{linklet} forms with no compilation. JIT mode
|
||||
triggers compilation of individual function forms on demand.
|
||||
|
||||
|
|
@ -79,7 +79,7 @@ compiled forms whenever a Racket form is compiled. For all Racket
|
|||
variants, the output shows one or more @tech{linklets} that are
|
||||
generated from the original Racket form.
|
||||
|
||||
For the CS variant of Racket, a ``schemified'' version of the linklet
|
||||
For the @tech{CS} implementation of Racket, a ``schemified'' version of the linklet
|
||||
is also shown as the translation of the @racket[linklet] form to a
|
||||
Chez Scheme procedure form. The following environment variables imply
|
||||
@envvar{PLT_LINKLET_SHOW} and show additional intermediate compiled
|
||||
|
|
|
|||
|
|
@ -190,7 +190,7 @@ called in tail position, and the continuation procedure supplied to
|
|||
A continuation obtained from @racket[call-with-escape-continuation] is
|
||||
actually a kind of prompt. Escape continuations are provided mainly
|
||||
for backwards compatibility, since they pre-date general prompts in
|
||||
Racket. In the 3m and CGC variants of Racket,
|
||||
Racket. In the @tech{BC} implementation of Racket,
|
||||
@racket[call-with-escape-continuation] is implemented more efficiently
|
||||
than @racket[call-with-current-continuation], so
|
||||
@racket[call-with-escape-continuation] can sometimes replace
|
||||
|
|
|
|||
|
|
@ -80,9 +80,8 @@ down, then it cannot be a subordinate of @racket[super].}
|
|||
|
||||
@defproc[(custodian-memory-accounting-available?) boolean?]{
|
||||
|
||||
@margin-note{Memory accounting is normally available in Racket 3m,
|
||||
which is the main variant of Racket, and not normally available in
|
||||
Racket CGC.}
|
||||
@margin-note{Memory accounting is normally available, but not in
|
||||
the @tech{CGC} implementation.}
|
||||
|
||||
Returns @racket[#t] if Racket is compiled with support for
|
||||
per-custodian memory accounting, @racket[#f] otherwise.}
|
||||
|
|
|
|||
|
|
@ -5,9 +5,9 @@
|
|||
|
||||
Racket's built-in debugging support is limited to context (i.e.,
|
||||
``stack trace'') information that is printed with an exception. In
|
||||
some cases, for 3m and CGC variants of Racket, disabling the
|
||||
@tech{JIT} compiler can affect context information. For the CS variant
|
||||
of Racket, setting the @envvar-indexed{PLT_CS_DEBUG} environment
|
||||
some cases, for @tech{BC} implementation of Racket, disabling the
|
||||
@tech{JIT} compiler can affect context information. For the @tech{CS}
|
||||
implementation of Racket, setting the @envvar-indexed{PLT_CS_DEBUG} environment
|
||||
variable causes compilation to record expression-level context
|
||||
information, instead of just function-level information.
|
||||
|
||||
|
|
|
|||
|
|
@ -1088,8 +1088,8 @@ The values managed by a custodian are semi-weakly held by the
|
|||
custodian: a @techlink{will} can be executed for a value that is
|
||||
managed by a custodian; in addition, weak references via weak
|
||||
@tech{hash tables}, @tech{ephemerons}, or @tech{weak box}es can be
|
||||
dropped on the 3m or CGC variants of Racket, but not on the CS
|
||||
variant. For all variants, a custodian only weakly
|
||||
dropped on the @tech{BC} implementation of Racket, but not on the @tech{CS}
|
||||
implementation. For all variants, a custodian only weakly
|
||||
references its subordinate custodians; if a subordinate custodian is
|
||||
unreferenced but has its own subordinates, then the custodian may be
|
||||
garbage collected, at which point its subordinates become immediately
|
||||
|
|
|
|||
46
pkgs/racket-doc/scribblings/reference/implementation.scrbl
Normal file
46
pkgs/racket-doc/scribblings/reference/implementation.scrbl
Normal file
|
|
@ -0,0 +1,46 @@
|
|||
#lang scribble/doc
|
||||
@(require "mz.rkt")
|
||||
|
||||
@title[#:tag "implementations" #:style 'quiet]{Implementations}
|
||||
|
||||
The definition of Racket aims for determinism and independence from
|
||||
its implementation. Nevertheless, some details inevitably vary with
|
||||
the implementation. Racket currently has two main implementations:
|
||||
|
||||
@itemlist[
|
||||
|
||||
@item{The @deftech{CS} implementation is the default implementation
|
||||
as of Racket version 8.0. This variant is called ``CS'' because
|
||||
it uses Chez Scheme as its core compiler and runtime system.
|
||||
|
||||
The CS implementation typically provides the best performance
|
||||
for Racket programs. Compiled Racket CS code in a
|
||||
@filepath{.zo} file normally contains machine code that is
|
||||
specific to an operating system and architecture.}
|
||||
|
||||
@item{The @deftech{BC} implementation was the default implementation
|
||||
up until version 7.8. The ``BC'' label stands for ``before
|
||||
Chez'' or ``bytecode.''
|
||||
|
||||
Compiled Racket BC code in a @filepath{.zo} file normally
|
||||
contains platform-independent bytecode that is further compiled
|
||||
to machine code ``just in time'' as the code is loaded.
|
||||
|
||||
Racket BC has two subvariants: @deftech{3m} and @deftech{CGC}.
|
||||
The difference is the @tech{garbage collection} implementation,
|
||||
where 3m uses a garbage collector that moves objects in memory
|
||||
(an effect that is visible to foreign libraries, for example)
|
||||
and keeps precise track of allocated objects, while CGC uses a
|
||||
``conservative'' collector that requires less cooperation from
|
||||
an embedding foreign environment. The 3m subvariant tends to
|
||||
perform much better than CGC, and it because the default
|
||||
variant in version 370 (which would be v3.7 in the current
|
||||
versioning convention).}
|
||||
|
||||
]
|
||||
|
||||
Most Racket programs run the same in all variants, but some Racket
|
||||
features are available only on some implementation variants, and the
|
||||
interaction of Racket and foreign functions is significantly different
|
||||
across the variants. Use @racket[system-type] to get information about
|
||||
the current running implementation.
|
||||
|
|
@ -224,10 +224,10 @@ to a value that starts with @litchar{0}, @litchar{n}, or @litchar{N} to
|
|||
disable incremental-mode requests.
|
||||
|
||||
Each garbage collection logs a message (see @secref["logging"]) at the
|
||||
@racket['debug] level with topic @racket['GC]. In the 3m and CS
|
||||
variants of Racket, ``major'' collections are also logged at the
|
||||
@racket['debug] level with the topic @racket['GC:major]. In the 3m
|
||||
and CS variants of Racket, the data portion of the message is an
|
||||
@racket['debug] level with topic @racket['GC]. In the @tech{CS} and @tech{3m}
|
||||
implementations of Racket, ``major'' collections are also logged at the
|
||||
@racket['debug] level with the topic @racket['GC:major]. In the @tech{CS}
|
||||
and @tech{3m} implementations of Racket, the data portion of the message is an
|
||||
instance of a @indexed-racket[gc-info] @tech{prefab} structure type
|
||||
with 10 fields as follows, but future versions of Racket may use a
|
||||
@racket[gc-info] @tech{prefab} structure with additional fields:
|
||||
|
|
@ -360,9 +360,9 @@ garbage-collection mode, depending on @racket[request]:
|
|||
The intent of incremental mode is to significantly reduce pause
|
||||
times due to major collections, but incremental mode may imply
|
||||
longer minor-collection times and higher memory use. Currently,
|
||||
incremental mode is only meaningful when @racket[(system-type
|
||||
'gc)] returns @racket['3m] or @racket['cs]; it has no effect in
|
||||
other Racket variants.
|
||||
incremental mode is only meaningful for @tech{CS} and @tech{3m}
|
||||
Racket implementations; it has no effect in
|
||||
other Racket implementations.
|
||||
|
||||
If the @envvar{PLT_INCREMENTAL_GC} environment variable's value
|
||||
starts with @litchar{0}, @litchar{n}, or @litchar{N} on
|
||||
|
|
@ -373,7 +373,7 @@ garbage-collection mode, depending on @racket[request]:
|
|||
@history[#:changed "6.3" @elem{Added the @racket[request] argument.}
|
||||
#:changed "6.3.0.2" @elem{Added @racket['incremental] mode.}
|
||||
#:changed "7.7.0.4" @elem{Added @racket['incremental] effect
|
||||
for Racket CS.}]}
|
||||
for Racket @tech{CS}.}]}
|
||||
|
||||
|
||||
@defproc[(current-memory-use [mode (or/c #f 'cumulative custodian?) #f])
|
||||
|
|
@ -437,8 +437,7 @@ manager that memory is allocated within the process but through a
|
|||
separate allocator, such as through a foreign library that is accessed
|
||||
via @racketmodname[ffi/unsafe]. This hint is used to trigger
|
||||
@tech{garbage collections} or to compute the result of
|
||||
@racket[current-memory-use]. Currently, the hint is used only in
|
||||
Racket 3m (the main variant of Racket).
|
||||
@racket[current-memory-use].
|
||||
|
||||
@defproc[(phantom-bytes? [v any/c]) boolean?]{
|
||||
|
||||
|
|
|
|||
|
|
@ -9,3 +9,4 @@
|
|||
@include-section["syntax-model.scrbl"]
|
||||
@include-section["reader.scrbl"]
|
||||
@include-section["printer.scrbl"]
|
||||
@include-section["implementation.scrbl"]
|
||||
|
|
|
|||
|
|
@ -25,16 +25,16 @@ take advantage of machines with multiple processors, cores, or
|
|||
hardware threads.
|
||||
|
||||
@margin-note{Currently, parallel support for places is enabled
|
||||
only for the CS and 3m variants of Racket, and for 3m, only
|
||||
only for the @tech{CS} and @tech{3m} implementations of Racket, and for @tech{3m}, only
|
||||
by default for Windows, Linux x86/x86_64, and Mac OS x86/x86_64. To
|
||||
enable support for other platforms with 3m, use @DFlag{enable-places} with
|
||||
enable support for other platforms with @tech{3m}, use @DFlag{enable-places} with
|
||||
@exec{configure} when building Racket. The @racket[place-enabled?]
|
||||
function reports whether places run in parallel.
|
||||
|
||||
Implementation and operating-system constraints may limit the
|
||||
scalability of places. For example, although places can perform
|
||||
garbage collections in parallel in the CS variant or independently
|
||||
in the 3m variant, a garbage collection
|
||||
garbage collections in parallel in the @tech{CS} implementation or independently
|
||||
in the @tech{3m} implementation, a garbage collection
|
||||
may need to manipulate a page table that is shared across all
|
||||
places, and that shared page table can be a bottleneck with enough
|
||||
places---perhaps around 8 or 16.}
|
||||
|
|
|
|||
|
|
@ -624,7 +624,7 @@ the conversion of the source field is to preserve some source
|
|||
information but not expose or record a path that makes no sense on
|
||||
a different filesystem or platform.
|
||||
|
||||
For internal testing purposes in the 3m and CGC variants of Racket, when the
|
||||
For internal testing purposes in the @tech{BC} implementation of Racket, when the
|
||||
@as-index{@envvar{PLT_VALIDATE_LOAD}} environment variable is set, the
|
||||
reader runs a validator on bytecode parsed from @litchar{#~}. The
|
||||
validator may catch miscompilations or bytecode-file corruption. The
|
||||
|
|
|
|||
|
|
@ -43,7 +43,7 @@ or 64-bit program.
|
|||
about the @racket['vm] and @racket['gc] mode results.}
|
||||
|
||||
In @indexed-racket['vm] mode,
|
||||
the possible symbol results are:
|
||||
the possible symbol results are (see also @secref["implementations"]):
|
||||
|
||||
@itemize[
|
||||
@item{@indexed-racket['racket]}
|
||||
|
|
@ -51,7 +51,7 @@ the possible symbol results are:
|
|||
]
|
||||
|
||||
In @indexed-racket['gc] mode,
|
||||
the possible symbol results are:
|
||||
the possible symbol results are (see also @secref["implementations"]):
|
||||
|
||||
@itemize[
|
||||
@item{@indexed-racket['cgc] --- when @racket[(system-type 'vm)] is @racket['racket]}
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user