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} @title{Custodians}
When an extension allocates resources that must be explicitly freed 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 object associated with the resource should be placed into the
management of the current custodian with @cppi{scheme_add_managed}. 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])]{ [Scheme_Exit_Closer_Func f])]{
Installs a function to be called on each custodian-registered item and 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 has the type
@verbatim[#:indent 2]{ @verbatim[#:indent 2]{

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

@ -3,7 +3,7 @@
@title{Evaluation} @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 This function takes an S-expression (as a @cpp{Scheme_Object*}) and a
namespace and returns the value of the expression in that namespace. 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 array of @cpp{Scheme_Object *} arguments. The return value is the
result of the application. There is also a function result of the application. There is also a function
@cppi{scheme_apply_to_list}, which takes a procedure and a list @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. @scheme[apply] operation.
The @cppi{scheme_eval} function actually calls @cppi{scheme_compile} The @cppi{scheme_eval} function actually calls @cppi{scheme_compile}
@ -43,15 +43,15 @@ see @secref["exceptions"].
@section-index{tail recursion} @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 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 handled properly. Specifically, when the final return value of a
function is the result of an application, then function is the result of an application, then
@cppi{scheme_tail_apply} should be used instead of @cppi{scheme_tail_apply} should be used instead of
@cppi{scheme_apply}. When @cppi{scheme_tail_apply} is called, it @cppi{scheme_apply}. When @cppi{scheme_tail_apply} is called, it
postpones the procedure application until control returns to the postpones the procedure application until control returns to the
Scheme evaluation loop. Racket evaluation loop.
For example, consider the following implementation of a For example, consider the following implementation of a
@scheme[thunk-or] primitive, which takes any number of thunks and @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)]{ @function[(Scheme_Env* scheme_basic_env)]{
Creates the main namespace for an embedded PLT Scheme. This procedure Creates the main namespace for an embedded Racket. This procedure
must be called before other Scheme library function (except must be called before other Racket library function (except
@cpp{scheme_make_param}). Extensions to Scheme cannot call this @cpp{scheme_make_param}). Extensions to Racket cannot call this
function. function.
If it is called more than once, this function resets all threads 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 a parameterization using @cppi{scheme_set_param} with
@cppi{MZCONFIG_ENV}. @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 namespace with @cppi{scheme_basic_env} before calling this procedure
to create new namespaces.} to create new namespaces.}

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

