suzanne.soy/racket
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

rackety inside doc

Browse Source
This commit is contained in:
Matthew Flatt 2010-04-30 21:58:08 -06:00
parent 81ba669237
commit 77a99f6aa0
16 changed files with 321 additions and 305 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
collects/scribblings/inside/custodians.scrbl
View File

@ -4,7 +4,7 @@
@title{Custodians}
When an extension allocates resources that must be explicitly freed
(in the same way that a port must be explicitly closed), a Scheme
(in the same way that a port must be explicitly closed), a Racket
object associated with the resource should be placed into the
management of the current custodian with @cppi{scheme_add_managed}.
@ -93,7 +93,7 @@ Instructs the custodian @var{m} to shutdown all of its managed values.}
[Scheme_Exit_Closer_Func f])]{
Installs a function to be called on each custodian-registered item and
its closer when MzScheme is about to exit. The registered function
its closer when Racket is about to exit. The registered function
has the type
@verbatim[#:indent 2]{

18
collects/scribblings/inside/eval.scrbl
View File

@ -3,7 +3,7 @@
@title{Evaluation}
A Scheme S-expression is evaluated by calling @cppi{scheme_eval}.
A Racket S-expression is evaluated by calling @cppi{scheme_eval}.
This function takes an S-expression (as a @cpp{Scheme_Object*}) and a
namespace and returns the value of the expression in that namespace.
@ -12,7 +12,7 @@ a procedure, the number of arguments to pass to the procedure, and an
array of @cpp{Scheme_Object *} arguments. The return value is the
result of the application. There is also a function
@cppi{scheme_apply_to_list}, which takes a procedure and a list
(constructed with @cppi{scheme_make_pair}) and performs the Scheme
(constructed with @cppi{scheme_make_pair}) and performs the Racket
@scheme[apply] operation.
The @cppi{scheme_eval} function actually calls @cppi{scheme_compile}
@ -43,15 +43,15 @@ see @secref["exceptions"].
@section-index{tail recursion}
All of Scheme's built-in functions and syntax support proper
All of Racket's built-in functions and syntax support proper
tail-recursion. When a new primitive procedure or syntax is added to
Scheme, special care must be taken to ensure that tail recursion is
Racket, special care must be taken to ensure that tail recursion is
handled properly. Specifically, when the final return value of a
function is the result of an application, then
@cppi{scheme_tail_apply} should be used instead of
@cppi{scheme_apply}. When @cppi{scheme_tail_apply} is called, it
postpones the procedure application until control returns to the
Scheme evaluation loop.
Racket evaluation loop.
For example, consider the following implementation of a
@scheme[thunk-or] primitive, which takes any number of thunks and
@ -158,9 +158,9 @@ Non-top-level version of @cpp{scheme_eval_compiled_multi}. (See @secref["topleve
@function[(Scheme_Env* scheme_basic_env)]{
Creates the main namespace for an embedded PLT Scheme. This procedure
must be called before other Scheme library function (except
@cpp{scheme_make_param}). Extensions to Scheme cannot call this
Creates the main namespace for an embedded Racket. This procedure
must be called before other Racket library function (except
@cpp{scheme_make_param}). Extensions to Racket cannot call this
function.
If it is called more than once, this function resets all threads
@ -176,7 +176,7 @@ Creates and returns a new namespace. This values can be cast to
a parameterization using @cppi{scheme_set_param} with
@cppi{MZCONFIG_ENV}.
When PLT Scheme is embedded in an application, create the initial
When Racket is embedded in an application, create the initial
namespace with @cppi{scheme_basic_env} before calling this procedure
to create new namespaces.}

46
collects/scribblings/inside/exns.scrbl
View File

@ -3,7 +3,7 @@
@title[#:tag "exceptions"]{Exceptions and Escape Continuations}
When Scheme encounters an error, it raises an exception. The default
When Racket encounters an error, it raises an exception. The default
exception handler invokes the error display handler and then the error
escape handler. The default error escape handler escapes via a
@defterm{primitive error escape}, which is implemented by calling
@ -12,7 +12,7 @@ escape handler. The default error escape handler escapes via a
An embedding program should install a fresh buffer into
@cpp{scheme_current_thread->error_buf} and call
@cpp{scheme_setjmp(*scheme_current_thread->error_buf)} before any
top-level entry into Scheme evaluation to catch primitive error
top-level entry into Racket evaluation to catch primitive error
escapes. When the new buffer goes out of scope, restore the original
in @cpp{scheme_current_thread->error_buf}. The macro
@cppi{scheme_error_buf} is a shorthand for
@ -47,12 +47,12 @@ New primitive procedures can raise a generic exception by calling
function @cpp{printf}. A specific primitive exception can be raised by
calling @cppi{scheme_raise_exn}.
Full @as-index{continuations} are implemented in Scheme by copying
Full @as-index{continuations} are implemented in Racket by copying
the C stack and using @cppi{scheme_setjmp} and @cppi{scheme_longjmp}.
As long a C/C++ application invokes Scheme evaluation through the
As long a C/C++ application invokes Racket evaluation through the
top-level evaluation functions (@cpp{scheme_eval}, @cpp{scheme_apply},
etc., as opposed to @cpp{_scheme_apply}, @cpp{_scheme_eval_compiled},
etc.), the code is protected against any unusual behavior from Scheme
etc.), the code is protected against any unusual behavior from Racket
evaluations (such as returning twice from a function) because
continuation invocations are confined to jumps within a single
top-level evaluation. However, escape continuation jumps are still
@ -109,11 +109,11 @@ calls top-level evaluation functions (@cpp{scheme_eval},
@cpp{_scheme_eval_compiled}, etc.). Otherwise, use
@cppi{scheme_dynamic_wind} to protect your code against full
continuation jumps in the same way that @scheme[dynamic-wind] is used
in Scheme.
in Racket.
The above solution simply traps the escape; it doesn't report the
reason that the escape occurred. To catch exceptions and obtain
information about the exception, the simplest route is to mix Scheme
information about the exception, the simplest route is to mix Racket
code with C-implemented thunks. The code below can be used to catch
exceptions in a variety of situations. It implements the function
@cpp{_apply_catch_exceptions}, which catches exceptions during the
@ -148,7 +148,7 @@ application of a thunk. (This code is in
}
}
/* This function applies a thunk, returning the Scheme value if
/* This function applies a thunk, returning the Racket value if
there's no exception, otherwise returning NULL and setting *exn
to the raised value (usually an exn structure). */
Scheme_Object *_apply_thunk_catch_exceptions(Scheme_Object *f,
@ -184,9 +184,11 @@ In the following example, the above code is used to catch exceptions
that occur during while evaluating source code from a string.
@verbatim[#:indent 2]{
static Scheme_Object *do_eval(void *s, int noargc, Scheme_Object **noargv)
static Scheme_Object *do_eval(void *s, int noargc,
Scheme_Object **noargv)
{
return scheme_eval_string((char *)s, scheme_get_env(scheme_config));
return scheme_eval_string((char *)s,
scheme_get_env(scheme_config));
}
static Scheme_Object *eval_string_or_get_exn_message(char *s)
@ -213,12 +215,12 @@ that occur during while evaluating source code from a string.
@section{Enabling and Disabling Breaks}
When embedding PLT Scheme, asynchronous break exceptions are disabled by
When embedding Racket, asynchronous break exceptions are disabled by
default. Call @cpp{scheme_set_can_break} (which is the same as calling
the Scheme funciton @scheme[break-enabled]) to enable or disable
the Racket funciton @scheme[break-enabled]) to enable or disable
breaks. To enable or disable breaks during the dynamic extent of
another evaluation (where you would use
@scheme[with-break-parameterization] in Scheme), use
@scheme[with-break-parameterization] in Racket), use
@cppi{scheme_push_break_enable} before and
@cppi{scheme_pop_break_enable} after, instead.
@ -245,7 +247,7 @@ for @cpp{printf}, but with the following format directives:
@item{@FormatD{5} : a nul-terminated @cpp{mzchar} string}
@item{@FormatD{S} : a Scheme symbol (a @cpp{Scheme_Object*})}
@item{@FormatD{S} : a Racket symbol (a @cpp{Scheme_Object*})}
@item{@FormatD{t} : a @cpp{char} string with a @cpp{long} size (two
arguments), possibly containing a non-terminating nul byte, and
@ -255,16 +257,16 @@ for @cpp{printf}, but with the following format directives:
arguments), possibly containing a non-terminating nul character, and
possibly without a nul-terminator}
@item{@FormatD{T} : a Scheme string (a @cpp{Scheme_Object*})}
@item{@FormatD{T} : a Racket string (a @cpp{Scheme_Object*})}
@item{@FormatD{q} : a string, truncated to 253 characters, with ellipses
printed if the string is truncated}
@item{@FormatD{Q} : a Scheme string (a @cpp{Scheme_Object*}),
@item{@FormatD{Q} : a Racket string (a @cpp{Scheme_Object*}),
truncated to 253 characters, with ellipses printed if the string is
truncated}
@item{@FormatD{V} : a Scheme value (a @cpp{Scheme_Object*}),
@item{@FormatD{V} : a Racket value (a @cpp{Scheme_Object*}),
truncated according to the current error print width.}
@item{@FormatD{e} : an @cpp{errno} value, to be printed as a text
@ -282,7 +284,7 @@ for @cpp{printf}, but with the following format directives:
]
The arguments following the format string must include no more than 25
strings and Scheme values, 25 integers, and 25 floating-point
strings and Racket values, 25 integers, and 25 floating-point
numbers. (This restriction simplifies the implementation with precise
garbage collection.)}
@ -298,7 +300,7 @@ fields). The remaining arguments start with an error string and
proceed roughly as for @cpp{printf}; see @cpp{scheme_signal_error}
above for more details.
Exception ids are @cpp{#define}d using the same names as in Scheme,
Exception ids are @cpp{#define}d using the same names as in Racket,
but prefixed with ``MZ'', all letters are capitalized, and all ``:'s',
``-''s, and ``/''s are replaced with underscores. For example,
@cpp{MZEXN_FAIL_FILESYSTEM} is the exception id for a filesystem
@ -370,8 +372,8 @@ variable.}
[int count]
[int* len])]{
Converts a Scheme value into a string for the purposes of reporting an
error message. The @var{count} argument specifies how many Scheme
Converts a Racket value into a string for the purposes of reporting an
error message. The @var{count} argument specifies how many Racket
values total will appear in the error message (so the string for this
value can be scaled appropriately). If @var{len} is not @cpp{NULL}, it
is filled with the length of the returned string.}
@ -384,7 +386,7 @@ is filled with the length of the returned string.}
[Scheme_Object** argv]
[long* len])]{
Converts an array of Scheme values into a byte string, skipping the
Converts an array of Racket values into a byte string, skipping the
array element indicated by @var{which}. This function is used to
specify the ``other'' arguments to a function when one argument is bad
(thus giving the user more information about the state of the program

8
collects/scribblings/inside/hooks.scrbl
View File

@ -3,7 +3,7 @@
@title{Flags and Hooks}
The following flags and hooks are available when PLT Scheme is
The following flags and hooks are available when Racket is
embedded:
@itemize[
@ -14,7 +14,7 @@ embedded:
@item{@cppdef{scheme_make_stdin}, @cppdef{scheme_make_stdout},
@cppdef{scheme_make_stderr}, --- These pointers can be set to a
function that takes no arguments and returns a Scheme port
function that takes no arguments and returns a Racket port
@cpp{Scheme_Object *} to be used as the starting standard input,
output, and/or error port. The defaults are @cpp{NULL}. Setting the
initial error port is particularly important for seeing unexpected
@ -22,7 +22,7 @@ embedded:
@item{@cppdef{scheme_console_output} --- This pointer can be set to a
function that takes a string and a @cpp{long} string length; the
function will be called to display internal MzScheme warnings and
function will be called to display internal Racket warnings and
messages that possibly contain non-terminating nuls. The default is
@var{NULL}.}
@ -36,7 +36,7 @@ embedded:
@item{@cppdef{scheme_case_sensitive} --- If this flag is set to a
non-zero value before @cppi{scheme_basic_env} is called, then
MzScheme will not ignore capitalization for symbols and global
Racket will not ignore capitalization for symbols and global
variable names. The value of this flag should not change once it is
set. The default is zero.}

10
collects/scribblings/inside/inside.scrbl
View File

@ -2,19 +2,19 @@
@(require "utils.ss")
@title[#:tag-prefix '(lib "scribblings/inside/inside.scrbl")
#:tag "top"]{@bold{Inside}: PLT Scheme C API}
#:tag "top"]{@bold{Inside}: Racket C API}
@author["Matthew Flatt"]
This manual describes PLT Scheme's C interface, which allows the
This manual describes Racket's C interface, which allows the
interpreter to be extended by a dynamically-loaded library, or
embedded within an arbitrary C/C++ program. The manual assumes
familiarity with PLT Scheme as described in @|MzScheme|.
familiarity with Racket as described in @|MzScheme|.
For an alternative way of dealing with foreign code, see
@other-manual['(lib "scribblings/foreign/foreign.scrbl")], which
describes the @schememodname[scheme/foreign] module for manipulating
low-level libraries and structures purely through Scheme code.
describes the @racketmodname[ffi/unsafe] module for manipulating
low-level libraries and structures purely through Racket code.
@table-of-contents[]

28
collects/scribblings/inside/memory.scrbl
View File

@ -6,14 +6,14 @@
@section-index{memory}
@section-index{garbage collection}
PLT Scheme uses both @cppi{malloc} and allocation functions provided
Racket uses both @cppi{malloc} and allocation functions provided
by a garbage collector. Embedding/extension C/C++ code may use either
allocation method, keeping in mind that pointers to
garbage-collectable blocks in @cpp{malloc}ed memory are invisible
(i.e., such pointers will not prevent the block from being
garbage-collected).
PLT Scheme CGC uses a conservative garbage collector. This garbage
Racket CGC uses a conservative garbage collector. This garbage
collector normally only recognizes pointers to the beginning of
allocated objects. Thus, a pointer into the middle of a GC-allocated
string will normally not keep the string from being collected. The
@ -22,7 +22,7 @@ registers may point to the middle of a collectable object. Thus, it
is safe to loop over an array by incrementing a local pointer
variable.
PLT Scheme 3m uses a precise garbage collector that moves objects
Racket 3m uses a precise garbage collector that moves objects
during collection, in which case the C code must be instrumented to
expose local pointer bindings to the collector, and to provide tracing
procedures for (tagged) records containing pointers. This
@ -74,8 +74,8 @@ The basic collector allocation functions are:
]
@index['("globals" "in extension code")]{If} a PLT Scheme extension
stores Scheme pointers in a global or static variable, then that
@index['("globals" "in extension code")]{If} a Racket extension
stores Racket pointers in a global or static variable, then that
variable must be registered with
@cppi{scheme_register_extension_global}; this makes the pointer
visible to the garbage collector. Registered variables need not
@ -98,8 +98,8 @@ Collectable memory can be temporarily locked from collection by using
the reference-counting function @cppi{scheme_dont_gc_ptr}. Under 3m,
such locking does not prevent the object from being moved.
Garbage collection can occur during any call into Scheme or its
allocator, on anytime that Scheme has control, except during functions
Garbage collection can occur during any call into Racket or its
allocator, on anytime that Racket has control, except during functions
that are documented otherwise. The predicate and accessor macros
listed in @secref["im:stdtypes"] never trigger a collection.
@ -115,7 +115,7 @@ content of a word registered as a pointer must contain either
into an object allocated by @cpp{scheme_malloc_allow_interior}, a
pointer to an object currently allocated by another memory manager
(and therefore not into a block that is currently managed by the
collector), or a pointer to an odd-numbered address (e.g., a Scheme
collector), or a pointer to an odd-numbered address (e.g., a Racket
fixnum).
Pointers are registered in three different ways:
@ -158,7 +158,7 @@ retaining such a pointer can lead to a crash.
As explained in @secref["im:values+types"], the @cpp{scheme_make_type}
function can be used to obtain a new tag for a new type of object.
These new types are in relatively short supply for 3m; the maximum tag
is 255, and Scheme itself uses nearly 200.
is 255, and Racket itself uses nearly 200.
After allocating a new tag in 3m (and before creating instances of the
tag), a @defterm{size procedure}, a @defterm{mark procedure}, and a
@ -434,7 +434,7 @@ is not defined, so the macros can be placed into code to be compiled
for both conservative and precise collection.
The @cpp{MZ_GC_REG} and @cpp{MZ_GC_UNREG} macros must never be
used in an OS thread other than Scheme's thread.
used in an OS thread other than Racket's thread.
@; - - - - - - - - - - - - - - - - - - - - - - - -
@ -700,7 +700,7 @@ Frees memory allocated with @cpp{scheme_malloc_code}.}
[void* ptr]
[long size])]{
Registers an extension's global variable that can contain Scheme
Registers an extension's global variable that can contain Racket
pointers. The address of the global is given in @var{ptr}, and its
size in bytes in @var{size}.In addition to global variables, this
function can be used to register any permanent memory that the
@ -788,7 +788,7 @@ in the stack than @cpp{dummy}. To avoid these problems, use
Like @cpp{scheme_set_stack_base}, except for the extra
@var{stack_end} argument. If @var{stack_end} is non-@cpp{NULL}, then
it corresponds to a point of C-stack growth after which Scheme
it corresponds to a point of C-stack growth after which Racket
should attempt to handle stack overflow. The @var{stack_end} argument
should not correspond to the actual stack end, since detecting stack
overflow may take a few frames, and since handling stack overflow
@ -895,9 +895,9 @@ To remove an added finalizer, use @cpp{scheme_subtract_finalizer}.}
Installs a ``will''-like finalizer, similar to @scheme[will-register].
Scheme finalizers are called one at a time, requiring the collector
to prove that a value has become inaccessible again before calling
the next Scheme finalizer. Finalizers registered with
the next Racket finalizer. Finalizers registered with
@cpp{scheme_register_finalizer} or @cpp{scheme_add_finalizer} are
not called until all Scheme finalizers have been exhausted.
not called until all Racket finalizers have been exhausted.
See @cpp{scheme_register_finalizer}, above, for information about
the arguments.

16
collects/scribblings/inside/misc.scrbl
View File

@ -4,7 +4,7 @@
@title{Miscellaneous Utilities}
The @cppi{MZSCHEME_VERSION} preprocessor macro is defined as a string
describing the version of Scheme. The @cppi{MZSCHEME_VERSION_MAJOR}
describing the version of Racket. The @cppi{MZSCHEME_VERSION_MAJOR}
and @cppi{MZSCHEME_VERSION_MINOR} macros are defined as the major and
minor version numbers, respectively.
@ -35,7 +35,7 @@ Like @cpp{scheme_equal}, but accepts an extra value for cycle
tracking. This procedure is meant to be called by a procedure
installed with @cpp{scheme_set_type_equality}.}
Returns 1 if the Scheme values are @scheme[equal?].}
Returns 1 if the Racket values are @scheme[equal?].}
@function[(long scheme_equal_hash_key
[Scheme_Object* obj])]{
@ -150,13 +150,13 @@ The same as @scheme[namespace-require].}
@function[(Scheme_Object* scheme_load
[char* file])]{
Loads the specified Scheme file, returning the value of the last
Loads the specified Racket file, returning the value of the last
expression loaded, or @cpp{NULL} if the load fails.}
@function[(Scheme_Object* scheme_load_extension
[char* filename])]{
Loads the specified Scheme extension file, returning the value provided
Loads the specified Racket extension file, returning the value provided
by the extension's initialization function.}
@function[(Scheme_Hash_Table* scheme_make_hash_table
@ -170,7 +170,7 @@ table hashes on a key's pointer address, while
@cpp{SCHEME_hash_string} uses a key as a @cpp{char*} and hashes on the
null-terminated string content. Since a hash table created with
@cpp{SCHEME_hash_string} (instead of @cpp{SCHEME_hash_ptr}) does not
use a key as a Scheme value, it cannot be used from Scheme code.
use a key as a Racket value, it cannot be used from Racket code.
Although the hash table interface uses the type @cpp{Scheme_Object*}
for both keys and values, the table functions never inspect values,
@ -212,7 +212,7 @@ that will be encountered.}
@function[(Scheme_Hash_Table* scheme_make_hash_table_equal)]{
Like @cpp{scheme_make_hash_table}, except that keys are treated as
Scheme values and hashed based on @scheme[equal?] instead of
Racket values and hashed based on @scheme[equal?] instead of
@scheme[eq?].}
@function[(void scheme_hash_set
@ -334,8 +334,8 @@ Returns the current process ``time'' in milliseconds, just like
@function[(char* scheme_banner)]{
Returns the string that is used as the Scheme startup banner.}
Returns the string that is used as the Racket startup banner.}
@function[(char* scheme_version)]{
Returns a string for the executing version of Scheme.}
Returns a string for the executing version of Racket.}

18
collects/scribblings/inside/namespaces.scrbl
View File

@ -3,17 +3,17 @@
@title[#:tag "im:env"]{Namespaces and Modules}
A Scheme namespace (a top-level environment) is represented by a value
of type @cppi{Scheme_Env*} --- which is also a Scheme value, castable
A Racket namespace (a top-level environment) is represented by a value
of type @cppi{Scheme_Env*} --- which is also a Racket value, castable
to @cpp{Scheme_Object*}. Calling @cppi{scheme_basic_env} returns a
namespace that includes all of Scheme's standard global procedures
namespace that includes all of Racket's standard global procedures
and syntax.
The @cpp{scheme_basic_env} function must be called once by an
embedding program, before any other PLT Scheme function is called
embedding program, before any other Racket function is called
(except @cpp{scheme_make_param}), but @cpp{scheme_main_setup}
automatically calls @cpp{scheme_basic_env}. The returned namespace is
the initial current namespace for the main Scheme thread. Scheme
the initial current namespace for the main Racket thread. Racket
extensions cannot call @cpp{scheme_basic_env}.
The current thread's current namespace is available from
@ -22,7 +22,7 @@ The current thread's current namespace is available from
New values can be added as @as-index{globals} in a namespace using
@cppi{scheme_add_global}. The @cppi{scheme_lookup_global} function
takes a Scheme symbol and returns the global value for that name, or
takes a Racket symbol and returns the global value for that name, or
@cpp{NULL} if the symbol is undefined.
A @as-index{module}'s set of top-level bindings is implemented using
@ -37,8 +37,8 @@ module files). After installing variables into the module with
to make the module declaration available. All defined variables are
exported from the primitive module.
The Scheme @indexed-scheme[#%variable-reference] form produces a value
that is opaque to Scheme code. Use @cpp{SCHEME_PTR_VAL} on the result
The Racket @indexed-scheme[#%variable-reference] form produces a value
that is opaque to Racket code. Use @cpp{SCHEME_PTR_VAL} on the result
of @scheme[#%variable-reference] to obtain the same kind of value as
returned by @cpp{scheme_global_bucket} (i.e., a bucket containing the
variable's value, or @cpp{NULL} if the variable is not yet defined).
@ -95,7 +95,7 @@ The @cppi{Scheme_Bucket} structure is defined as:
Like @cpp{scheme_global_bucket}, but finds a variable in a
module. The @var{mod} and @var{symbol} arguments are as for
@scheme[dynamic-require] in Scheme. The @var{pos} argument should be
@scheme[dynamic-require] in Racket. The @var{pos} argument should be
@cpp{-1} always. The @var{env} argument represents the namespace in
which the module is declared.}

12
collects/scribblings/inside/numbers.scrbl
View File

@ -3,9 +3,9 @@
@title{Bignums, Rationals, and Complex Numbers}
Scheme supports integers of an arbitrary magnitude; when an integer
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
bit), then it is represented by the Scheme type
bit), then it is represented by the Racket type
@cppi{scheme_bignum_type}. There is no overlap in integer values
represented by fixnums and bignums.
@ -60,7 +60,7 @@ unspecified accuracy.}
@function[(float scheme_bignum_to_float
[Scheme_Object* n])]{
If PLT Scheme is not compiled with single-precision floats, this procedure
If Racket is not compiled with single-precision floats, this procedure
is actually a macro alias for @cpp{scheme_bignum_to_double}.}
@function[(Scheme_Object* scheme_bignum_from_double
@ -72,7 +72,7 @@ number @var{d}. The conversion accuracy is reasonable but unspecified.}
@function[(Scheme_Object* scheme_bignum_from_float
[float f])]{
If PLT Scheme is not compiled with single-precision floats, this procedure
If Racket is not compiled with single-precision floats, this procedure
is actually a macro alias for @cpp{scheme_bignum_from_double}.}
@function[(char* scheme_bignum_to_string
@ -121,7 +121,7 @@ Converts the rational @var{n} to a @cpp{double}.}
@function[(float scheme_rational_to_float
[Scheme_Object* n])]{
If PLT Scheme is not compiled with single-precision floats, this procedure
If Racket is not compiled with single-precision floats, this procedure
is actually a macro alias for @cpp{scheme_rational_to_double}.}
@function[(Scheme_Object* scheme_rational_numerator
@ -142,7 +142,7 @@ Converts the given @cpp{double} into a maximally-precise rational.}
@function[(Scheme_Object* scheme_rational_from_float
[float d])]{
If PLT Scheme is not compiled with single-precision floats, this procedure
If Racket is not compiled with single-precision floats, this procedure
is actually a macro alias for @cpp{scheme_rational_from_double}.}
@function[(Scheme_Object* scheme_make_complex

246
collects/scribblings/inside/overview.scrbl
View File

@ -3,21 +3,31 @@
@title[#:tag "overview"]{Overview}
@section{``Scheme'' versus ``Racket''}
The old name for Racket was ``PLT Scheme,'' and the core compiler and
run-time system used to be called ``MzScheme.'' The old names are
entrenched in Racket internals, to the point that most C bindings
defined in this manual start with @cpp{scheme_}. They all should be
renamed to start @cpp{racket_}.
@; ----------------------------------------------------------------------
@section{CGC versus 3m}
Before mixing any C code with MzScheme, first decide whether to use
the @bold{3m} variant of PLT Scheme, the @bold{CGC} variant of PLT
Scheme, or both:
Before mixing any C code with Racket, 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 PLT Scheme, which
@item{@bold{@as-index{3m}} : the main variant of Racket, which
uses @defterm{precise} garbage collection instead of conservative
garbage collection, and it may move objects in memory during a
collection.}
@item{@bold{@as-index{CGC}} : the original variant of PLT Scheme,
where memory management depends on a @defterm{conservative} garbage
@item{@bold{@as-index{CGC}} : the original variant of Racket, 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
platforms) static variables.}
@ -29,9 +39,9 @@ At the C level, working with CGC can be much easier than working with
@; ----------------------------------------------------------------------
@section{Writing MzScheme Extensions}
@section{Writing Racket Extensions}
@section-index["extending MzScheme"]
@section-index["extending Racket"]
The process of creating an extension for 3m or CGC is essentially the
same, but the process for 3m is most easily understood as a variant of
@ -40,41 +50,41 @@ the process for CGC.
@subsection{CGC Extensions}
To write a C/C++-based extension for PLT Scheme CGC, follow these
To write a C/C++-based extension for Racket CGC, follow these
steps:
@itemize[
@item{@index['("header files")]{For} each C/C++ file that uses PLT
Scheme library functions, @cpp{#include} the file
@item{@index['("header files")]{For} each C/C++ file that uses
Racket library functions, @cpp{#include} the file
@as-index{@filepath{escheme.h}}.
This file is distributed with the PLT software in an
@filepath{include} directory, but if @|mzc| is used to compile, this
path is found automatically.}
This file is distributed with the Racket software in an
@filepath{include} directory, but if @|mzc| is used to
compile, this path is found automatically.}
@item{Define the C function @cppi{scheme_initialize}, which takes a
@cpp{Scheme_Env*} namespace (see @secref["im:env"]) and returns a
@cpp{Scheme_Object*} Scheme value.
@cpp{Scheme_Object*} Racket value.
This initialization function can install new global primitive
procedures or other values into the namespace, or it can simply
return a Scheme value. The initialization function is called when the
extension is loaded with @scheme[load-extension] (the first time);
return a Racket value. The initialization function is called when the
extension is loaded with @racket[load-extension] (the first time);
the return value from @cpp{scheme_initialize} is used as the return
value for @scheme[load-extension]. The namespace provided to
value for @racket[load-extension]. The namespace provided to
@cpp{scheme_initialize} is the current namespace when
@scheme[load-extension] is called.}
@racket[load-extension] is called.}
@item{Define the C function @cppi{scheme_reload}, which has the same
arguments and return type as @cpp{scheme_initialize}.
This function is called if @scheme[load-extension] is called a second
This function is called if @racket[load-extension] is called a second
time (or more times) for an extension. Like @cpp{scheme_initialize},
the return value from this function is the return value for
@scheme[load-extension].}
@racket[load-extension].}
@item{Define the C function @cppi{scheme_module_name}, which takes
@ -84,7 +94,7 @@ steps:
The function should return a symbol when the effect of calling
@cpp{scheme_initialize} and @cpp{scheme_reload} is only to declare
a module with the returned name. This function is called when the
extension is loaded to satisfy a @scheme[require] declaration.
extension is loaded to satisfy a @racket[require] declaration.
The @cpp{scheme_module_name} function may be called before
@cpp{scheme_initialize} and @cpp{scheme_reload}, after those
@ -95,7 +105,7 @@ steps:
@item{Compile the extension C/C++ files to create platform-specific
object files.
The @as-index{@|mzc|} compiler, which is distributed with PLT Scheme,
The @as-index{@|mzc|} compiler, which is distributed with Racket,
compiles plain C files when the @as-index{@DFlag{cc}} flag is
specified. More precisely, @|mzc| does not compile the files itself,
but it locates a C compiler on the system and launches it with the
@ -104,7 +114,7 @@ steps:
compiler or @exec{gcc} in the path, or a Mac OS X system with Apple's
developer tools installed, then using @|mzc| is typically easier than
working with the C compiler directly. Use the @as-index{@DFlag{cgc}}
flag to indicate that the build is for use with PLT Scheme CGC.}
flag to indicate that the build is for use with Racket CGC.}
@item{Link the extension C/C++ files with
@ -115,50 +125,50 @@ steps:
The @filepath{mzdyn} object file is distributed in the installation's
@filepath{lib} directory. For Windows, the object file is in a
compiler-specific sub-directory of @filepath{plt\lib}.
compiler-specific sub-directory of @filepath{racket\lib}.
The @|mzc| compiler links object files into an extension when the
@as-index{@DFlag{ld}} flag is specified, automatically locating
@filepath{mzdyn}. Again, use the @DFlag{cgc} flag with @|mzc|.}
@item{Load the shared object within Scheme using
@scheme[(load-extension _path)], where @scheme[_path] is the name of
@item{Load the shared object within Racket using
@racket[(load-extension _path)], where @racket[_path] is the name of
the extension file generated in the previous step.
Alternately, if the extension defines a module (i.e.,
@cpp{scheme_module_name} returns a symbol), then place the shared
object in a special directory with a special name, so that it is
detected by the module loader when @scheme[require] is used. The
detected by the module loader when @racket[require] is used. The
special directory is a platform-specific path that can be obtained by
evaluating @scheme[(build-path "compiled" "native"
(system-library-subpath))]; see @scheme[load/use-compiled] for more
evaluating @racket[(build-path "compiled" "native"
(system-library-subpath))]; see @racket[load/use-compiled] for more
information. For example, if the shared object's name is
@filepath{example_ss.dll}, then @scheme[(require "example.ss")] will
be redirected to @filepath{example_ss.dll} if the latter is placed in
the sub-directory @scheme[(build-path "compiled" "native"
(system-library-subpath))] and if @filepath{example.ss} does not
@filepath{example_rkt.dll}, then @racket[(require "example.rkt")] will
be redirected to @filepath{example_rkt.dll} if the latter is placed in
the sub-directory @racket[(build-path "compiled" "native"
(system-library-subpath))] and if @filepath{example.rkt} does not
exist or has an earlier timestamp.
Note that @scheme[(load-extension _path)] within a @scheme[module]
Note that @racket[(load-extension _path)] within a @racket[module]
does @italic{not} introduce the extension's definitions into the
module, because @scheme[load-extension] is a run-time operation. To
module, because @racket[load-extension] is a run-time operation. To
introduce an extension's bindings into a module, make sure that the
extension defines a module, put the extension in the
platform-specific location as described above, and use
@scheme[require].}
@racket[require].}
]
@index['("allocation")]{@bold{IMPORTANT:}} With PLT Scheme CGC, Scheme
@index['("allocation")]{@bold{IMPORTANT:}} With Racket CGC, Racket
values are garbage collected using a conservative garbage collector,
so pointers to Scheme objects can be kept in registers, stack
so pointers to Racket objects can be kept in registers, stack
variables, or structures allocated with @cppi{scheme_malloc}. However,
static variables that contain pointers to collectable memory must be
registered using @cppi{scheme_register_extension_global} (see
@secref["im:memoryalloc"]).
As an example, the following C code defines an extension that returns
@scheme["hello world"] when it is loaded:
@racket["hello world"] when it is loaded:
@verbatim[#:indent 2]{
#include "escheme.h"
@ -176,18 +186,18 @@ As an example, the following C code defines an extension that returns
Assuming that this code is in the file @filepath{hw.c}, the extension
is compiled under Unix with the following two commands:
@commandline{mzc --cgc --cc hw.c}
@commandline{mzc --cgc --ld hw.so hw.o}
@commandline{raco ctool --cgc --cc hw.c}
@commandline{raco ctool --cgc --ld hw.so hw.o}
(Note that the @DFlag{cgc}, @DFlag{cc}, and @DFlag{ld} flags are each
prefixed by two dashes, not one.)
The @filepath{collects/mzscheme/examples} directory in the PLT
The @filepath{collects/mzscheme/examples} directory in the Racket
distribution contains additional examples.
@subsection{3m Extensions}
To build an extension to work with PLT Scheme 3m, the CGC instructions
To build an extension to work with Racket 3m, the CGC instructions
must be extended as follows:
@itemize[
@ -213,12 +223,12 @@ must be extended as follows:
For a relatively simple extension @filepath{hw.c}, the extension is
compiled under Unix for 3m with the following three commands:
@commandline{mzc --xform hw.c}
@commandline{mzc --3m --cc hw.3m.c}
@commandline{mzc --3m --ld hw.so hw.o}
@commandline{raco ctool --xform hw.c}
@commandline{raco ctool --3m --cc hw.3m.c}
@commandline{raco ctool --3m --ld hw.so hw.o}
Some examples in @filepath{collects/mzscheme/examples} work with
MzScheme3m in this way. A few examples are manually instrumented, in
Racket 3m in this way. A few examples are manually instrumented, in
which case the @DFlag{xform} step should be skipped.
@subsection{Declaring a Module in an Extension}
@ -228,7 +238,7 @@ To create an extension that behaves as a module, return a symbol from
@cpp{scheme_rename} declare a module using @cpp{scheme_primitive_module}.
For example, the following extension implements a module named
@scheme[hello] that exports a binding @scheme[greeting]:
@racket[hello] that exports a binding @racket[greeting]:
@verbatim[#:indent 2]{
#include "escheme.h"
@ -253,96 +263,96 @@ For example, the following extension implements a module named
}
}
This extension could be compiled for 3m on Mac OS X for i386, for
This extension could be compiled for 3m on i386 Linux, for
example, using the following sequence of @exec{mzc} commands:
@commandline{mzc --xform hi.c}
@commandline{mzc --3m --cc hi.3m.c}
@commandline{mkdir -p compiled/native/i386-macosx/3m}
@commandline{mzc --3m --ld compiled/native/i386-macosx/3m/hi_ss.dylib hi_3m.o}
@commandline{raco ctool --xform hi.c}
@commandline{raco ctool --3m --cc hi.3m.c}
@commandline{mkdir -p compiled/native/i386-linux/3m}
@commandline{raco ctool --3m --ld compiled/native/i386-linux/3m/hi_rkt.so hi_3m.o}
The resulting module can be loaded with
@schemeblock[(require "hi.ss")]
@racketblock[(require "hi.rkt")]
@; ----------------------------------------------------------------------
@section[#:tag "embedding"]{Embedding MzScheme into a Program}
@section[#:tag "embedding"]{Embedding Racket into a Program}
@section-index["embedding MzScheme"]
@section-index["embedding Racket"]
Like creating extensions, the embedding process for PLT Scheme CGC or
PLT Scheme 3m is essentially the same, but the process for PLT Scheme
Like creating extensions, the embedding process for Racket CGC or
Racket 3m is essentially the same, but the process for Racket
3m is most easily understood as a variant of the process for
PLT Scheme CGC.
Racket CGC.
@subsection{CGC Embedding}
To embed PLT Scheme CGC in a program, follow these steps:
To embed Racket CGC in a program, follow these steps:
@itemize[
@item{Locate or build the PLT Scheme CGC libraries. Since the
@item{Locate or build the Racket CGC libraries. Since the
standard distribution provides 3m libraries, only, you will most
likely have to build from source.
Under Unix, the libraries are @as-index{@filepath{libmzscheme.a}}
Under Unix, the libraries are @as-index{@filepath{libracket.a}}
and @as-index{@filepath{libmzgc.a}} (or
@as-index{@filepath{libmzscheme.so}} and
@as-index{@filepath{libracket.so}} and
@as-index{@filepath{libmzgc.so}} for a dynamic-library build, with
@as-index{@filepath{libmzscheme.la}} and
@as-index{@filepath{libracket.la}} and
@as-index{@filepath{libmzgc.la}} files for use with
@exec{libtool}). Building from source and installing places the
libraries into the installation's @filepath{lib} directory. Be sure
to build the CGC variant, since the default is 3m.
Under Windows, stub libraries for use with Microsoft tools are
@filepath{libmzsch@italic{x}.lib} and
@filepath{libracket@italic{x}.lib} and
@filepath{libmzgc@italic{x}.lib} (where @italic{x} represents the
version number) are in a compiler-specific directory in
@filepath{plt\lib}. These libraries identify the bindings that are
provided by @filepath{libmzsch@italic{x}.dll} and
@filepath{racket\lib}. These libraries identify the bindings that are
provided by @filepath{libracket@italic{x}.dll} and
@filepath{libmzgc@italic{x}.dll} --- which are typically installed
in @filepath{plt\lib}. When linking with Cygwin, link to
@filepath{libmzsch@italic{x}.dll} and
in @filepath{racket\lib}. When linking with Cygwin, link to
@filepath{libracket@italic{x}.dll} and
@filepath{libmzgc@italic{x}.dll} directly. At run time, either
@filepath{libmzsch@italic{x}.dll} and
@filepath{libracket@italic{x}.dll} and
@filepath{libmzgc@italic{x}.dll} must be moved to a location in the
standard DLL search path, or your embedding application must
``delayload'' link the DLLs and explicitly load them before
use. (@filepath{MzScheme.exe} and @filepath{MrEd.exe} use the latter
use. (@filepath{Racket.exe} and @filepath{MrEd.exe} use the latter
strategy.)
Under Mac OS X, dynamic libraries are provided by the
@filepath{PLT_MzScheme} framework, which is typically installed in
@filepath{Racket} framework, which is typically installed in
@filepath{lib} sub-directory of the installation. Supply
@exec{-framework PLT_MzScheme} to @exec{gcc} when linking, along
@exec{-framework Racket} to @exec{gcc} when linking, along
with @exec{-F} and a path to the @filepath{lib} directory. Beware
that CGC and 3m libraries are installed as different versions within
a single framework, and installation marks one version or the other
as the default (by setting symbolic links); install only CGC to
simplify accessing the CGC version within the framework. At run
time, either @filepath{PLT_MzScheme.framework} must be moved to a
time, either @filepath{Racket.framework} must be moved to a
location in the standard framework search path, or your embedding
executable must provide a specific path to the framework (possibly
an executable-relative path using the Mach-O @tt["@executable_path"]
prefix).}
@item{For each C/C++ file that uses MzScheme library functions,
@item{For each C/C++ file that uses Racket library functions,
@cpp{#include} the file @as-index{@filepath{scheme.h}}.
The C preprocessor symbol @cppi{SCHEME_DIRECT_EMBEDDED} is defined
as @cpp{1} when @filepath{scheme.h} is @cpp{#include}d, or as
@cpp{0} when @filepath{escheme.h} is @cpp{#include}d.
The @filepath{scheme.h} file is distributed with the PLT software in
The @filepath{scheme.h} file is distributed with the Racket software in
the installation's @filepath{include} directory. Building and
installing from source also places this file in the installation's
@filepath{include} directory.}
@item{Start your main program through the @cpp{scheme_main_setup} (or
@cpp{scheme_main_stack_setup}) trampoline, and put all uses of
MzScheme functions inside the function passed to
Racket functions inside the function passed to
@cpp{scheme_main_setup}. The @cpp{scheme_main_setup} function
registers the current C stack location with the memory manager. It
also creates the initial namespace @cpp{Scheme_Env*} by calling
@ -353,11 +363,11 @@ To embed PLT Scheme CGC in a program, follow these steps:
@item{Configure the namespace by adding module declarations. The
initial namespace contains declarations only for a few primitive
modules, such as @scheme['#%kernel], and no bindings are imported
modules, such as @racket['#%kernel], and no bindings are imported
into the top-level environment.
To embed a module like @schememodname[scheme/base] (along with all
its dependencies), use @exec{mzc --c-mods}, which generates a C file
To embed a module like @racketmodname[racket/base] (along with all
its dependencies), use @exec{raco ctool --c-mods}, which generates a C file
that contains modules in bytecode form as encapsulated in a static
array. The generated C file defines a @cppi{declare_modules}
function that takes a @cpp{Scheme_Env*}, installs the modules into
@ -368,7 +378,7 @@ To embed PLT Scheme CGC in a program, follow these steps:
@cpp{scheme_init_collection_paths} to configure and install a path
for finding modules at run time.}
@item{Access Scheme through @cppi{scheme_dynamic_require},
@item{Access Racket through @cppi{scheme_dynamic_require},
@cppi{scheme_load}, @cppi{scheme_eval}, and/or other functions
described in this manual.
@ -379,13 +389,13 @@ To embed PLT Scheme CGC in a program, follow these steps:
certain privileged operations, such as installing a @|PLaneT|
package.}
@item{Compile the program and link it with the MzScheme libraries.}
@item{Compile the program and link it with the Racket libraries.}
]
@index['("allocation")]{With} PLT Scheme CGC, Scheme values are
@index['("allocation")]{With} Racket CGC, Racket values are
garbage collected using a conservative garbage collector, so pointers
to Scheme objects can be kept in registers, stack variables, or
to Racket objects can be kept in registers, stack variables, or
structures allocated with @cppi{scheme_malloc}. In an embedding
application on some platforms, static variables are also automatically
registered as roots for garbage collection (but see notes below
@ -393,12 +403,12 @@ specific to Mac OS X and Windows).
For example, the following is a simple embedding program which
evaluates all expressions provided on the command line and displays
the results, then runs a @scheme[read]-@scheme[eval]-@scheme[print]
the results, then runs a @racket[read]-@racket[eval]-@racket[print]
loop. Run
@commandline{mzc --c-mods base.c ++lib scheme/base}
@commandline{raco ctool --c-mods base.c ++lib racket/base}
to generate @filepath{base.c}, which encapsulates @scheme[scheme/base]
to generate @filepath{base.c}, which encapsulates @racket[racket/base]
and all of its transitive imports (so that they need not be found
separately a run time).
@ -416,7 +426,7 @@ static int run(Scheme_Env *e, int argc, char *argv[])
/* Declare embedded modules in "base.c": */
declare_modules(e);
scheme_namespace_require(scheme_intern_symbol("scheme/base"));
scheme_namespace_require(scheme_intern_symbol("racket/base"));
curout = scheme_get_param(scheme_current_config(),
MZCONFIG_OUTPUT_PORT);
@ -433,7 +443,7 @@ static int run(Scheme_Env *e, int argc, char *argv[])
scheme_display(v, curout);
scheme_display(scheme_make_char('\n'), curout);
/* read-eval-print loop, uses initial Scheme_Env: */
a[0] = scheme_intern_symbol("scheme/base");
a[0] = scheme_intern_symbol("racket/base");
a[1] = scheme_intern_symbol("read-eval-print-loop");
scheme_apply(scheme_dynamic_require(2, a), 0, NULL);
scheme_current_thread->error_buf = save;
@ -448,7 +458,7 @@ int main(int argc, char *argv[])
}
}
Under Mac OS X, or under Windows when MzScheme is compiled to a DLL
Under Mac OS X, or under Windows when Racket is compiled to a DLL
using Cygwin, the garbage collector cannot find static variables
automatically. In that case, @cppi{scheme_main_setup} must be called with a
non-zero first argument.
@ -467,7 +477,7 @@ pointer. For example, if @cpp{curout} above is made @cpp{static}, then
@cpp{MZ_REGISTER_STATIC(curout)} should be inserted before the call to
@cpp{scheme_get_param}.
When building an embedded MzSchemeCGC to use SenoraGC (SGC) instead of
When building an embedded Racket CGC to use SenoraGC (SGC) instead of
the default collector, @cpp{scheme_main_setup} must be called with a
non-zero first argument. See @secref["im:memoryalloc"] for more
information.
@ -475,7 +485,7 @@ information.
@subsection{3m Embedding}
MzScheme3m can be embedded mostly the same as MzScheme, as long as the
Racket 3m can be embedded mostly the same as Racket, as long as the
embedding program cooperates with the precise garbage collector as
described in @secref["im:3m"].
@ -489,31 +499,31 @@ In addition, some library details are different:
@itemize[
@item{Under Unix, the library is just
@as-index{@filepath{libmzscheme3m.a}} (or
@as-index{@filepath{libmzscheme3m.so}} for a dynamic-library build,
with @as-index{@filepath{libmzscheme3m.la}} for use with
@as-index{@filepath{libracket3m.a}} (or
@as-index{@filepath{libracket3m.so}} for a dynamic-library build,
with @as-index{@filepath{libracket3m.la}} for use with
@exec{libtool}). There is no separate library for 3m analogous to
CGC's @filepath{libmzgc.a}.}
@item{Under Windows, the stub library for use with Microsoft tools is
@filepath{libmzsch3m@italic{x}.lib} (where @italic{x} represents the
@filepath{libracket3m@italic{x}.lib} (where @italic{x} represents the
version number). This library identifies the bindings that are
provided by @filepath{libmzsch3m@italic{x}.dll}. There is no
provided by @filepath{libracket3m@italic{x}.dll}. There is no
separate library for 3m analogous to CGC's
@filepath{libmzgc@italic{x}.lib}.}
@item{Under Mac OS X, 3m dynamic libraries are provided by the
@filepath{PLT_MzScheme} framework, just as for CGC, but as a version
@filepath{Racket} framework, just as for CGC, but as a version
suffixed with @filepath{_3m}.}
]
For MzScheme3m, an embedding application must call @cpp{scheme_main_setup}
For Racket 3m, an embedding application must call @cpp{scheme_main_setup}
with a non-zero first argument.
The simple embedding program from the previous section can be
processed by @exec{mzc --xform}, then compiled and linked with
MzScheme3m. Alternately, the source code can be extended to work with
processed by @exec{raco ctool --xform}, then compiled and linked with
Racket 3m. Alternately, the source code can be extended to work with
either CGC or 3m depending on whether @cpp{MZ_PRECISE_GC} is defined
on the compiler's command line:
@ -541,7 +551,7 @@ static int run(Scheme_Env *e, int argc, char *argv[])
declare_modules(e);
v = scheme_intern_symbol("scheme/base");
v = scheme_intern_symbol("racket/base");
scheme_namespace_require(v);
config = scheme_current_config();
@ -559,7 +569,7 @@ static int run(Scheme_Env *e, int argc, char *argv[])
v = scheme_make_char('\n');
scheme_display(v, curout);
/* read-eval-print loop, uses initial Scheme_Env: */
a[0] = scheme_intern_symbol("scheme/base");
a[0] = scheme_intern_symbol("racket/base");
a[1] = scheme_intern_symbol("read-eval-print-loop");
v = scheme_dynamic_require(2, a);
scheme_apply(v, 0, NULL);
@ -586,22 +596,22 @@ and when all temporary values are put into variables.
@; ----------------------------------------------------------------------
@section{MzScheme and Threads}
@section{Racket and Threads}
MzScheme implements threads for Scheme programs without aid from the
operating system, so that MzScheme threads are cooperative from the
perspective of C code. Under Unix, stand-alone MzScheme uses a single
Racket implements threads for Racket programs without aid from the
operating system, so that Racket threads are cooperative from the
perspective of C code. Under Unix, stand-alone Racket uses a single
OS-implemented thread. Under Windows and Mac OS X, stand-alone
MzScheme uses a few private OS-implemented threads for background
Racket uses a few private OS-implemented threads for background
tasks, but these OS-implemented threads are never exposed by the
MzScheme API.
Racket API.
In an embedding application, MzScheme can co-exist with additional
In an embedding application, Racket can co-exist with additional
OS-implemented threads, but the additional OS threads must not call
any @cpp{scheme_} function. Only the OS thread that originally calls
@cpp{scheme_basic_env} can call @cpp{scheme_} functions. (This
restriction is stronger than saying all calls must be serialized
across threads. MzScheme relies on properties of specific threads to
across threads. Racket relies on properties of specific threads to
avoid stack overflow and garbage collection.) When
@cpp{scheme_basic_env} is called a second time to reset the
interpreter, it can be called in an OS thread that is different from
@ -609,19 +619,19 @@ the original call to @cpp{scheme_basic_env}. Thereafter, all calls to
@cpp{scheme_} functions must originate from the new thread.
See @secref["threads"] for more information about threads, including
the possible effects of MzScheme's thread implementation on extension
the possible effects of Racket's thread implementation on extension
and embedding C code.
@; ----------------------------------------------------------------------
@section[#:tag "im:unicode"]{MzScheme, Unicode, Characters, and Strings}
@section[#:tag "im:unicode"]{Racket, Unicode, Characters, and Strings}
A character in MzScheme is a Unicode code point. In C, a character
A character in Racket is a Unicode code point. In C, a character
value has type @cppi{mzchar}, which is an alias for @cpp{unsigned} ---
which is, in turn, 4 bytes for a properly compiled MzScheme. Thus, a
which is, in turn, 4 bytes for a properly compiled Racket. Thus, a
@cpp{mzchar*} string is effectively a UCS-4 string.
Only a few MzScheme functions use @cpp{mzchar*}. Instead, most
Only a few Racket functions use @cpp{mzchar*}. Instead, most
functions accept @cpp{char*} strings. When such byte strings are to be
used as a character strings, they are interpreted as UTF-8
encodings. A plain ASCII string is always acceptable in such cases,
@ -633,7 +643,7 @@ See also @secref["im:strings"] and @secref["im:encodings"].
@section[#:tag "im:intsize"]{Integers}
MzScheme expects to be compiled in a mode where @cppi{short} is a
Racket expects to be compiled in a mode where @cppi{short} is a
16-bit integer, @cppi{int} is a 32-bit integer, and @cppi{long} has
the same number of bits as @cpp{void*}. The @cppi{mzlonglong} type has
64 bits for compilers that support a 64-bit integer type, otherwise it

40
collects/scribblings/inside/ports.scrbl
View File

@ -3,7 +3,7 @@
@title{Ports and the Filesystem}
Ports are represented as Scheme values with the types
Ports are represented as Racket values with the types
@cppi{scheme_input_port_type} and @cppi{scheme_output_port_type}. The
function @cppi{scheme_read} takes an input port value and returns the
next S-expression from the port. The function @cppi{scheme_write}
@ -23,7 +23,7 @@ The contents of a string output port are obtained with
Custom ports, with arbitrary read/write handlers, are created with
@cppi{scheme_make_input_port} and @cppi{scheme_make_output_port}.
When opening a file for any reason using a name provided from Scheme,
When opening a file for any reason using a name provided from Racket,
use @cppi{scheme_expand_filename} to normalize the filename and
resolve relative paths.
@ -50,7 +50,7 @@ Like @cpp{scheme_write}, but the printing is truncated to @var{n} bytes.
[Scheme_Object* obj]
[Scheme_Object* port])]{
@scheme[display]s the Scheme value @var{obj} to the given output
@scheme[display]s the Racket value @var{obj} to the given output
port.}
@function[(void scheme_display_w_max
@ -119,7 +119,7 @@ without the non-blocking option.}
[Scheme_Object* obj]
[long* len])]{
Prints the Scheme value @var{obj} using @scheme[write] to a newly
Prints the Racket value @var{obj} using @scheme[write] to a newly
allocated string. If @var{len} is not @cpp{NULL}, @cpp{*@var{len}} is
set to the length of the bytes string.}
@ -136,7 +136,7 @@ Like @cpp{scheme_write_to_string}, but the string is truncated to
[Scheme_Object* obj]
[long* len])]{
Prints the Scheme value @var{obj} using @scheme[display] to a newly
Prints the Racket value @var{obj} using @scheme[display] to a newly
allocated string. If @var{len} is not @cpp{NULL}, @cpp{*@var{len}} is
set to the length of the string.}
@ -154,7 +154,7 @@ Like @cpp{scheme_display_to_string}, but the string is truncated to
@function[(void scheme_debug_print
[Scheme_Object* obj])]{
Prints the Scheme value @var{obj} using @scheme[write] to the main
Prints the Racket value @var{obj} using @scheme[write] to the main
thread's output port.}
@function[(void scheme_flush_output
@ -423,7 +423,7 @@ The functions are as follows.
in @var{unless} becomes ready before bytes can be read. In
particular, @var{get_bytes_fun} should check the event in
@var{unless} before taking any action, and it should check the
event in @var{unless} after any operation that may allow Scheme
event in @var{unless} after any operation that may allow Racket
thread swaps. If the read must block, then it should unblock if
the event in @var{unless} becomes ready.
@ -439,7 +439,7 @@ The functions are as follows.
use @cpp{scheme_block_until_unless} instead of
@cpp{scheme_block_until}. Finally, in blocking mode,
@var{get_bytes_fun} must return after immediately reading data,
without allowing a Scheme thread swap.}
without allowing a Racket thread swap.}
@subfunction[(long peek_bytes_fun
[Scheme_Input_Port* port]
@ -652,7 +652,7 @@ Opens @var{filename} for reading. In an exception is raised, the
[FILE* fp]
[Scheme_Object* name])]{
Creates a Scheme input file port from an ANSI C file pointer. The file
Creates a Racket input file port from an ANSI C file pointer. The file
must never block on reads. The @var{name} argument is used as the
port's name.}
@ -667,7 +667,7 @@ Opens @var{filename} for writing in @scheme['truncate/replace] mode. If
@function[(Scheme_Object* scheme_make_file_output_port
[FILE* fp])]{
Creates a Scheme output file port from an ANSI C file pointer. The
Creates a Racket output file port from an ANSI C file pointer. The
file must never block on writes.}
@function[(Scheme_Object* scheme_make_fd_input_port
@ -676,7 +676,7 @@ Creates a Scheme output file port from an ANSI C file pointer. The
[int regfile]
[int win_textmode])]{
Creates a Scheme input port for a file descriptor @var{fd}. Under
Creates a Racket input port for a file descriptor @var{fd}. Under
Windows, @var{fd} can be a @cpp{HANDLE} for a stream, and it should
never be a file descriptor from the C library or a WinSock socket.
@ -702,7 +702,7 @@ Instead of calling both @cpp{scheme_make_fd_input_port} and
[int win_textmode]
[int read_too])]{
Creates a Scheme output port for a file descriptor @var{fd}. Under
Creates a Racket output port for a file descriptor @var{fd}. Under
Windows, @var{fd} can be a @cpp{HANDLE} for a stream, and it should
never be a file descriptor from the C library or a WinSock socket.
@ -729,7 +729,7 @@ If @var{read_too} is non-zero, the function produces multiple values
[Scheme_Object** inp]
[Scheme_Object** outp])]{
Creates Scheme input and output ports for a TCP socket @var{s}. The
Creates Racket input and output ports for a TCP socket @var{s}. The
@var{name} argument supplies the name for the ports. If @var{close}
is non-zero, then the ports assume responsibility for closing the
socket. The resulting ports are written to @var{inp} and @var{outp}.}
@ -737,13 +737,13 @@ Creates Scheme input and output ports for a TCP socket @var{s}. The
@function[(Scheme_Object* scheme_make_byte_string_input_port
[char* str])]{
Creates a Scheme input port from a byte string; successive
Creates a Racket input port from a byte string; successive
@scheme[read-char]s on the port return successive bytes in the
string.}
@function[(Scheme_Object* scheme_make_byte_string_output_port)]{
Creates a Scheme output port; all writes to the port are kept in a byte string,
Creates a Racket output port; all writes to the port are kept in a byte string,
which can be obtained with @cpp{scheme_get_byte_string_output}.}
@function[(char* scheme_get_byte_string_output
@ -843,12 +843,12 @@ character string or a path value.}
@function[(Scheme_Object* scheme_char_string_to_path
[Scheme_Object* s])]{
Converts a Scheme character string into a Scheme path value.}
Converts a Racket character string into a Racket path value.}
@function[(Scheme_Object* scheme_path_to_char_string
[Scheme_Object* s])]{
Converts a Scheme path value into a Scheme character string.}
Converts a Racket path value into a Racket character string.}
@function[(Scheme_Object* scheme_make_path
[char* bytes])]{
@ -923,7 +923,7 @@ no 0, then an exception is raised if the operation fails.}
[int noexn])]{
Sets the current working directory according to the operating system. This
is separate from MzScheme's current directory parameter.
is separate from Racket's current directory parameter.
If @var{noexn} is not 0, then an exception is raised if the operation
fails.}
@ -935,7 +935,7 @@ fails.}
[Scheme_Object** argv]
[long* rlen])]{
Creates a string like MzScheme's @scheme[format] procedure, using the
Creates a string like Racket's @scheme[format] procedure, using the
format string @var{format} (of length @var{flen}) and the extra
arguments specified in @var{argc} and @var{argv}. If @var{rlen} is not
@cpp{NULL}, @cpp{*@var{rlen}} is filled with the length of the
@ -947,7 +947,7 @@ resulting string.}
[int argc]
[Scheme_Object** argv])]{
Writes to the current output port like MzScheme's @scheme[printf]
Writes to the current output port like Racket's @scheme[printf]
procedure, using the format string @var{format} (of length @var{flen})
and the extra arguments specified in @var{argc} and @var{argv}.}

10
collects/scribblings/inside/procedures.scrbl
View File

@ -3,11 +3,11 @@
@title{Procedures}
A @defterm{primitive procedure} is a Scheme-callable procedure that is
implemented in C. Primitive procedures are created in Scheme with
A @defterm{primitive procedure} is a Racket-callable procedure that is
implemented in C. Primitive procedures are created in Racket with
the function @cppi{scheme_make_prim_w_arity}, which takes a C function
pointer, the name of the primitive, and information about the number
of Scheme arguments that it takes; it returns a Scheme procedure
of Racket arguments that it takes; it returns a Racket procedure
value.
The C function implementing the procedure must take two arguments: an
@ -15,7 +15,7 @@ integer that specifies the number of arguments passed to the
procedure, and an array of @cpp{Scheme_Object*} arguments. The number
of arguments passed to the function will be checked using the arity
information. (The arity information provided to
@cpp{scheme_make_prim_w_arity} is also used for the Scheme
@cpp{scheme_make_prim_w_arity} is also used for the Racket
@scheme[arity] procedure.) The procedure implementation is not allowed
to mutate the input array of arguments; as an exception, the procedure
can mutate the array if it is the same a the result of
@ -60,7 +60,7 @@ maximum number of arguments that can be supplied to the procedure, or
-1 if the procedure can take arbitrarily many arguments. The
@var{mina} and @var{maxa} values are used for automatically checking
the argument count before the primitive is invoked, and also for the
Scheme @indexed-scheme[arity] procedure. The @var{name} argument is
Racket @indexed-scheme[arity] procedure. The @var{name} argument is
used to report application arity errors at run-time.}
@function[(Scheme_Object* scheme_make_folding_prim

8
collects/scribblings/inside/structures.scrbl
View File

@ -3,7 +3,7 @@
@title{Structures}
A new Scheme structure type is created with
A new Racket structure type is created with
@cppi{scheme_make_struct_type}. This creates the structure type, but
does not generate the constructor, etc. procedures. The
@cppi{scheme_make_struct_values} function takes a structure type and
@ -42,6 +42,10 @@ be restricted by passing any combination of these flags:
@item{@cppi{SCHEME_STRUCT_GEN_SET} --- the field-independent
mutator procedure value/name is returned.}
@item{@cppi{SCHEME_STRUCT_NO_MAKE_PREFIX} --- the constructor name
omits a @schemeidfont{make-} prefix, like @racket[struct] instead of
@racket[define-struct].}
]
When all values or names are returned, they are returned as an array
@ -87,7 +91,7 @@ Creates and returns an array of standard structure value name
symbols. The @var{base_name} argument is used as the name of the
structure type; it should be the same symbol passed to the associated
call to @cpp{scheme_make_struct_type}. The @var{field_names} argument
is a (Scheme) list of field name symbols. The @var{flags} argument
is a (Racket) list of field name symbols. The @var{flags} argument
specifies which names should be generated, and if @var{count_out} is
not @cpp{NULL}, @var{count_out} is filled with the number of names
returned in the array.}

88
collects/scribblings/inside/threads.scrbl
View File

@ -5,10 +5,10 @@
@title[#:tag "threads"]{Threads}
The initializer function @cppi{scheme_basic_env} creates the main
Scheme thread; all other threads are created through calls to
Racket thread; all other threads are created through calls to
@cppi{scheme_thread}.
Information about each internal Scheme thread is kept in a
Information about each internal Racket thread is kept in a
@cppi{Scheme_Thread} structure. A pointer to the current thread's
structure is available as @cppi{scheme_current_thread}. A
@cpp{Scheme_Thread} structure includes the following fields:
@ -43,7 +43,7 @@ The last thread in the list is always the main thread.
@section{Integration with Threads}
Scheme's threads can break external C code under two circumstances:
Racket's threads can break external C code under two circumstances:
@itemize[
@ -53,18 +53,18 @@ Scheme's threads can break external C code under two circumstances:
pointer in the global variable, it may point to data that is not
currently on the stack.}
@item{@italic{C functions that can invoke Scheme (and also be invoked
by Scheme) depend on strict function-call nesting.} For example,
@item{@italic{C functions that can invoke Racket (and also be invoked
by Racket) depend on strict function-call nesting.} For example,
suppose a function F uses an internal stack, pushing items on to the
stack on entry and popping the same items on exit. Suppose also that
F invokes Scheme to evaluate an expression. If the evaluation of
F invokes Racket to evaluate an expression. If the evaluation of
this expression invokes F again in a new thread, but then returns to
the first thread before completing the second F, then F's internal
stack will be corrupted.}
]
If either of these circumstances occurs, Scheme will probably crash.
If either of these circumstances occurs, Racket will probably crash.
@; ----------------------------------------------------------------------
@ -72,8 +72,8 @@ If either of these circumstances occurs, Scheme will probably crash.
@section[#:tag "usefuel"]{Allowing Thread Switches}
C code that performs substantial or unbounded work should occasionally
call @cppi{SCHEME_USE_FUEL}---actually a macro---which allows Scheme
to swap in another Scheme thread to run, and to check for breaks on
call @cppi{SCHEME_USE_FUEL}---actually a macro---which allows Racket
to swap in another Racket thread to run, and to check for breaks on
the current thread. In particular, if breaks are enabled, then
@cpp{SCHEME_USE_FUEL} may trigger an exception.
@ -110,18 +110,18 @@ expression.
@section[#:tag "threadblock"]{Blocking the Current Thread}
Embedding or extension code sometimes needs to block, but blocking
should allow other Scheme threads to execute. To allow other threads
should allow other Racket threads to execute. To allow other threads
to run, block using @cppi{scheme_block_until}. This procedure takes
two functions: a polling function that tests whether the blocking
operation can be completed, and a prepare-to-sleep function that sets
bits in @cpp{fd_set}s when Scheme decides to sleep (because all Scheme
bits in @cpp{fd_set}s when Racket decides to sleep (because all Racket
threads are blocked). Under Windows, an ``@cpp{fd_set}'' can also
accommodate OS-level semaphores or other handles via
@cpp{scheme_add_fd_handle}.
Since the functions passed to @cppi{scheme_block_until} are called by
the Scheme thread scheduler, they must never raise exceptions, call
@cpp{scheme_apply}, or trigger the evaluation of Scheme code in any
the Racket thread scheduler, they must never raise exceptions, call
@cpp{scheme_apply}, or trigger the evaluation of Racket code in any
way. The @cpp{scheme_block_until} function itself may call the current
exception handler, however, in reaction to a break (if breaks are
enabled).
@ -133,8 +133,8 @@ polling and sleeping functions with @cppi{scheme_add_evt}, or register
a semaphore accessor with @cppi{scheme_add_evt_through_sema}.
The @cppi{scheme_signal_received} function can be called to wake up
Scheme when it is sleeping. In particular, calling
@cppi{scheme_signal_received} ensures that Scheme will poll all
Racket when it is sleeping. In particular, calling
@cppi{scheme_signal_received} ensures that Racket will poll all
blocking synchronizations soon afterward. Furthermore,
@cpp{scheme_signal_received} can be called from any OS-level thread.
Thus, when no adequate prepare-to-sleep function can be implemented
@ -144,17 +144,17 @@ changes will ensure that a poll is issued.
@; ----------------------------------------------------------------------
@section[#:tag "threadtime"]{Threads in Embedded Scheme with Event Loops}
@section[#:tag "threadtime"]{Threads in Embedded Racket with Event Loops}
When Scheme is embedded in an application with an event-based model
(i.e., the execution of Scheme code in the main thread is repeatedly
When Racket is embedded in an application with an event-based model
(i.e., the execution of Racket code in the main thread is repeatedly
triggered by external events until the application exits) special
hooks must be set to ensure that non-main threads execute
correctly. For example, during the execution in the main thread, a new
thread may be created; the new thread may still be running when the
main thread returns to the event loop, and it may be arbitrarily long
before the main thread continues from the event loop. Under such
circumstances, the embedding program must explicitly allow Scheme to
circumstances, the embedding program must explicitly allow Racket to
execute the non-main threads; this can be done by periodically calling
the function @cppi{scheme_check_threads}.
@ -167,11 +167,11 @@ when thread-checking becomes necessary, and then with 0 when thread
checking is no longer necessary. An embedding program can use this
information to prevent unnecessary @cpp{scheme_check_threads} polling.
The below code illustrates how MrEd formerly set up
The below code illustrates how GRacket formerly set up
@cpp{scheme_check_threads} polling using the wxWindows @cpp{wxTimer}
class. (Any regular event-loop-based callback is appropriate.) The
@cpp{scheme_notify_multithread} pointer is set to
@cpp{MrEdInstallThreadTimer}. (MrEd no longer work this way, however.)
@cpp{MrEdInstallThreadTimer}. (GRacket no longer work this way, however.)
@verbatim[#:indent 2]{
class MrEdThreadTimer : public wxTimer
@ -208,15 +208,15 @@ class. (Any regular event-loop-based callback is appropriate.) The
}
}
An alternate architecture, which MrEd now uses, is to send the main
An alternate architecture, which GRacket now uses, is to send the main
thread into a loop, which blocks until an event is ready to handle.
Scheme automatically takes care of running all threads, and it does so
Racket automatically takes care of running all threads, and it does so
efficiently because the main thread blocks on a file descriptor, as
explained in @secref["threadblock"].
@subsection[#:tag "blockednonmainel"]{Callbacks for Blocked Threads}
Scheme threads are sometimes blocked on file descriptors, such as an
Racket threads are sometimes blocked on file descriptors, such as an
input file or the X event socket. Blocked non-main threads do not
block the main thread, and therefore do not affect the event loop, so
@cppi{scheme_check_threads} is sufficient to implement this case
@ -237,7 +237,7 @@ sets up callbacks on the specified file descriptors. When input is
ready on any of those file descriptors, the callbacks are removed and
@cpp{scheme_wake_up} is called.
For example, the X Windows version of MrEd formerly set
For example, the X Windows version of GRacket formerly set
@cpp{scheme_wakeup_on_input} to this @cpp{MrEdNeedWakeup}:
@verbatim[#:indent 2]{
@ -319,15 +319,15 @@ For example, the X Windows version of MrEd formerly set
@; ----------------------------------------------------------------------
@section[#:tag "sleeping"]{Sleeping by Embedded Scheme}
@section[#:tag "sleeping"]{Sleeping by Embedded Racket}
When all Scheme threads are blocked, Scheme must ``sleep'' for a
When all Racket threads are blocked, Racket must ``sleep'' for a
certain number of seconds or until external input appears on some file
descriptor. Generally, sleeping should block the main event loop of
the entire application. However, the way in which sleeping is
performed may depend on the embedding application. The global function
pointer @cppi{scheme_sleep} can be set by an embedding application to
implement a blocking sleep, although Scheme implements this function
implement a blocking sleep, although Racket implements this function
for you.
A @cpp{scheme_sleep} function takes two arguments: a @cpp{float} and a
@ -348,7 +348,7 @@ manipulate each ``@cpp{fd_set}'' with @cpp{MZ_FD_SET},
The following function @cpp{mzsleep} is an appropriate
@cpp{scheme_sleep} function for most any Unix or Windows application.
(This is approximately the built-in sleep used by Scheme.)
(This is approximately the built-in sleep used by Racket.)
@verbatim[#:indent 2]{
void mzsleep(float v, void *fds)
@ -490,7 +490,7 @@ Blocks the current thread until @var{f} with @var{data} returns a true
a @cpp{Scheme_Object*} value, because it is only used by @var{f}
and @var{fdf}.)
If Scheme decides to sleep, then the @var{fdf} function is called to
If Racket decides to sleep, then the @var{fdf} function is called to
sets bits in @var{fds}, conceptually an array of three
@cpp{fd_set}s: one or reading, one for writing, and one for
exceptions. Use @cpp{scheme_get_fdset} to get elements of this
@ -501,7 +501,7 @@ If Scheme decides to sleep, then the @var{fdf} function is called to
The @var{fdf} argument can be @cpp{NULL}, which implies that the thread
becomes unblocked (i.e., @var{ready} changes its result to true) only
through Scheme actions, and never through external processes (e.g.,
through Racket actions, and never through external processes (e.g.,
through a socket or OS-level semaphore)---with the exception that
@cpp{scheme_signal_received} may be called to indicate an external
change.
@ -548,8 +548,8 @@ Like @cpp{scheme_block_until_enable_break}, but the function
Indicates that an external event may have caused the result of a
synchronization poll to have a different result. Unlike most other
Scheme functions, this one can be called from any OS-level thread, and
it wakes up if the Scheme thread if it is sleeping.}
Racket functions, this one can be called from any OS-level thread, and
it wakes up if the Racket thread if it is sleeping.}
@function[(void scheme_check_threads)]{
@ -577,12 +577,12 @@ Extracts an ``@cpp{fd_set}'' from an array passed to
[int repost])]{
Adds an OS-level semaphore (Windows) or other waitable handle
(Windows) to the ``@cpp{fd_set}'' @var{fds}. When Scheme performs
(Windows) to the ``@cpp{fd_set}'' @var{fds}. When Racket performs
a ``@cpp{select}'' to sleep on @var{fds}, it also waits on the given
semaphore or handle. This feature makes it possible for Scheme to
semaphore or handle. This feature makes it possible for Racket to
sleep until it is awakened by an external process.
Scheme does not attempt to deallocate the given semaphore or handle,
Racket does not attempt to deallocate the given semaphore or handle,
and the ``@cpp{select}'' call using @var{fds} may be unblocked due to
some other file descriptor or handle in @var{fds}. If @var{repost} is
a true value, then @var{h} must be an OS-level semaphore, and if the
@ -603,9 +603,9 @@ Under Unix and Mac OS X, this function has no effect.}
[int mask])]{
Adds an OS-level event type (Windows) to the set of types in the
``@cpp{fd_set}'' @var{fds}. When Scheme performs a
``@cpp{fd_set}'' @var{fds}. When Racket performs a
``@cpp{select}'' to sleep on @var{fds}, it also waits on events of
them specified type. This feature makes it possible for Scheme to
them specified type. This feature makes it possible for Racket to
sleep until it is awakened by an external process.
The event mask is only used when some handle is installed with
@ -711,28 +711,28 @@ Calls @var{prim} with the given @var{argc} and @var{argv} with breaks
[Scheme_Thread_Cell_Table* cells]
[Scheme_Object* v])]{
Prevents Scheme thread swaps until @cpp{scheme_end_atomic} or
Prevents Racket thread swaps until @cpp{scheme_end_atomic} or
@cpp{scheme_end_atomic_no_swap} is called. Start-atomic and
end-atomic pairs can be nested.}
@function[(void scheme_end_atomic)]{
Ends an atomic region with respect to Scheme threads. The current
Ends an atomic region with respect to Racket threads. The current
thread may be swapped out immediately (i.e., the call to
@cpp{scheme_end_atomic} is assumed to be a safe point for thread
swaps).}
@function[(void scheme_end_atomic_no_swap)]{
Ends an atomic region with respect to Scheme threads, and also
prevents an immediate thread swap. (In other words, no Scheme
Ends an atomic region with respect to Racket threads, and also
prevents an immediate thread swap. (In other words, no Racket
thread swaps will occur until a future safe point.)}
@function[(void scheme_add_swap_callback
[Scheme_Closure_Func f]
[Scheme_Object* data])]{
Registers a callback to be invoked just after a Scheme thread is
Registers a callback to be invoked just after a Racket thread is
swapped in. The @var{data} is provided back to @var{f} when it is
called, where @cpp{Closure_Func} is defined as follows:
@ -745,4 +745,4 @@ called, where @cpp{Closure_Func} is defined as follows:
[Scheme_Object* data])]{
Like @cpp{scheme_add_swap_callback}, but registers a callback to be
invoked just before a Scheme thread is swapped out.}
invoked just before a Racket thread is swapped out.}

2
collects/scribblings/inside/utils.rkt
View File

@ -152,7 +152,7 @@
(define cppdef (lambda (x) (as-cpp-defn x (cpp x))))
(define *var italic)
(define mzc (exec "mzc"))
(define mzc (exec "raco ctool"))
(define (refsecref s)
(secref #:doc '(lib "scribblings/reference/reference.scrbl") s))

72
collects/scribblings/inside/values.scrbl
View File

@ -3,27 +3,27 @@
@title[#:tag "im:values+types"]{Values and Types}
A Scheme value is represented by a pointer-sized value. The low bit is
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
indicates a (word-aligned) pointer.
A pointer Scheme value references a structure that begins with a
A pointer Racket value references a structure that begins with a
@cppi{Scheme_Object} sub-structure, which in turn starts with a tag
that has the C type @cppi{Scheme_Type}. The rest of the structure,
following the @cppi{Scheme_Object} header, is type-dependent.
PLT Scheme's C interface gives Scheme values the type
Racket's C interface gives Racket values the type
@cpp{Scheme_Object*}. (The ``object'' here does not refer to objects
in the sense of the @schememodname[scheme/class] library.)
in the sense of the @schememodname[racket/class] library.)
Examples of @cpp{Scheme_Type} values include @cpp{scheme_pair_type}
and @cpp{scheme_symbol_type}. Some of these are implemented as
instances of @cppi{Scheme_Simple_Object}, which is defined in
@filepath{scheme.h}, but extension or embedding code should never access
this structure directly. Instead, the code should use macros, such as
@cpp{SCHEME_CAR}, that provide access to the data of common Scheme
@cpp{SCHEME_CAR}, that provide access to the data of common Racket
types.
For most Scheme types, a constructor is provided for creating values
For most Racket types, a constructor is provided for creating values
of the type. For example, @cpp{scheme_make_pair} takes two
@cpp{Scheme_Object*} values and returns the @scheme[cons] of the
values.
@ -32,12 +32,12 @@ The macro @cppdef{SCHEME_TYPE} takes a @cpp{Scheme_Object *} and returns
the type of the object. This macro performs the tag-bit check, and
returns @cppi{scheme_integer_type} when the value is an immediate
integer; otherwise, @cpp{SCHEME_TYPE} follows the pointer to get the
type tag. Macros are provided to test for common Scheme types; for
type tag. Macros are provided to test for common Racket types; for
example, @cpp{SCHEME_PAIRP} returns @cpp{1} if the value is a cons
cell, @cpp{0} otherwise.
In addition to providing constructors, PLT Scheme defines six global
constant Scheme values: @cppi{scheme_true}, @cppi{scheme_false},
In addition to providing constructors, Racket defines six global
constant Racket values: @cppi{scheme_true}, @cppi{scheme_false},
@cppi{scheme_null}, @cppi{scheme_eof}, @cppi{scheme_void}, and
@cppi{scheme_undefined}. Each of these has a type tag, but each is
normally recognized via its constant address.
@ -46,7 +46,7 @@ normally recognized via its constant address.
can create new a primitive data type by calling
@cppi{scheme_make_type}, which returns a fresh @cpp{Scheme_Type}
value. To create a collectable instance of this type, allocate memory
for the instance with @cpp{scheme_malloc}. From PLT Scheme's
for the instance with @cpp{scheme_malloc}. From Racket's
perspective, the main constraint on the data format of such an
instance is that the first @cpp{sizeof(Scheme_Object)} bytes must
correspond to a @cpp{Scheme_Object} record; furthermore, the first
@ -54,7 +54,7 @@ correspond to a @cpp{Scheme_Object} record; furthermore, the first
@cpp{scheme_make_type}. Extensions with modest needs can use
@cppi{scheme_make_cptr}, instead of creating an entirely new type.
Scheme values should never be allocated on the stack, and they should
Racket values should never be allocated on the stack, and they should
never contain pointers to values on the stack. Besides the problem of
restricting the value's lifetime to that of the stack frame,
allocating values on the stack creates problems for continuations and
@ -89,7 +89,7 @@ types:
floating-point value; test for this type with @cppdef{SCHEME_DBLP}}
@item{@cppdef{scheme_float_type} --- single-precision flonum
inexact numbers, when specifically enabled when compiling PLT Scheme;
inexact numbers, when specifically enabled when compiling Racket;
@cppi{SCHEME_FLOAT_VAL} or @cppdef{SCHEME_FLT_VAL} extracts the
floating-point value; test for this type with @cppdef{SCHEME_FLTP}}
@ -109,7 +109,7 @@ types:
@item{@cppdef{scheme_char_string_type} --- @index['("strings"
"conversion to C")]{@cppdef{SCHEME_CHAR_STR_VAL}} extracts the string
as a @cpp{mzchar*}; the string is always nul-terminated, but may also
contain embedded nul characters, and the Scheme string is modified if
contain embedded nul characters, and the Racket string is modified if
this string is modified; @cppdef{SCHEME_CHAR_STRLEN_VAL} extracts the
string length (in characters, not counting the nul terminator); test
for this type with @cppdef{SCHEME_CHAR_STRINGP}}
@ -117,7 +117,7 @@ types:
@item{@cppdef{scheme_byte_string_type} ---
@cppdef{SCHEME_BYTE_STR_VAL} extracts the string as a @cpp{char*}; the
string is always nul-terminated, but may also contain embedded nul
characters, and the Scheme string is modified if this string is
characters, and the Racket string is modified if this string is
modified; @cppdef{SCHEME_BYTE_STRLEN_VAL} extracts the string length
(in bytes, not counting the nul terminator); test for this type with
@cppdef{SCHEME_BYTE_STRINGP}}
@ -158,7 +158,7 @@ types:
@item{@cppdef{scheme_vector_type} --- @cppdef{SCHEME_VEC_SIZE}
extracts the length and @cppdef{SCHEME_VEC_ELS} extracts the array of
Scheme values (the Scheme vector is modified when this array is
Racket values (the Racket vector is modified when this array is
modified); test for this type with @cppdef{SCHEME_VECTORP}; 3m: see
@secref["im:3m"] for a caution about @cppi{SCHEME_VEC_ELS}}
@ -222,7 +222,7 @@ The following are the procedure types:
@item{@cppdef{scheme_closed_prim_type} --- an old-style primitive
procedure with a data pointer}
@item{@cppdef{scheme_compiled_closure_type} --- a Scheme
@item{@cppdef{scheme_compiled_closure_type} --- a Racket
procedure}
@item{@cppdef{scheme_cont_type} --- a continuation}
@ -289,9 +289,9 @@ There are six global constants:
@section[#:tag "im:strings"]{Strings}
As noted in @secref["im:unicode"], a Scheme character is a Unicode
As noted in @secref["im:unicode"], a Racket character is a Unicode
code point represented by a @cpp{mzchar} value, and character strings
are @cpp{mzchar} arrays. PLT Scheme also supplies byte strings, which
are @cpp{mzchar} arrays. Racket also supplies byte strings, which
are @cpp{char} arrays.
For a character string @var{s}, @cpp{@cpp{SCHEME_CHAR_STR_VAL}(@var{s})}
@ -319,7 +319,7 @@ For more fine-grained control over UTF-8 encoding, use the
Returns the character value. The @var{ch} value must be a legal
Unicode code point (and not a surrogate, for example). The first 256
characters are represented by constant Scheme values, and others are
characters are represented by constant Racket values, and others are
allocated.}
@function[(Scheme_Object* scheme_make_char_or_null
@ -389,7 +389,7 @@ Creates an integer given the high and low @cpp{long}s of an unsigned
Extracts the integer value. Unlike the @cppi{SCHEME_INT_VAL} macro,
this procedure will extract an integer that fits in a @cpp{long} from
a Scheme bignum. If @var{o} fits in a @cpp{long}, the extracted
a Racket bignum. If @var{o} fits in a @cpp{long}, the extracted
integer is placed in @var{*i} and 1 is returned; otherwise, 0 is
returned and @var{*i} is unmodified.}
@ -422,13 +422,13 @@ Creates a new floating-point value.}
[float d])]{
Creates a new single-precision floating-point value. The procedure is
available only when PLT Scheme is compiled with single-precision
available only when Racket is compiled with single-precision
numbers enabled.}
@function[(double scheme_real_to_double
[Scheme_Object* o])]{
Converts a Scheme real number to a double-precision floating-point
Converts a Racket real number to a double-precision floating-point
value.}
@function[(Scheme_Object* scheme_make_pair
@ -440,7 +440,7 @@ Makes a @scheme[cons] pair.}
@function[(Scheme_Object* scheme_make_byte_string
[char* bytes])]{
Makes a Scheme byte string from a nul-terminated C string. The
Makes a Racket byte string from a nul-terminated C string. The
@var{bytes} string is copied.}
@function[(Scheme_Object* scheme_make_byte_string_without_copying
@ -475,7 +475,7 @@ Like @cpp{scheme_make_sized_byte_string}, except the @var{len}
[long size]
[char fill])]{
Allocates a new Scheme byte string.}
Allocates a new Racket byte string.}
@function[(Scheme_Object* scheme_append_byte_string
[Scheme_Object* a]
@ -486,7 +486,7 @@ Creates a new byte string by appending the two given byte strings.}
@function[(Scheme_Object* scheme_make_locale_string
[char* bytes])]{
Makes a Scheme string from a nul-terminated byte string that is a
Makes a Racket string from a nul-terminated byte string that is a
locale-specific encoding of a character string; a new string is
allocated during decoding. The ``locale in the name of this function
thus refers to @var{bytes}, and not the resulting string (which is
@ -495,7 +495,7 @@ Makes a Scheme string from a nul-terminated byte string that is a
@function[(Scheme_Object* scheme_make_utf8_string
[char* bytes])]{
Makes a Scheme string from a nul-terminated byte string that is a
Makes a Racket string from a nul-terminated byte string that is a
UTF-8 encoding. A new string is allocated during decoding. The
``utf8'' in the name of this function thus refers to @var{bytes}, and
not the resulting string (which is internally stored as UCS-4).}
@ -523,7 +523,7 @@ Like @cpp{scheme_make_sized_char_string}, except the @var{len} characters
@function[(Scheme_Object* scheme_make_char_string
[mzchar* chars])]{
Makes a Scheme string from a nul-terminated UCS-4 string. The
Makes a Racket string from a nul-terminated UCS-4 string. The
@var{chars} string is copied.}
@function[(Scheme_Object* scheme_make_char_string_without_copying
@ -558,7 +558,7 @@ Like @cpp{scheme_make_sized_char_string}, except the @var{len}
[long size]
[mzchar fill])]{
Allocates a new Scheme string.}
Allocates a new Racket string.}
@function[(Scheme_Object* scheme_append_char_string
[Scheme_Object* a]
@ -569,22 +569,22 @@ Creates a new string by appending the two given strings.}
@function[(Scheme_Object* scheme_char_string_to_byte_string
[Scheme_Object* s])]{
Converts a Scheme character string into a Scheme byte string via UTF-8.}
Converts a Racket character string into a Racket byte string via UTF-8.}
@function[(Scheme_Object* scheme_byte_string_to_char_string
[Scheme_Object* s])]{
Converts a Scheme byte string into a Scheme character string via UTF-8.}
Converts a Racket byte string into a Racket character string via UTF-8.}
@function[(Scheme_Object* scheme_char_string_to_byte_string_locale
[Scheme_Object* s])]{
Converts a Scheme character string into a Scheme byte string via the locale's encoding.}
Converts a Racket character string into a Racket byte string via the locale's encoding.}
@function[(Scheme_Object* scheme_byte_string_to_char_string_locale
[Scheme_Object* s])]{
Converts a Scheme byte string into a Scheme character string via the locale's encoding.}
Converts a Racket byte string into a Racket character string via the locale's encoding.}
@function[(Scheme_Object* scheme_intern_symbol
[char* name])]{
@ -654,7 +654,7 @@ Creates a new weak box containing the value @var{v}.}
@function[(Scheme_Type scheme_make_type
[char* name])]{
Creates a new type (not a Scheme value).}
Creates a new type (not a Racket value).}
@function[(Scheme_Object* scheme_make_cptr
[void* ptr]
@ -664,10 +664,10 @@ Creates a C-pointer object that encapsulates @var{ptr} and uses
@var{typetag} to identify the type of the pointer. The
@cppi{SCHEME_CPTRP} macro recognizes objects created by
@cpp{scheme_make_cptr}. The @cppi{SCHEME_CPTR_VAL} macro extracts
the original @var{ptr} from the Scheme object, and
the original @var{ptr} from the Racket object, and
@cppi{SCHEME_CPTR_TYPE} extracts the type tag.
The @cppi{SCHEME_CPTR_OFFSETVAL} macro returns @cpp{0}
for the result Scheme object.
for the result Racket object.
The @var{ptr} can refer to either memory managed by the garbage
collector or by some other memory manager. Beware, however, of
@ -690,7 +690,7 @@ referencing memory managed by the garbage collector.}
Creates a C-pointer object that encapsulates both @var{ptr} and @var{offset}.
The @cppi{SCHEME_CPTR_OFFSETVAL} macro returns @var{offset}
for the result Scheme object (and the macro be used to change the offset,
for the result Racket object (and the macro be used to change the offset,
since it also works on objects with no offset).
The @var{ptr} can refer to either memory managed by the garbage