@ -3,7 +3,7 @@
@title[#:tag "exceptions"]{Exceptions and Escape Continuations} @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 exception handler invokes the error display handler and then the error
escape handler. The default error escape handler escapes via a escape handler. The default error escape handler escapes via a
@defterm{primitive error escape}, which is implemented by calling @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 An embedding program should install a fresh buffer into
@cpp{scheme_current_thread->error_buf} and call @cpp{scheme_current_thread->error_buf} and call
@cpp{scheme_setjmp(*scheme_current_thread->error_buf)} before any @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 escapes. When the new buffer goes out of scope, restore the original
in @cpp{scheme_current_thread->error_buf}. The macro in @cpp{scheme_current_thread->error_buf}. The macro
@cppi{scheme_error_buf} is a shorthand for @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 function @cpp{printf}. A specific primitive exception can be raised by
calling @cppi{scheme_raise_exn}. 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}. 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}, top-level evaluation functions (@cpp{scheme_eval}, @cpp{scheme_apply},
etc., as opposed to @cpp{_scheme_apply}, @cpp{_scheme_eval_compiled}, 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 evaluations (such as returning twice from a function) because
continuation invocations are confined to jumps within a single continuation invocations are confined to jumps within a single
top-level evaluation. However, escape continuation jumps are still 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 @cpp{_scheme_eval_compiled}, etc.). Otherwise, use
@cppi{scheme_dynamic_wind} to protect your code against full @cppi{scheme_dynamic_wind} to protect your code against full
continuation jumps in the same way that @scheme[dynamic-wind] is used 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 The above solution simply traps the escape; it doesn't report the
reason that the escape occurred. To catch exceptions and obtain 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 code with C-implemented thunks. The code below can be used to catch
exceptions in a variety of situations. It implements the function exceptions in a variety of situations. It implements the function
@cpp{_apply_catch_exceptions}, which catches exceptions during the @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 there's no exception, otherwise returning NULL and setting *exn
to the raised value (usually an exn structure). */ to the raised value (usually an exn structure). */
Scheme_Object *_apply_thunk_catch_exceptions(Scheme_Object *f, 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. that occur during while evaluating source code from a string.
@verbatim[#:indent 2]{ @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) 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} @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 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 breaks. To enable or disable breaks during the dynamic extent of
another evaluation (where you would use 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_push_break_enable} before and
@cppi{scheme_pop_break_enable} after, instead. @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{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 @item{@FormatD{t} : a @cpp{char} string with a @cpp{long} size (two
arguments), possibly containing a non-terminating nul byte, and 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 arguments), possibly containing a non-terminating nul character, and
possibly without a nul-terminator} 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 @item{@FormatD{q} : a string, truncated to 253 characters, with ellipses
printed if the string is truncated} 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 to 253 characters, with ellipses printed if the string is
truncated} 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.} truncated according to the current error print width.}
@item{@FormatD{e} : an @cpp{errno} value, to be printed as a text @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 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 numbers. (This restriction simplifies the implementation with precise
garbage collection.)} 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} proceed roughly as for @cpp{printf}; see @cpp{scheme_signal_error}
above for more details. 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', but prefixed with ``MZ'', all letters are capitalized, and all ``:'s',
``-''s, and ``/''s are replaced with underscores. For example, ``-''s, and ``/''s are replaced with underscores. For example,
@cpp{MZEXN_FAIL_FILESYSTEM} is the exception id for a filesystem @cpp{MZEXN_FAIL_FILESYSTEM} is the exception id for a filesystem
@ -370,8 +372,8 @@ variable.}
[int count] [int count]
[int* len])]{ [int* len])]{
Converts a Scheme value into a string for the purposes of reporting an Converts a Racket value into a string for the purposes of reporting an
error message. The @var{count} argument specifies how many Scheme error message. The @var{count} argument specifies how many Racket
values total will appear in the error message (so the string for this 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 value can be scaled appropriately). If @var{len} is not @cpp{NULL}, it
is filled with the length of the returned string.} 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] [Scheme_Object** argv]
[long* len])]{ [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 array element indicated by @var{which}. This function is used to
specify the ``other'' arguments to a function when one argument is bad specify the ``other'' arguments to a function when one argument is bad
(thus giving the user more information about the state of the program (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} @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: embedded:
@itemize[ @itemize[
@ -14,7 +14,7 @@ embedded:
@item{@cppdef{scheme_make_stdin}, @cppdef{scheme_make_stdout}, @item{@cppdef{scheme_make_stdin}, @cppdef{scheme_make_stdout},
@cppdef{scheme_make_stderr}, --- These pointers can be set to a @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, @cpp{Scheme_Object *} to be used as the starting standard input,
output, and/or error port. The defaults are @cpp{NULL}. Setting the output, and/or error port. The defaults are @cpp{NULL}. Setting the
initial error port is particularly important for seeing unexpected 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 @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 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 messages that possibly contain non-terminating nuls. The default is
@var{NULL}.} @var{NULL}.}
@ -36,7 +36,7 @@ embedded:
@item{@cppdef{scheme_case_sensitive} --- If this flag is set to a @item{@cppdef{scheme_case_sensitive} --- If this flag is set to a
non-zero value before @cppi{scheme_basic_env} is called, then 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 variable names. The value of this flag should not change once it is
set. The default is zero.} set. The default is zero.}

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

@ -2,19 +2,19 @@
@(require "utils.ss") @(require "utils.ss")
@title[#:tag-prefix '(lib "scribblings/inside/inside.scrbl") @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"] @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 interpreter to be extended by a dynamically-loaded library, or
embedded within an arbitrary C/C++ program. The manual assumes 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 For an alternative way of dealing with foreign code, see
@other-manual['(lib "scribblings/foreign/foreign.scrbl")], which @other-manual['(lib "scribblings/foreign/foreign.scrbl")], which
describes the @schememodname[scheme/foreign] module for manipulating describes the @racketmodname[ffi/unsafe] module for manipulating
low-level libraries and structures purely through Scheme code. low-level libraries and structures purely through Racket code.
@table-of-contents[] @table-of-contents[]

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

@ -6,14 +6,14 @@
@section-index{memory} @section-index{memory}
@section-index{garbage collection} @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 by a garbage collector. Embedding/extension C/C++ code may use either
allocation method, keeping in mind that pointers to allocation method, keeping in mind that pointers to
garbage-collectable blocks in @cpp{malloc}ed memory are invisible garbage-collectable blocks in @cpp{malloc}ed memory are invisible
(i.e., such pointers will not prevent the block from being (i.e., such pointers will not prevent the block from being
garbage-collected). 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 collector normally only recognizes pointers to the beginning of
allocated objects. Thus, a pointer into the middle of a GC-allocated allocated objects. Thus, a pointer into the middle of a GC-allocated
string will normally not keep the string from being collected. The 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 is safe to loop over an array by incrementing a local pointer
variable. 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 during collection, in which case the C code must be instrumented to
expose local pointer bindings to the collector, and to provide tracing expose local pointer bindings to the collector, and to provide tracing
procedures for (tagged) records containing pointers. This 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 @index['("globals" "in extension code")]{If} a Racket extension
stores Scheme pointers in a global or static variable, then that stores Racket pointers in a global or static variable, then that
variable must be registered with variable must be registered with
@cppi{scheme_register_extension_global}; this makes the pointer @cppi{scheme_register_extension_global}; this makes the pointer
visible to the garbage collector. Registered variables need not 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, the reference-counting function @cppi{scheme_dont_gc_ptr}. Under 3m,
such locking does not prevent the object from being moved. such locking does not prevent the object from being moved.
Garbage collection can occur during any call into Scheme or its Garbage collection can occur during any call into Racket or its
allocator, on anytime that Scheme has control, except during functions allocator, on anytime that Racket has control, except during functions
that are documented otherwise. The predicate and accessor macros that are documented otherwise. The predicate and accessor macros
listed in @secref["im:stdtypes"] never trigger a collection. 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 into an object allocated by @cpp{scheme_malloc_allow_interior}, a
pointer to an object currently allocated by another memory manager pointer to an object currently allocated by another memory manager
(and therefore not into a block that is currently managed by the (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). fixnum).
Pointers are registered in three different ways: 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} 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. 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 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 After allocating a new tag in 3m (and before creating instances of the
tag), a @defterm{size procedure}, a @defterm{mark procedure}, and a 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. for both conservative and precise collection.
The @cpp{MZ_GC_REG} and @cpp{MZ_GC_UNREG} macros must never be 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] [void* ptr]
[long size])]{ [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 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 size in bytes in @var{size}.In addition to global variables, this
function can be used to register any permanent memory that the 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 Like @cpp{scheme_set_stack_base}, except for the extra
@var{stack_end} argument. If @var{stack_end} is non-@cpp{NULL}, then @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 attempt to handle stack overflow. The @var{stack_end} argument
should not correspond to the actual stack end, since detecting stack should not correspond to the actual stack end, since detecting stack
overflow may take a few frames, and since handling stack overflow 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]. Installs a ``will''-like finalizer, similar to @scheme[will-register].
Scheme finalizers are called one at a time, requiring the collector Scheme finalizers are called one at a time, requiring the collector
to prove that a value has become inaccessible again before calling 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 @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 See @cpp{scheme_register_finalizer}, above, for information about
the arguments. the arguments.

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

@ -4,7 +4,7 @@
@title{Miscellaneous Utilities} @title{Miscellaneous Utilities}
The @cppi{MZSCHEME_VERSION} preprocessor macro is defined as a string 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 and @cppi{MZSCHEME_VERSION_MINOR} macros are defined as the major and
minor version numbers, respectively. 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 tracking. This procedure is meant to be called by a procedure
installed with @cpp{scheme_set_type_equality}.} 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 @function[(long scheme_equal_hash_key
[Scheme_Object* obj])]{ [Scheme_Object* obj])]{
@ -150,13 +150,13 @@ The same as @scheme[namespace-require].}
@function[(Scheme_Object* scheme_load @function[(Scheme_Object* scheme_load
[char* file])]{ [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.} expression loaded, or @cpp{NULL} if the load fails.}
@function[(Scheme_Object* scheme_load_extension @function[(Scheme_Object* scheme_load_extension
[char* filename])]{ [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.} by the extension's initialization function.}
@function[(Scheme_Hash_Table* scheme_make_hash_table @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 @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 null-terminated string content. Since a hash table created with
@cpp{SCHEME_hash_string} (instead of @cpp{SCHEME_hash_ptr}) does not @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*} Although the hash table interface uses the type @cpp{Scheme_Object*}
for both keys and values, the table functions never inspect values, 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)]{ @function[(Scheme_Hash_Table* scheme_make_hash_table_equal)]{
Like @cpp{scheme_make_hash_table}, except that keys are treated as 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?].} @scheme[eq?].}
@function[(void scheme_hash_set @function[(void scheme_hash_set
@ -334,8 +334,8 @@ Returns the current process ``time'' in milliseconds, just like
@function[(char* scheme_banner)]{ @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)]{ @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} @title[#:tag "im:env"]{Namespaces and Modules}
A Scheme namespace (a top-level environment) is represented by a value A Racket namespace (a top-level environment) is represented by a value
of type @cppi{Scheme_Env*} --- which is also a Scheme value, castable of type @cppi{Scheme_Env*} --- which is also a Racket value, castable
to @cpp{Scheme_Object*}. Calling @cppi{scheme_basic_env} returns a 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. and syntax.
The @cpp{scheme_basic_env} function must be called once by an 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} (except @cpp{scheme_make_param}), but @cpp{scheme_main_setup}
automatically calls @cpp{scheme_basic_env}. The returned namespace is 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}. extensions cannot call @cpp{scheme_basic_env}.
The current thread's current namespace is available from 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 New values can be added as @as-index{globals} in a namespace using
@cppi{scheme_add_global}. The @cppi{scheme_lookup_global} function @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. @cpp{NULL} if the symbol is undefined.
A @as-index{module}'s set of top-level bindings is implemented using 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 to make the module declaration available. All defined variables are
exported from the primitive module. exported from the primitive module.
The Scheme @indexed-scheme[#%variable-reference] form produces a value The Racket @indexed-scheme[#%variable-reference] form produces a value
that is opaque to Scheme code. Use @cpp{SCHEME_PTR_VAL} on the result 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 of @scheme[#%variable-reference] to obtain the same kind of value as
returned by @cpp{scheme_global_bucket} (i.e., a bucket containing the 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). 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 Like @cpp{scheme_global_bucket}, but finds a variable in a
module. The @var{mod} and @var{symbol} arguments are as for 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 @cpp{-1} always. The @var{env} argument represents the namespace in
which the module is declared.} which the module is declared.}

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

@ -3,9 +3,9 @@
@title{Bignums, Rationals, and Complex Numbers} @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 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 @cppi{scheme_bignum_type}. There is no overlap in integer values
represented by fixnums and bignums. represented by fixnums and bignums.
@ -60,7 +60,7 @@ unspecified accuracy.}
@function[(float scheme_bignum_to_float @function[(float scheme_bignum_to_float
[Scheme_Object* n])]{ [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}.} is actually a macro alias for @cpp{scheme_bignum_to_double}.}
@function[(Scheme_Object* scheme_bignum_from_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 @function[(Scheme_Object* scheme_bignum_from_float
[float f])]{ [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}.} is actually a macro alias for @cpp{scheme_bignum_from_double}.}
@function[(char* scheme_bignum_to_string @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 @function[(float scheme_rational_to_float
[Scheme_Object* n])]{ [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}.} is actually a macro alias for @cpp{scheme_rational_to_double}.}
@function[(Scheme_Object* scheme_rational_numerator @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 @function[(Scheme_Object* scheme_rational_from_float
[float d])]{ [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}.} is actually a macro alias for @cpp{scheme_rational_from_double}.}
@function[(Scheme_Object* scheme_make_complex @function[(Scheme_Object* scheme_make_complex

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

@ -3,21 +3,31 @@
@title[#:tag "overview"]{Overview} @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} @section{CGC versus 3m}
Before mixing any C code with MzScheme, first decide whether to use Before mixing any C code with Racket, first decide whether to use the
the @bold{3m} variant of PLT Scheme, the @bold{CGC} variant of PLT @bold{3m} variant of Racket, the @bold{CGC} variant of Racket, or
Scheme, or both: both:
@itemize[ @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 uses @defterm{precise} garbage collection instead of conservative
garbage collection, and it may move objects in memory during a garbage collection, and it may move objects in memory during a
collection.} collection.}
@item{@bold{@as-index{CGC}} : the original variant of PLT Scheme, @item{@bold{@as-index{CGC}} : the original variant of Racket, where
where memory management depends on a @defterm{conservative} garbage memory management depends on a @defterm{conservative} garbage
collector. The conservative garbage collector can automatically find collector. The conservative garbage collector can automatically find
references to managed values from C local variables and (on some references to managed values from C local variables and (on some
platforms) static variables.} 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 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 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} @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: steps:
@itemize[ @itemize[
@item{@index['("header files")]{For} each C/C++ file that uses PLT @item{@index['("header files")]{For} each C/C++ file that uses
Scheme library functions, @cpp{#include} the file Racket library functions, @cpp{#include} the file
@as-index{@filepath{escheme.h}}. @as-index{@filepath{escheme.h}}.
This file is distributed with the PLT software in an This file is distributed with the Racket software in an
@filepath{include} directory, but if @|mzc| is used to compile, this @filepath{include} directory, but if @|mzc| is used to
path is found automatically.} compile, this path is found automatically.}
@item{Define the C function @cppi{scheme_initialize}, which takes a @item{Define the C function @cppi{scheme_initialize}, which takes a
@cpp{Scheme_Env*} namespace (see @secref["im:env"]) and returns 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 This initialization function can install new global primitive
procedures or other values into the namespace, or it can simply procedures or other values into the namespace, or it can simply
return a Scheme value. The initialization function is called when the return a Racket value. The initialization function is called when the
extension is loaded with @scheme[load-extension] (the first time); extension is loaded with @racket[load-extension] (the first time);
the return value from @cpp{scheme_initialize} is used as the return 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 @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 @item{Define the C function @cppi{scheme_reload}, which has the same
arguments and return type as @cpp{scheme_initialize}. 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}, time (or more times) for an extension. Like @cpp{scheme_initialize},
the return value from this function is the return value for 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 @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 The function should return a symbol when the effect of calling
@cpp{scheme_initialize} and @cpp{scheme_reload} is only to declare @cpp{scheme_initialize} and @cpp{scheme_reload} is only to declare
a module with the returned name. This function is called when the 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 The @cpp{scheme_module_name} function may be called before
@cpp{scheme_initialize} and @cpp{scheme_reload}, after those @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 @item{Compile the extension C/C++ files to create platform-specific
object files. 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 compiles plain C files when the @as-index{@DFlag{cc}} flag is
specified. More precisely, @|mzc| does not compile the files itself, specified. More precisely, @|mzc| does not compile the files itself,
but it locates a C compiler on the system and launches it with the 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 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 developer tools installed, then using @|mzc| is typically easier than
working with the C compiler directly. Use the @as-index{@DFlag{cgc}} 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 @item{Link the extension C/C++ files with
@ -115,50 +125,50 @@ steps:
The @filepath{mzdyn} object file is distributed in the installation's The @filepath{mzdyn} object file is distributed in the installation's
@filepath{lib} directory. For Windows, the object file is in a @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 The @|mzc| compiler links object files into an extension when the
@as-index{@DFlag{ld}} flag is specified, automatically locating @as-index{@DFlag{ld}} flag is specified, automatically locating
@filepath{mzdyn}. Again, use the @DFlag{cgc} flag with @|mzc|.} @filepath{mzdyn}. Again, use the @DFlag{cgc} flag with @|mzc|.}
@item{Load the shared object within Scheme using @item{Load the shared object within Racket using
@scheme[(load-extension _path)], where @scheme[_path] is the name of @racket[(load-extension _path)], where @racket[_path] is the name of
the extension file generated in the previous step. the extension file generated in the previous step.
Alternately, if the extension defines a module (i.e., Alternately, if the extension defines a module (i.e.,
@cpp{scheme_module_name} returns a symbol), then place the shared @cpp{scheme_module_name} returns a symbol), then place the shared
object in a special directory with a special name, so that it is 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 special directory is a platform-specific path that can be obtained by
evaluating @scheme[(build-path "compiled" "native" evaluating @racket[(build-path "compiled" "native"
(system-library-subpath))]; see @scheme[load/use-compiled] for more (system-library-subpath))]; see @racket[load/use-compiled] for more
information. For example, if the shared object's name is information. For example, if the shared object's name is
@filepath{example_ss.dll}, then @scheme[(require "example.ss")] will @filepath{example_rkt.dll}, then @racket[(require "example.rkt")] will
be redirected to @filepath{example_ss.dll} if the latter is placed in be redirected to @filepath{example_rkt.dll} if the latter is placed in
the sub-directory @scheme[(build-path "compiled" "native" the sub-directory @racket[(build-path "compiled" "native"
(system-library-subpath))] and if @filepath{example.ss} does not (system-library-subpath))] and if @filepath{example.rkt} does not
exist or has an earlier timestamp. 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 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 introduce an extension's bindings into a module, make sure that the
extension defines a module, put the extension in the extension defines a module, put the extension in the
platform-specific location as described above, and use 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, 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, variables, or structures allocated with @cppi{scheme_malloc}. However,
static variables that contain pointers to collectable memory must be static variables that contain pointers to collectable memory must be
registered using @cppi{scheme_register_extension_global} (see registered using @cppi{scheme_register_extension_global} (see
@secref["im:memoryalloc"]). @secref["im:memoryalloc"]).
As an example, the following C code defines an extension that returns 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]{ @verbatim[#:indent 2]{
#include "escheme.h" #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 Assuming that this code is in the file @filepath{hw.c}, the extension
is compiled under Unix with the following two commands: is compiled under Unix with the following two commands:
@commandline{mzc --cgc --cc hw.c} @commandline{raco ctool --cgc --cc hw.c}
@commandline{mzc --cgc --ld hw.so hw.o} @commandline{raco ctool --cgc --ld hw.so hw.o}
(Note that the @DFlag{cgc}, @DFlag{cc}, and @DFlag{ld} flags are each (Note that the @DFlag{cgc}, @DFlag{cc}, and @DFlag{ld} flags are each
prefixed by two dashes, not one.) 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. distribution contains additional examples.
@subsection{3m Extensions} @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: must be extended as follows:
@itemize[ @itemize[
@ -213,12 +223,12 @@ must be extended as follows:
For a relatively simple extension @filepath{hw.c}, the extension is For a relatively simple extension @filepath{hw.c}, the extension is
compiled under Unix for 3m with the following three commands: compiled under Unix for 3m with the following three commands:
@commandline{mzc --xform hw.c} @commandline{raco ctool --xform hw.c}
@commandline{mzc --3m --cc hw.3m.c} @commandline{raco ctool --3m --cc hw.3m.c}
@commandline{mzc --3m --ld hw.so hw.o} @commandline{raco ctool --3m --ld hw.so hw.o}
Some examples in @filepath{collects/mzscheme/examples} work with 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. which case the @DFlag{xform} step should be skipped.
@subsection{Declaring a Module in an Extension} @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}. @cpp{scheme_rename} declare a module using @cpp{scheme_primitive_module}.
For example, the following extension implements a module named 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]{ @verbatim[#:indent 2]{
#include "escheme.h" #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: example, using the following sequence of @exec{mzc} commands:
@commandline{mzc --xform hi.c} @commandline{raco ctool --xform hi.c}
@commandline{mzc --3m --cc hi.3m.c} @commandline{raco ctool --3m --cc hi.3m.c}
@commandline{mkdir -p compiled/native/i386-macosx/3m} @commandline{mkdir -p compiled/native/i386-linux/3m}
@commandline{mzc --3m --ld compiled/native/i386-macosx/3m/hi_ss.dylib hi_3m.o} @commandline{raco ctool --3m --ld compiled/native/i386-linux/3m/hi_rkt.so hi_3m.o}
The resulting module can be loaded with 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 Like creating extensions, the embedding process for Racket CGC or
PLT Scheme 3m is essentially the same, but the process for PLT Scheme Racket 3m is essentially the same, but the process for Racket
3m is most easily understood as a variant of the process for 3m is most easily understood as a variant of the process for
PLT Scheme CGC. Racket CGC.
@subsection{CGC Embedding} @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[ @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 standard distribution provides 3m libraries, only, you will most
likely have to build from source. 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 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{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 @as-index{@filepath{libmzgc.la}} files for use with
@exec{libtool}). Building from source and installing places the @exec{libtool}). Building from source and installing places the
libraries into the installation's @filepath{lib} directory. Be sure libraries into the installation's @filepath{lib} directory. Be sure
to build the CGC variant, since the default is 3m. to build the CGC variant, since the default is 3m.
Under Windows, stub libraries for use with Microsoft tools are 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 @filepath{libmzgc@italic{x}.lib} (where @italic{x} represents the
version number) are in a compiler-specific directory in version number) are in a compiler-specific directory in
@filepath{plt\lib}. These libraries identify the bindings that are @filepath{racket\lib}. These libraries identify the bindings that are
provided by @filepath{libmzsch@italic{x}.dll} and provided by @filepath{libracket@italic{x}.dll} and
@filepath{libmzgc@italic{x}.dll} --- which are typically installed @filepath{libmzgc@italic{x}.dll} --- which are typically installed
in @filepath{plt\lib}. When linking with Cygwin, link to in @filepath{racket\lib}. When linking with Cygwin, link to
@filepath{libmzsch@italic{x}.dll} and @filepath{libracket@italic{x}.dll} and
@filepath{libmzgc@italic{x}.dll} directly. At run time, either @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 @filepath{libmzgc@italic{x}.dll} must be moved to a location in the
standard DLL search path, or your embedding application must standard DLL search path, or your embedding application must
``delayload'' link the DLLs and explicitly load them before ``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.) strategy.)
Under Mac OS X, dynamic libraries are provided by the 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 @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 with @exec{-F} and a path to the @filepath{lib} directory. Beware
that CGC and 3m libraries are installed as different versions within that CGC and 3m libraries are installed as different versions within
a single framework, and installation marks one version or the other a single framework, and installation marks one version or the other
as the default (by setting symbolic links); install only CGC to as the default (by setting symbolic links); install only CGC to
simplify accessing the CGC version within the framework. At run 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 location in the standard framework search path, or your embedding
executable must provide a specific path to the framework (possibly executable must provide a specific path to the framework (possibly
an executable-relative path using the Mach-O @tt["@executable_path"] an executable-relative path using the Mach-O @tt["@executable_path"]
prefix).} 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}}. @cpp{#include} the file @as-index{@filepath{scheme.h}}.
The C preprocessor symbol @cppi{SCHEME_DIRECT_EMBEDDED} is defined The C preprocessor symbol @cppi{SCHEME_DIRECT_EMBEDDED} is defined
as @cpp{1} when @filepath{scheme.h} is @cpp{#include}d, or as as @cpp{1} when @filepath{scheme.h} is @cpp{#include}d, or as
@cpp{0} when @filepath{escheme.h} is @cpp{#include}d. @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 the installation's @filepath{include} directory. Building and
installing from source also places this file in the installation's installing from source also places this file in the installation's
@filepath{include} directory.} @filepath{include} directory.}
@item{Start your main program through the @cpp{scheme_main_setup} (or @item{Start your main program through the @cpp{scheme_main_setup} (or
@cpp{scheme_main_stack_setup}) trampoline, and put all uses of @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 @cpp{scheme_main_setup}. The @cpp{scheme_main_setup} function
registers the current C stack location with the memory manager. It registers the current C stack location with the memory manager. It
also creates the initial namespace @cpp{Scheme_Env*} by calling 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 @item{Configure the namespace by adding module declarations. The
initial namespace contains declarations only for a few primitive 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. into the top-level environment.
To embed a module like @schememodname[scheme/base] (along with all To embed a module like @racketmodname[racket/base] (along with all
its dependencies), use @exec{mzc --c-mods}, which generates a C file its dependencies), use @exec{raco ctool --c-mods}, which generates a C file
that contains modules in bytecode form as encapsulated in a static that contains modules in bytecode form as encapsulated in a static
array. The generated C file defines a @cppi{declare_modules} array. The generated C file defines a @cppi{declare_modules}
function that takes a @cpp{Scheme_Env*}, installs the modules into 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 @cpp{scheme_init_collection_paths} to configure and install a path
for finding modules at run time.} 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 @cppi{scheme_load}, @cppi{scheme_eval}, and/or other functions
described in this manual. 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| certain privileged operations, such as installing a @|PLaneT|
package.} 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 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 structures allocated with @cppi{scheme_malloc}. In an embedding
application on some platforms, static variables are also automatically application on some platforms, static variables are also automatically
registered as roots for garbage collection (but see notes below 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 For example, the following is a simple embedding program which
evaluates all expressions provided on the command line and displays 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 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 and all of its transitive imports (so that they need not be found
separately a run time). 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 embedded modules in "base.c": */
declare_modules(e); 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(), curout = scheme_get_param(scheme_current_config(),
MZCONFIG_OUTPUT_PORT); MZCONFIG_OUTPUT_PORT);
@ -433,7 +443,7 @@ static int run(Scheme_Env *e, int argc, char *argv[])
scheme_display(v, curout); scheme_display(v, curout);
scheme_display(scheme_make_char('\n'), curout); scheme_display(scheme_make_char('\n'), curout);
/* read-eval-print loop, uses initial Scheme_Env: */ /* 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"); a[1] = scheme_intern_symbol("read-eval-print-loop");
scheme_apply(scheme_dynamic_require(2, a), 0, NULL); scheme_apply(scheme_dynamic_require(2, a), 0, NULL);
scheme_current_thread->error_buf = save; 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 using Cygwin, the garbage collector cannot find static variables
automatically. In that case, @cppi{scheme_main_setup} must be called with a automatically. In that case, @cppi{scheme_main_setup} must be called with a
non-zero first argument. 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{MZ_REGISTER_STATIC(curout)} should be inserted before the call to
@cpp{scheme_get_param}. @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 the default collector, @cpp{scheme_main_setup} must be called with a
non-zero first argument. See @secref["im:memoryalloc"] for more non-zero first argument. See @secref["im:memoryalloc"] for more
information. information.
@ -475,7 +485,7 @@ information.
@subsection{3m Embedding} @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 embedding program cooperates with the precise garbage collector as
described in @secref["im:3m"]. described in @secref["im:3m"].
@ -489,31 +499,31 @@ In addition, some library details are different:
@itemize[ @itemize[
@item{Under Unix, the library is just @item{Under Unix, the library is just
@as-index{@filepath{libmzscheme3m.a}} (or @as-index{@filepath{libracket3m.a}} (or
@as-index{@filepath{libmzscheme3m.so}} for a dynamic-library build, @as-index{@filepath{libracket3m.so}} for a dynamic-library build,
with @as-index{@filepath{libmzscheme3m.la}} for use with with @as-index{@filepath{libracket3m.la}} for use with
@exec{libtool}). There is no separate library for 3m analogous to @exec{libtool}). There is no separate library for 3m analogous to
CGC's @filepath{libmzgc.a}.} CGC's @filepath{libmzgc.a}.}
@item{Under Windows, the stub library for use with Microsoft tools is @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 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 separate library for 3m analogous to CGC's
@filepath{libmzgc@italic{x}.lib}.} @filepath{libmzgc@italic{x}.lib}.}
@item{Under Mac OS X, 3m dynamic libraries are provided by the @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}.} 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. with a non-zero first argument.
The simple embedding program from the previous section can be The simple embedding program from the previous section can be
processed by @exec{mzc --xform}, then compiled and linked with processed by @exec{raco ctool --xform}, then compiled and linked with
MzScheme3m. Alternately, the source code can be extended to work 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 either CGC or 3m depending on whether @cpp{MZ_PRECISE_GC} is defined
on the compiler's command line: on the compiler's command line:
@ -541,7 +551,7 @@ static int run(Scheme_Env *e, int argc, char *argv[])
declare_modules(e); declare_modules(e);
v = scheme_intern_symbol("scheme/base"); v = scheme_intern_symbol("racket/base");
scheme_namespace_require(v); scheme_namespace_require(v);
config = scheme_current_config(); config = scheme_current_config();
@ -559,7 +569,7 @@ static int run(Scheme_Env *e, int argc, char *argv[])
v = scheme_make_char('\n'); v = scheme_make_char('\n');
scheme_display(v, curout); scheme_display(v, curout);
/* read-eval-print loop, uses initial Scheme_Env: */ /* 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"); a[1] = scheme_intern_symbol("read-eval-print-loop");
v = scheme_dynamic_require(2, a); v = scheme_dynamic_require(2, a);
scheme_apply(v, 0, NULL); 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 Racket implements threads for Racket programs without aid from the
operating system, so that MzScheme threads are cooperative from the operating system, so that Racket threads are cooperative from the
perspective of C code. Under Unix, stand-alone MzScheme uses a single perspective of C code. Under Unix, stand-alone Racket uses a single
OS-implemented thread. Under Windows and Mac OS X, stand-alone 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 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 OS-implemented threads, but the additional OS threads must not call
any @cpp{scheme_} function. Only the OS thread that originally calls any @cpp{scheme_} function. Only the OS thread that originally calls
@cpp{scheme_basic_env} can call @cpp{scheme_} functions. (This @cpp{scheme_basic_env} can call @cpp{scheme_} functions. (This
restriction is stronger than saying all calls must be serialized 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 avoid stack overflow and garbage collection.) When
@cpp{scheme_basic_env} is called a second time to reset the @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 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. @cpp{scheme_} functions must originate from the new thread.
See @secref["threads"] for more information about threads, including 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. 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} --- 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. @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 functions accept @cpp{char*} strings. When such byte strings are to be
used as a character strings, they are interpreted as UTF-8 used as a character strings, they are interpreted as UTF-8
encodings. A plain ASCII string is always acceptable in such cases, 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} @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 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 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 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} @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 @cppi{scheme_input_port_type} and @cppi{scheme_output_port_type}. The
function @cppi{scheme_read} takes an input port value and returns the function @cppi{scheme_read} takes an input port value and returns the
next S-expression from the port. The function @cppi{scheme_write} 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 Custom ports, with arbitrary read/write handlers, are created with
@cppi{scheme_make_input_port} and @cppi{scheme_make_output_port}. @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 use @cppi{scheme_expand_filename} to normalize the filename and
resolve relative paths. 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* obj]
[Scheme_Object* port])]{ [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.} port.}
@function[(void scheme_display_w_max @function[(void scheme_display_w_max
@ -119,7 +119,7 @@ without the non-blocking option.}
[Scheme_Object* obj] [Scheme_Object* obj]
[long* len])]{ [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 allocated string. If @var{len} is not @cpp{NULL}, @cpp{*@var{len}} is
set to the length of the bytes string.} 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] [Scheme_Object* obj]
[long* len])]{ [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 allocated string. If @var{len} is not @cpp{NULL}, @cpp{*@var{len}} is
set to the length of the string.} 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 @function[(void scheme_debug_print
[Scheme_Object* obj])]{ [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.} thread's output port.}
@function[(void scheme_flush_output @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 in @var{unless} becomes ready before bytes can be read. In
particular, @var{get_bytes_fun} should check the event in particular, @var{get_bytes_fun} should check the event in
@var{unless} before taking any action, and it should check the @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 thread swaps. If the read must block, then it should unblock if
the event in @var{unless} becomes ready. the event in @var{unless} becomes ready.
@ -439,7 +439,7 @@ The functions are as follows.
use @cpp{scheme_block_until_unless} instead of use @cpp{scheme_block_until_unless} instead of
@cpp{scheme_block_until}. Finally, in blocking mode, @cpp{scheme_block_until}. Finally, in blocking mode,
@var{get_bytes_fun} must return after immediately reading data, @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 @subfunction[(long peek_bytes_fun
[Scheme_Input_Port* port] [Scheme_Input_Port* port]
@ -652,7 +652,7 @@ Opens @var{filename} for reading. In an exception is raised, the
[FILE* fp] [FILE* fp]
[Scheme_Object* name])]{ [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 must never block on reads. The @var{name} argument is used as the
port's name.} 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 @function[(Scheme_Object* scheme_make_file_output_port
[FILE* fp])]{ [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.} file must never block on writes.}
@function[(Scheme_Object* scheme_make_fd_input_port @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 regfile]
[int win_textmode])]{ [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 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. 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 win_textmode]
[int read_too])]{ [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 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. 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** inp]
[Scheme_Object** outp])]{ [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} @var{name} argument supplies the name for the ports. If @var{close}
is non-zero, then the ports assume responsibility for closing the is non-zero, then the ports assume responsibility for closing the
socket. The resulting ports are written to @var{inp} and @var{outp}.} 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 @function[(Scheme_Object* scheme_make_byte_string_input_port
[char* str])]{ [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 @scheme[read-char]s on the port return successive bytes in the
string.} string.}
@function[(Scheme_Object* scheme_make_byte_string_output_port)]{ @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}.} which can be obtained with @cpp{scheme_get_byte_string_output}.}
@function[(char* 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 @function[(Scheme_Object* scheme_char_string_to_path
[Scheme_Object* s])]{ [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 @function[(Scheme_Object* scheme_path_to_char_string
[Scheme_Object* s])]{ [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 @function[(Scheme_Object* scheme_make_path
[char* bytes])]{ [char* bytes])]{
@ -923,7 +923,7 @@ no 0, then an exception is raised if the operation fails.}
[int noexn])]{ [int noexn])]{
Sets the current working directory according to the operating system. This 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 If @var{noexn} is not 0, then an exception is raised if the operation
fails.} fails.}
@ -935,7 +935,7 @@ fails.}
[Scheme_Object** argv] [Scheme_Object** argv]
[long* rlen])]{ [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 format string @var{format} (of length @var{flen}) and the extra
arguments specified in @var{argc} and @var{argv}. If @var{rlen} is not 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 @cpp{NULL}, @cpp{*@var{rlen}} is filled with the length of the
@ -947,7 +947,7 @@ resulting string.}
[int argc] [int argc]
[Scheme_Object** argv])]{ [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}) procedure, using the format string @var{format} (of length @var{flen})
and the extra arguments specified in @var{argc} and @var{argv}.} 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} @title{Procedures}
A @defterm{primitive procedure} is a Scheme-callable procedure that is A @defterm{primitive procedure} is a Racket-callable procedure that is
implemented in C. Primitive procedures are created in Scheme with implemented in C. Primitive procedures are created in Racket with
the function @cppi{scheme_make_prim_w_arity}, which takes a C function the function @cppi{scheme_make_prim_w_arity}, which takes a C function
pointer, the name of the primitive, and information about the number 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. value.
The C function implementing the procedure must take two arguments: an 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 procedure, and an array of @cpp{Scheme_Object*} arguments. The number
of arguments passed to the function will be checked using the arity of arguments passed to the function will be checked using the arity
information. (The arity information provided to 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 @scheme[arity] procedure.) The procedure implementation is not allowed
to mutate the input array of arguments; as an exception, the procedure 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 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 -1 if the procedure can take arbitrarily many arguments. The
@var{mina} and @var{maxa} values are used for automatically checking @var{mina} and @var{maxa} values are used for automatically checking
the argument count before the primitive is invoked, and also for the 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.} used to report application arity errors at run-time.}
@function[(Scheme_Object* scheme_make_folding_prim @function[(Scheme_Object* scheme_make_folding_prim

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

@ -3,7 +3,7 @@
@title{Structures} @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 @cppi{scheme_make_struct_type}. This creates the structure type, but
does not generate the constructor, etc. procedures. The does not generate the constructor, etc. procedures. The
@cppi{scheme_make_struct_values} function takes a structure type and @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 @item{@cppi{SCHEME_STRUCT_GEN_SET} --- the field-independent
mutator procedure value/name is returned.} 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 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 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 structure type; it should be the same symbol passed to the associated
call to @cpp{scheme_make_struct_type}. The @var{field_names} argument 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 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 not @cpp{NULL}, @var{count_out} is filled with the number of names
returned in the array.} returned in the array.}

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

@ -5,10 +5,10 @@
@title[#:tag "threads"]{Threads} @title[#:tag "threads"]{Threads}
The initializer function @cppi{scheme_basic_env} creates the main 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}. @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 @cppi{Scheme_Thread} structure. A pointer to the current thread's
structure is available as @cppi{scheme_current_thread}. A structure is available as @cppi{scheme_current_thread}. A
@cpp{Scheme_Thread} structure includes the following fields: @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} @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[ @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 pointer in the global variable, it may point to data that is not
currently on the stack.} currently on the stack.}
@item{@italic{C functions that can invoke Scheme (and also be invoked @item{@italic{C functions that can invoke Racket (and also be invoked
by Scheme) depend on strict function-call nesting.} For example, by Racket) depend on strict function-call nesting.} For example,
suppose a function F uses an internal stack, pushing items on to the 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 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 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 the first thread before completing the second F, then F's internal
stack will be corrupted.} 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} @section[#:tag "usefuel"]{Allowing Thread Switches}
C code that performs substantial or unbounded work should occasionally C code that performs substantial or unbounded work should occasionally
call @cppi{SCHEME_USE_FUEL}---actually a macro---which allows Scheme call @cppi{SCHEME_USE_FUEL}---actually a macro---which allows Racket
to swap in another Scheme thread to run, and to check for breaks on to swap in another Racket thread to run, and to check for breaks on
the current thread. In particular, if breaks are enabled, then the current thread. In particular, if breaks are enabled, then
@cpp{SCHEME_USE_FUEL} may trigger an exception. @cpp{SCHEME_USE_FUEL} may trigger an exception.
@ -110,18 +110,18 @@ expression.
@section[#:tag "threadblock"]{Blocking the Current Thread} @section[#:tag "threadblock"]{Blocking the Current Thread}
Embedding or extension code sometimes needs to block, but blocking 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 to run, block using @cppi{scheme_block_until}. This procedure takes
two functions: a polling function that tests whether the blocking two functions: a polling function that tests whether the blocking
operation can be completed, and a prepare-to-sleep function that sets 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 threads are blocked). Under Windows, an ``@cpp{fd_set}'' can also
accommodate OS-level semaphores or other handles via accommodate OS-level semaphores or other handles via
@cpp{scheme_add_fd_handle}. @cpp{scheme_add_fd_handle}.
Since the functions passed to @cppi{scheme_block_until} are called by Since the functions passed to @cppi{scheme_block_until} are called by
the Scheme thread scheduler, they must never raise exceptions, call the Racket thread scheduler, they must never raise exceptions, call
@cpp{scheme_apply}, or trigger the evaluation of Scheme code in any @cpp{scheme_apply}, or trigger the evaluation of Racket code in any
way. The @cpp{scheme_block_until} function itself may call the current way. The @cpp{scheme_block_until} function itself may call the current
exception handler, however, in reaction to a break (if breaks are exception handler, however, in reaction to a break (if breaks are
enabled). 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}. a semaphore accessor with @cppi{scheme_add_evt_through_sema}.
The @cppi{scheme_signal_received} function can be called to wake up The @cppi{scheme_signal_received} function can be called to wake up
Scheme when it is sleeping. In particular, calling Racket when it is sleeping. In particular, calling
@cppi{scheme_signal_received} ensures that Scheme will poll all @cppi{scheme_signal_received} ensures that Racket will poll all
blocking synchronizations soon afterward. Furthermore, blocking synchronizations soon afterward. Furthermore,
@cpp{scheme_signal_received} can be called from any OS-level thread. @cpp{scheme_signal_received} can be called from any OS-level thread.
Thus, when no adequate prepare-to-sleep function can be implemented 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 When Racket is embedded in an application with an event-based model
(i.e., the execution of Scheme code in the main thread is repeatedly (i.e., the execution of Racket code in the main thread is repeatedly
triggered by external events until the application exits) special triggered by external events until the application exits) special
hooks must be set to ensure that non-main threads execute hooks must be set to ensure that non-main threads execute
correctly. For example, during the execution in the main thread, a new 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 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 main thread returns to the event loop, and it may be arbitrarily long
before the main thread continues from the event loop. Under such 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 execute the non-main threads; this can be done by periodically calling
the function @cppi{scheme_check_threads}. 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 checking is no longer necessary. An embedding program can use this
information to prevent unnecessary @cpp{scheme_check_threads} polling. 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} @cpp{scheme_check_threads} polling using the wxWindows @cpp{wxTimer}
class. (Any regular event-loop-based callback is appropriate.) The class. (Any regular event-loop-based callback is appropriate.) The
@cpp{scheme_notify_multithread} pointer is set to @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]{ @verbatim[#:indent 2]{
class MrEdThreadTimer : public wxTimer 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. 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 efficiently because the main thread blocks on a file descriptor, as
explained in @secref["threadblock"]. explained in @secref["threadblock"].
@subsection[#:tag "blockednonmainel"]{Callbacks for Blocked Threads} @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 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 block the main thread, and therefore do not affect the event loop, so
@cppi{scheme_check_threads} is sufficient to implement this case @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 ready on any of those file descriptors, the callbacks are removed and
@cpp{scheme_wake_up} is called. @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}: @cpp{scheme_wakeup_on_input} to this @cpp{MrEdNeedWakeup}:
@verbatim[#:indent 2]{ @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 certain number of seconds or until external input appears on some file
descriptor. Generally, sleeping should block the main event loop of descriptor. Generally, sleeping should block the main event loop of
the entire application. However, the way in which sleeping is the entire application. However, the way in which sleeping is
performed may depend on the embedding application. The global function performed may depend on the embedding application. The global function
pointer @cppi{scheme_sleep} can be set by an embedding application to 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. for you.
A @cpp{scheme_sleep} function takes two arguments: a @cpp{float} and a 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 The following function @cpp{mzsleep} is an appropriate
@cpp{scheme_sleep} function for most any Unix or Windows application. @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]{ @verbatim[#:indent 2]{
void mzsleep(float v, void *fds) 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} a @cpp{Scheme_Object*} value, because it is only used by @var{f}
and @var{fdf}.) 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 sets bits in @var{fds}, conceptually an array of three
@cpp{fd_set}s: one or reading, one for writing, and one for @cpp{fd_set}s: one or reading, one for writing, and one for
exceptions. Use @cpp{scheme_get_fdset} to get elements of this 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 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 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 through a socket or OS-level semaphore)---with the exception that
@cpp{scheme_signal_received} may be called to indicate an external @cpp{scheme_signal_received} may be called to indicate an external
change. 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 Indicates that an external event may have caused the result of a
synchronization poll to have a different result. Unlike most other synchronization poll to have a different result. Unlike most other
Scheme functions, this one can be called from any OS-level thread, and Racket functions, this one can be called from any OS-level thread, and
it wakes up if the Scheme thread if it is sleeping.} it wakes up if the Racket thread if it is sleeping.}
@function[(void scheme_check_threads)]{ @function[(void scheme_check_threads)]{
@ -577,12 +577,12 @@ Extracts an ``@cpp{fd_set}'' from an array passed to
[int repost])]{ [int repost])]{
Adds an OS-level semaphore (Windows) or other waitable handle 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 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. 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 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 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 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])]{ [int mask])]{
Adds an OS-level event type (Windows) to the set of types in the 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 ``@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. sleep until it is awakened by an external process.
The event mask is only used when some handle is installed with 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_Thread_Cell_Table* cells]
[Scheme_Object* v])]{ [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 @cpp{scheme_end_atomic_no_swap} is called. Start-atomic and
end-atomic pairs can be nested.} end-atomic pairs can be nested.}
@function[(void scheme_end_atomic)]{ @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 thread may be swapped out immediately (i.e., the call to
@cpp{scheme_end_atomic} is assumed to be a safe point for thread @cpp{scheme_end_atomic} is assumed to be a safe point for thread
swaps).} swaps).}
@function[(void scheme_end_atomic_no_swap)]{ @function[(void scheme_end_atomic_no_swap)]{
Ends an atomic region with respect to Scheme threads, and also Ends an atomic region with respect to Racket threads, and also
prevents an immediate thread swap. (In other words, no Scheme prevents an immediate thread swap. (In other words, no Racket
thread swaps will occur until a future safe point.)} thread swaps will occur until a future safe point.)}
@function[(void scheme_add_swap_callback @function[(void scheme_add_swap_callback
[Scheme_Closure_Func f] [Scheme_Closure_Func f]
[Scheme_Object* data])]{ [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 swapped in. The @var{data} is provided back to @var{f} when it is
called, where @cpp{Closure_Func} is defined as follows: 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])]{ [Scheme_Object* data])]{
Like @cpp{scheme_add_swap_callback}, but registers a callback to be 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 cppdef (lambda (x) (as-cpp-defn x (cpp x))))
(define *var italic) (define *var italic)
(define mzc (exec "mzc")) (define mzc (exec "raco ctool"))
(define (refsecref s) (define (refsecref s)
(secref #:doc '(lib "scribblings/reference/reference.scrbl") 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} @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 a mark bit: a 1 in the low bit indicates an immediate integer, a 0
indicates a (word-aligned) pointer. 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 @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, that has the C type @cppi{Scheme_Type}. The rest of the structure,
following the @cppi{Scheme_Object} header, is type-dependent. 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 @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} Examples of @cpp{Scheme_Type} values include @cpp{scheme_pair_type}
and @cpp{scheme_symbol_type}. Some of these are implemented as and @cpp{scheme_symbol_type}. Some of these are implemented as
instances of @cppi{Scheme_Simple_Object}, which is defined in instances of @cppi{Scheme_Simple_Object}, which is defined in
@filepath{scheme.h}, but extension or embedding code should never access @filepath{scheme.h}, but extension or embedding code should never access
this structure directly. Instead, the code should use macros, such as 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. 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 of the type. For example, @cpp{scheme_make_pair} takes two
@cpp{Scheme_Object*} values and returns the @scheme[cons] of the @cpp{Scheme_Object*} values and returns the @scheme[cons] of the
values. 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 the type of the object. This macro performs the tag-bit check, and
returns @cppi{scheme_integer_type} when the value is an immediate returns @cppi{scheme_integer_type} when the value is an immediate
integer; otherwise, @cpp{SCHEME_TYPE} follows the pointer to get the 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 example, @cpp{SCHEME_PAIRP} returns @cpp{1} if the value is a cons
cell, @cpp{0} otherwise. cell, @cpp{0} otherwise.
In addition to providing constructors, PLT Scheme defines six global In addition to providing constructors, Racket defines six global
constant Scheme values: @cppi{scheme_true}, @cppi{scheme_false}, constant Racket values: @cppi{scheme_true}, @cppi{scheme_false},
@cppi{scheme_null}, @cppi{scheme_eof}, @cppi{scheme_void}, and @cppi{scheme_null}, @cppi{scheme_eof}, @cppi{scheme_void}, and
@cppi{scheme_undefined}. Each of these has a type tag, but each is @cppi{scheme_undefined}. Each of these has a type tag, but each is
normally recognized via its constant address. 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 can create new a primitive data type by calling
@cppi{scheme_make_type}, which returns a fresh @cpp{Scheme_Type} @cppi{scheme_make_type}, which returns a fresh @cpp{Scheme_Type}
value. To create a collectable instance of this type, allocate memory 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 perspective, the main constraint on the data format of such an
instance is that the first @cpp{sizeof(Scheme_Object)} bytes must instance is that the first @cpp{sizeof(Scheme_Object)} bytes must
correspond to a @cpp{Scheme_Object} record; furthermore, the first 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 @cpp{scheme_make_type}. Extensions with modest needs can use
@cppi{scheme_make_cptr}, instead of creating an entirely new type. @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 never contain pointers to values on the stack. Besides the problem of
restricting the value's lifetime to that of the stack frame, restricting the value's lifetime to that of the stack frame,
allocating values on the stack creates problems for continuations and 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}} floating-point value; test for this type with @cppdef{SCHEME_DBLP}}
@item{@cppdef{scheme_float_type} --- single-precision flonum @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 @cppi{SCHEME_FLOAT_VAL} or @cppdef{SCHEME_FLT_VAL} extracts the
floating-point value; test for this type with @cppdef{SCHEME_FLTP}} floating-point value; test for this type with @cppdef{SCHEME_FLTP}}
@ -109,7 +109,7 @@ types:
@item{@cppdef{scheme_char_string_type} --- @index['("strings" @item{@cppdef{scheme_char_string_type} --- @index['("strings"
"conversion to C")]{@cppdef{SCHEME_CHAR_STR_VAL}} extracts the string "conversion to C")]{@cppdef{SCHEME_CHAR_STR_VAL}} extracts the string
as a @cpp{mzchar*}; the string is always nul-terminated, but may also 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 this string is modified; @cppdef{SCHEME_CHAR_STRLEN_VAL} extracts the
string length (in characters, not counting the nul terminator); test string length (in characters, not counting the nul terminator); test
for this type with @cppdef{SCHEME_CHAR_STRINGP}} for this type with @cppdef{SCHEME_CHAR_STRINGP}}
@ -117,7 +117,7 @@ types:
@item{@cppdef{scheme_byte_string_type} --- @item{@cppdef{scheme_byte_string_type} ---
@cppdef{SCHEME_BYTE_STR_VAL} extracts the string as a @cpp{char*}; the @cppdef{SCHEME_BYTE_STR_VAL} extracts the string as a @cpp{char*}; the
string is always nul-terminated, but may also contain embedded nul 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 modified; @cppdef{SCHEME_BYTE_STRLEN_VAL} extracts the string length
(in bytes, not counting the nul terminator); test for this type with (in bytes, not counting the nul terminator); test for this type with
@cppdef{SCHEME_BYTE_STRINGP}} @cppdef{SCHEME_BYTE_STRINGP}}
@ -158,7 +158,7 @@ types:
@item{@cppdef{scheme_vector_type} --- @cppdef{SCHEME_VEC_SIZE} @item{@cppdef{scheme_vector_type} --- @cppdef{SCHEME_VEC_SIZE}
extracts the length and @cppdef{SCHEME_VEC_ELS} extracts the array of 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 modified); test for this type with @cppdef{SCHEME_VECTORP}; 3m: see
@secref["im:3m"] for a caution about @cppi{SCHEME_VEC_ELS}} @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 @item{@cppdef{scheme_closed_prim_type} --- an old-style primitive
procedure with a data pointer} procedure with a data pointer}
@item{@cppdef{scheme_compiled_closure_type} --- a Scheme @item{@cppdef{scheme_compiled_closure_type} --- a Racket
procedure} procedure}
@item{@cppdef{scheme_cont_type} --- a continuation} @item{@cppdef{scheme_cont_type} --- a continuation}
@ -289,9 +289,9 @@ There are six global constants:
@section[#:tag "im:strings"]{Strings} @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 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. are @cpp{char} arrays.
For a character string @var{s}, @cpp{@cpp{SCHEME_CHAR_STR_VAL}(@var{s})} 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 Returns the character value. The @var{ch} value must be a legal
Unicode code point (and not a surrogate, for example). The first 256 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.} allocated.}
@function[(Scheme_Object* scheme_make_char_or_null @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, Extracts the integer value. Unlike the @cppi{SCHEME_INT_VAL} macro,
this procedure will extract an integer that fits in a @cpp{long} from 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 integer is placed in @var{*i} and 1 is returned; otherwise, 0 is
returned and @var{*i} is unmodified.} returned and @var{*i} is unmodified.}
@ -422,13 +422,13 @@ Creates a new floating-point value.}
[float d])]{ [float d])]{
Creates a new single-precision floating-point value. The procedure is 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.} numbers enabled.}
@function[(double scheme_real_to_double @function[(double scheme_real_to_double
[Scheme_Object* o])]{ [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.} value.}
@function[(Scheme_Object* scheme_make_pair @function[(Scheme_Object* scheme_make_pair
@ -440,7 +440,7 @@ Makes a @scheme[cons] pair.}
@function[(Scheme_Object* scheme_make_byte_string @function[(Scheme_Object* scheme_make_byte_string
[char* bytes])]{ [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.} @var{bytes} string is copied.}
@function[(Scheme_Object* scheme_make_byte_string_without_copying @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] [long size]
[char fill])]{ [char fill])]{
Allocates a new Scheme byte string.} Allocates a new Racket byte string.}
@function[(Scheme_Object* scheme_append_byte_string @function[(Scheme_Object* scheme_append_byte_string
[Scheme_Object* a] [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 @function[(Scheme_Object* scheme_make_locale_string
[char* bytes])]{ [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 locale-specific encoding of a character string; a new string is
allocated during decoding. The ``locale in the name of this function allocated during decoding. The ``locale in the name of this function
thus refers to @var{bytes}, and not the resulting string (which is 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 @function[(Scheme_Object* scheme_make_utf8_string
[char* bytes])]{ [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 UTF-8 encoding. A new string is allocated during decoding. The
``utf8'' in the name of this function thus refers to @var{bytes}, and ``utf8'' in the name of this function thus refers to @var{bytes}, and
not the resulting string (which is internally stored as UCS-4).} 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 @function[(Scheme_Object* scheme_make_char_string
[mzchar* chars])]{ [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.} @var{chars} string is copied.}
@function[(Scheme_Object* scheme_make_char_string_without_copying @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] [long size]
[mzchar fill])]{ [mzchar fill])]{
Allocates a new Scheme string.} Allocates a new Racket string.}
@function[(Scheme_Object* scheme_append_char_string @function[(Scheme_Object* scheme_append_char_string
[Scheme_Object* a] [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 @function[(Scheme_Object* scheme_char_string_to_byte_string
[Scheme_Object* s])]{ [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 @function[(Scheme_Object* scheme_byte_string_to_char_string
[Scheme_Object* s])]{ [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 @function[(Scheme_Object* scheme_char_string_to_byte_string_locale
[Scheme_Object* s])]{ [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 @function[(Scheme_Object* scheme_byte_string_to_char_string_locale
[Scheme_Object* s])]{ [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 @function[(Scheme_Object* scheme_intern_symbol
[char* name])]{ [char* name])]{
@ -654,7 +654,7 @@ Creates a new weak box containing the value @var{v}.}
@function[(Scheme_Type scheme_make_type @function[(Scheme_Type scheme_make_type
[char* name])]{ [char* name])]{
Creates a new type (not a Scheme value).} Creates a new type (not a Racket value).}
@function[(Scheme_Object* scheme_make_cptr @function[(Scheme_Object* scheme_make_cptr
[void* ptr] [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 @var{typetag} to identify the type of the pointer. The
@cppi{SCHEME_CPTRP} macro recognizes objects created by @cppi{SCHEME_CPTRP} macro recognizes objects created by
@cpp{scheme_make_cptr}. The @cppi{SCHEME_CPTR_VAL} macro extracts @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. @cppi{SCHEME_CPTR_TYPE} extracts the type tag.
The @cppi{SCHEME_CPTR_OFFSETVAL} macro returns @cpp{0} 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 The @var{ptr} can refer to either memory managed by the garbage
collector or by some other memory manager. Beware, however, of 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}. Creates a C-pointer object that encapsulates both @var{ptr} and @var{offset}.
The @cppi{SCHEME_CPTR_OFFSETVAL} macro returns @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). since it also works on objects with no offset).
The @var{ptr} can refer to either memory managed by the garbage The @var{ptr} can refer to either memory managed by the garbage