From 77a99f6aa07340736b55cec2e0588b479870800c Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Fri, 30 Apr 2010 21:58:08 -0600 Subject: [PATCH] rackety inside doc --- collects/scribblings/inside/custodians.scrbl | 4 +- collects/scribblings/inside/eval.scrbl | 18 +- collects/scribblings/inside/exns.scrbl | 46 ++-- collects/scribblings/inside/hooks.scrbl | 8 +- collects/scribblings/inside/inside.scrbl | 10 +- collects/scribblings/inside/memory.scrbl | 28 +-- collects/scribblings/inside/misc.scrbl | 16 +- collects/scribblings/inside/namespaces.scrbl | 18 +- collects/scribblings/inside/numbers.scrbl | 12 +- collects/scribblings/inside/overview.scrbl | 246 ++++++++++--------- collects/scribblings/inside/ports.scrbl | 40 +-- collects/scribblings/inside/procedures.scrbl | 10 +- collects/scribblings/inside/structures.scrbl | 8 +- collects/scribblings/inside/threads.scrbl | 88 +++---- collects/scribblings/inside/utils.rkt | 2 +- collects/scribblings/inside/values.scrbl | 72 +++--- 16 files changed, 321 insertions(+), 305 deletions(-) diff --git a/collects/scribblings/inside/custodians.scrbl b/collects/scribblings/inside/custodians.scrbl index b9f5a3b269..c080a4d3b2 100644 --- a/collects/scribblings/inside/custodians.scrbl +++ b/collects/scribblings/inside/custodians.scrbl @@ -4,7 +4,7 @@ @title{Custodians} When an extension allocates resources that must be explicitly freed -(in the same way that a port must be explicitly closed), a Scheme +(in the same way that a port must be explicitly closed), a Racket object associated with the resource should be placed into the management of the current custodian with @cppi{scheme_add_managed}. @@ -93,7 +93,7 @@ Instructs the custodian @var{m} to shutdown all of its managed values.} [Scheme_Exit_Closer_Func f])]{ Installs a function to be called on each custodian-registered item and - its closer when MzScheme is about to exit. The registered function + its closer when Racket is about to exit. The registered function has the type @verbatim[#:indent 2]{ diff --git a/collects/scribblings/inside/eval.scrbl b/collects/scribblings/inside/eval.scrbl index 0e5be83fee..91854641c2 100644 --- a/collects/scribblings/inside/eval.scrbl +++ b/collects/scribblings/inside/eval.scrbl @@ -3,7 +3,7 @@ @title{Evaluation} -A Scheme S-expression is evaluated by calling @cppi{scheme_eval}. +A Racket S-expression is evaluated by calling @cppi{scheme_eval}. This function takes an S-expression (as a @cpp{Scheme_Object*}) and a namespace and returns the value of the expression in that namespace. @@ -12,7 +12,7 @@ a procedure, the number of arguments to pass to the procedure, and an array of @cpp{Scheme_Object *} arguments. The return value is the result of the application. There is also a function @cppi{scheme_apply_to_list}, which takes a procedure and a list -(constructed with @cppi{scheme_make_pair}) and performs the Scheme +(constructed with @cppi{scheme_make_pair}) and performs the Racket @scheme[apply] operation. The @cppi{scheme_eval} function actually calls @cppi{scheme_compile} @@ -43,15 +43,15 @@ see @secref["exceptions"]. @section-index{tail recursion} -All of Scheme's built-in functions and syntax support proper +All of Racket's built-in functions and syntax support proper tail-recursion. When a new primitive procedure or syntax is added to -Scheme, special care must be taken to ensure that tail recursion is +Racket, special care must be taken to ensure that tail recursion is handled properly. Specifically, when the final return value of a function is the result of an application, then @cppi{scheme_tail_apply} should be used instead of @cppi{scheme_apply}. When @cppi{scheme_tail_apply} is called, it postpones the procedure application until control returns to the -Scheme evaluation loop. +Racket evaluation loop. For example, consider the following implementation of a @scheme[thunk-or] primitive, which takes any number of thunks and @@ -158,9 +158,9 @@ Non-top-level version of @cpp{scheme_eval_compiled_multi}. (See @secref["topleve @function[(Scheme_Env* scheme_basic_env)]{ -Creates the main namespace for an embedded PLT Scheme. This procedure -must be called before other Scheme library function (except -@cpp{scheme_make_param}). Extensions to Scheme cannot call this +Creates the main namespace for an embedded Racket. This procedure +must be called before other Racket library function (except +@cpp{scheme_make_param}). Extensions to Racket cannot call this function. If it is called more than once, this function resets all threads @@ -176,7 +176,7 @@ Creates and returns a new namespace. This values can be cast to a parameterization using @cppi{scheme_set_param} with @cppi{MZCONFIG_ENV}. -When PLT Scheme is embedded in an application, create the initial +When Racket is embedded in an application, create the initial namespace with @cppi{scheme_basic_env} before calling this procedure to create new namespaces.} diff --git a/collects/scribblings/inside/exns.scrbl b/collects/scribblings/inside/exns.scrbl index e29b7f55a5..0b26ce2914 100644 --- a/collects/scribblings/inside/exns.scrbl +++ b/collects/scribblings/inside/exns.scrbl @@ -3,7 +3,7 @@ @title[#:tag "exceptions"]{Exceptions and Escape Continuations} -When Scheme encounters an error, it raises an exception. The default +When Racket encounters an error, it raises an exception. The default exception handler invokes the error display handler and then the error escape handler. The default error escape handler escapes via a @defterm{primitive error escape}, which is implemented by calling @@ -12,7 +12,7 @@ escape handler. The default error escape handler escapes via a An embedding program should install a fresh buffer into @cpp{scheme_current_thread->error_buf} and call @cpp{scheme_setjmp(*scheme_current_thread->error_buf)} before any -top-level entry into Scheme evaluation to catch primitive error +top-level entry into Racket evaluation to catch primitive error escapes. When the new buffer goes out of scope, restore the original in @cpp{scheme_current_thread->error_buf}. The macro @cppi{scheme_error_buf} is a shorthand for @@ -47,12 +47,12 @@ New primitive procedures can raise a generic exception by calling function @cpp{printf}. A specific primitive exception can be raised by calling @cppi{scheme_raise_exn}. -Full @as-index{continuations} are implemented in Scheme by copying +Full @as-index{continuations} are implemented in Racket by copying the C stack and using @cppi{scheme_setjmp} and @cppi{scheme_longjmp}. -As long a C/C++ application invokes Scheme evaluation through the +As long a C/C++ application invokes Racket evaluation through the top-level evaluation functions (@cpp{scheme_eval}, @cpp{scheme_apply}, etc., as opposed to @cpp{_scheme_apply}, @cpp{_scheme_eval_compiled}, -etc.), the code is protected against any unusual behavior from Scheme +etc.), the code is protected against any unusual behavior from Racket evaluations (such as returning twice from a function) because continuation invocations are confined to jumps within a single top-level evaluation. However, escape continuation jumps are still @@ -109,11 +109,11 @@ calls top-level evaluation functions (@cpp{scheme_eval}, @cpp{_scheme_eval_compiled}, etc.). Otherwise, use @cppi{scheme_dynamic_wind} to protect your code against full continuation jumps in the same way that @scheme[dynamic-wind] is used -in Scheme. +in Racket. The above solution simply traps the escape; it doesn't report the reason that the escape occurred. To catch exceptions and obtain -information about the exception, the simplest route is to mix Scheme +information about the exception, the simplest route is to mix Racket code with C-implemented thunks. The code below can be used to catch exceptions in a variety of situations. It implements the function @cpp{_apply_catch_exceptions}, which catches exceptions during the @@ -148,7 +148,7 @@ application of a thunk. (This code is in } } - /* This function applies a thunk, returning the Scheme value if + /* This function applies a thunk, returning the Racket value if there's no exception, otherwise returning NULL and setting *exn to the raised value (usually an exn structure). */ Scheme_Object *_apply_thunk_catch_exceptions(Scheme_Object *f, @@ -184,9 +184,11 @@ In the following example, the above code is used to catch exceptions that occur during while evaluating source code from a string. @verbatim[#:indent 2]{ - static Scheme_Object *do_eval(void *s, int noargc, Scheme_Object **noargv) + static Scheme_Object *do_eval(void *s, int noargc, + Scheme_Object **noargv) { - return scheme_eval_string((char *)s, scheme_get_env(scheme_config)); + return scheme_eval_string((char *)s, + scheme_get_env(scheme_config)); } static Scheme_Object *eval_string_or_get_exn_message(char *s) @@ -213,12 +215,12 @@ that occur during while evaluating source code from a string. @section{Enabling and Disabling Breaks} -When embedding PLT Scheme, asynchronous break exceptions are disabled by +When embedding Racket, asynchronous break exceptions are disabled by default. Call @cpp{scheme_set_can_break} (which is the same as calling -the Scheme funciton @scheme[break-enabled]) to enable or disable +the Racket funciton @scheme[break-enabled]) to enable or disable breaks. To enable or disable breaks during the dynamic extent of another evaluation (where you would use -@scheme[with-break-parameterization] in Scheme), use +@scheme[with-break-parameterization] in Racket), use @cppi{scheme_push_break_enable} before and @cppi{scheme_pop_break_enable} after, instead. @@ -245,7 +247,7 @@ for @cpp{printf}, but with the following format directives: @item{@FormatD{5} : a nul-terminated @cpp{mzchar} string} - @item{@FormatD{S} : a Scheme symbol (a @cpp{Scheme_Object*})} + @item{@FormatD{S} : a Racket symbol (a @cpp{Scheme_Object*})} @item{@FormatD{t} : a @cpp{char} string with a @cpp{long} size (two arguments), possibly containing a non-terminating nul byte, and @@ -255,16 +257,16 @@ for @cpp{printf}, but with the following format directives: arguments), possibly containing a non-terminating nul character, and possibly without a nul-terminator} - @item{@FormatD{T} : a Scheme string (a @cpp{Scheme_Object*})} + @item{@FormatD{T} : a Racket string (a @cpp{Scheme_Object*})} @item{@FormatD{q} : a string, truncated to 253 characters, with ellipses printed if the string is truncated} - @item{@FormatD{Q} : a Scheme string (a @cpp{Scheme_Object*}), + @item{@FormatD{Q} : a Racket string (a @cpp{Scheme_Object*}), truncated to 253 characters, with ellipses printed if the string is truncated} - @item{@FormatD{V} : a Scheme value (a @cpp{Scheme_Object*}), + @item{@FormatD{V} : a Racket value (a @cpp{Scheme_Object*}), truncated according to the current error print width.} @item{@FormatD{e} : an @cpp{errno} value, to be printed as a text @@ -282,7 +284,7 @@ for @cpp{printf}, but with the following format directives: ] The arguments following the format string must include no more than 25 -strings and Scheme values, 25 integers, and 25 floating-point +strings and Racket values, 25 integers, and 25 floating-point numbers. (This restriction simplifies the implementation with precise garbage collection.)} @@ -298,7 +300,7 @@ fields). The remaining arguments start with an error string and proceed roughly as for @cpp{printf}; see @cpp{scheme_signal_error} above for more details. -Exception ids are @cpp{#define}d using the same names as in Scheme, +Exception ids are @cpp{#define}d using the same names as in Racket, but prefixed with ``MZ'', all letters are capitalized, and all ``:'s', ``-''s, and ``/''s are replaced with underscores. For example, @cpp{MZEXN_FAIL_FILESYSTEM} is the exception id for a filesystem @@ -370,8 +372,8 @@ variable.} [int count] [int* len])]{ -Converts a Scheme value into a string for the purposes of reporting an -error message. The @var{count} argument specifies how many Scheme +Converts a Racket value into a string for the purposes of reporting an +error message. The @var{count} argument specifies how many Racket values total will appear in the error message (so the string for this value can be scaled appropriately). If @var{len} is not @cpp{NULL}, it is filled with the length of the returned string.} @@ -384,7 +386,7 @@ is filled with the length of the returned string.} [Scheme_Object** argv] [long* len])]{ -Converts an array of Scheme values into a byte string, skipping the +Converts an array of Racket values into a byte string, skipping the array element indicated by @var{which}. This function is used to specify the ``other'' arguments to a function when one argument is bad (thus giving the user more information about the state of the program diff --git a/collects/scribblings/inside/hooks.scrbl b/collects/scribblings/inside/hooks.scrbl index f792483917..ab2086c0ab 100644 --- a/collects/scribblings/inside/hooks.scrbl +++ b/collects/scribblings/inside/hooks.scrbl @@ -3,7 +3,7 @@ @title{Flags and Hooks} -The following flags and hooks are available when PLT Scheme is +The following flags and hooks are available when Racket is embedded: @itemize[ @@ -14,7 +14,7 @@ embedded: @item{@cppdef{scheme_make_stdin}, @cppdef{scheme_make_stdout}, @cppdef{scheme_make_stderr}, --- These pointers can be set to a - function that takes no arguments and returns a Scheme port + function that takes no arguments and returns a Racket port @cpp{Scheme_Object *} to be used as the starting standard input, output, and/or error port. The defaults are @cpp{NULL}. Setting the initial error port is particularly important for seeing unexpected @@ -22,7 +22,7 @@ embedded: @item{@cppdef{scheme_console_output} --- This pointer can be set to a function that takes a string and a @cpp{long} string length; the - function will be called to display internal MzScheme warnings and + function will be called to display internal Racket warnings and messages that possibly contain non-terminating nuls. The default is @var{NULL}.} @@ -36,7 +36,7 @@ embedded: @item{@cppdef{scheme_case_sensitive} --- If this flag is set to a non-zero value before @cppi{scheme_basic_env} is called, then - MzScheme will not ignore capitalization for symbols and global + Racket will not ignore capitalization for symbols and global variable names. The value of this flag should not change once it is set. The default is zero.} diff --git a/collects/scribblings/inside/inside.scrbl b/collects/scribblings/inside/inside.scrbl index ebb592260f..f0fbbdae24 100644 --- a/collects/scribblings/inside/inside.scrbl +++ b/collects/scribblings/inside/inside.scrbl @@ -2,19 +2,19 @@ @(require "utils.ss") @title[#:tag-prefix '(lib "scribblings/inside/inside.scrbl") - #:tag "top"]{@bold{Inside}: PLT Scheme C API} + #:tag "top"]{@bold{Inside}: Racket C API} @author["Matthew Flatt"] -This manual describes PLT Scheme's C interface, which allows the +This manual describes Racket's C interface, which allows the interpreter to be extended by a dynamically-loaded library, or embedded within an arbitrary C/C++ program. The manual assumes -familiarity with PLT Scheme as described in @|MzScheme|. +familiarity with Racket as described in @|MzScheme|. For an alternative way of dealing with foreign code, see @other-manual['(lib "scribblings/foreign/foreign.scrbl")], which -describes the @schememodname[scheme/foreign] module for manipulating -low-level libraries and structures purely through Scheme code. +describes the @racketmodname[ffi/unsafe] module for manipulating +low-level libraries and structures purely through Racket code. @table-of-contents[] diff --git a/collects/scribblings/inside/memory.scrbl b/collects/scribblings/inside/memory.scrbl index ff53885768..114e908e83 100644 --- a/collects/scribblings/inside/memory.scrbl +++ b/collects/scribblings/inside/memory.scrbl @@ -6,14 +6,14 @@ @section-index{memory} @section-index{garbage collection} -PLT Scheme uses both @cppi{malloc} and allocation functions provided +Racket uses both @cppi{malloc} and allocation functions provided by a garbage collector. Embedding/extension C/C++ code may use either allocation method, keeping in mind that pointers to garbage-collectable blocks in @cpp{malloc}ed memory are invisible (i.e., such pointers will not prevent the block from being garbage-collected). -PLT Scheme CGC uses a conservative garbage collector. This garbage +Racket CGC uses a conservative garbage collector. This garbage collector normally only recognizes pointers to the beginning of allocated objects. Thus, a pointer into the middle of a GC-allocated string will normally not keep the string from being collected. The @@ -22,7 +22,7 @@ registers may point to the middle of a collectable object. Thus, it is safe to loop over an array by incrementing a local pointer variable. -PLT Scheme 3m uses a precise garbage collector that moves objects +Racket 3m uses a precise garbage collector that moves objects during collection, in which case the C code must be instrumented to expose local pointer bindings to the collector, and to provide tracing procedures for (tagged) records containing pointers. This @@ -74,8 +74,8 @@ The basic collector allocation functions are: ] -@index['("globals" "in extension code")]{If} a PLT Scheme extension -stores Scheme pointers in a global or static variable, then that +@index['("globals" "in extension code")]{If} a Racket extension +stores Racket pointers in a global or static variable, then that variable must be registered with @cppi{scheme_register_extension_global}; this makes the pointer visible to the garbage collector. Registered variables need not @@ -98,8 +98,8 @@ Collectable memory can be temporarily locked from collection by using the reference-counting function @cppi{scheme_dont_gc_ptr}. Under 3m, such locking does not prevent the object from being moved. -Garbage collection can occur during any call into Scheme or its -allocator, on anytime that Scheme has control, except during functions +Garbage collection can occur during any call into Racket or its +allocator, on anytime that Racket has control, except during functions that are documented otherwise. The predicate and accessor macros listed in @secref["im:stdtypes"] never trigger a collection. @@ -115,7 +115,7 @@ content of a word registered as a pointer must contain either into an object allocated by @cpp{scheme_malloc_allow_interior}, a pointer to an object currently allocated by another memory manager (and therefore not into a block that is currently managed by the -collector), or a pointer to an odd-numbered address (e.g., a Scheme +collector), or a pointer to an odd-numbered address (e.g., a Racket fixnum). Pointers are registered in three different ways: @@ -158,7 +158,7 @@ retaining such a pointer can lead to a crash. As explained in @secref["im:values+types"], the @cpp{scheme_make_type} function can be used to obtain a new tag for a new type of object. These new types are in relatively short supply for 3m; the maximum tag -is 255, and Scheme itself uses nearly 200. +is 255, and Racket itself uses nearly 200. After allocating a new tag in 3m (and before creating instances of the tag), a @defterm{size procedure}, a @defterm{mark procedure}, and a @@ -434,7 +434,7 @@ is not defined, so the macros can be placed into code to be compiled for both conservative and precise collection. The @cpp{MZ_GC_REG} and @cpp{MZ_GC_UNREG} macros must never be -used in an OS thread other than Scheme's thread. +used in an OS thread other than Racket's thread. @; - - - - - - - - - - - - - - - - - - - - - - - - @@ -700,7 +700,7 @@ Frees memory allocated with @cpp{scheme_malloc_code}.} [void* ptr] [long size])]{ -Registers an extension's global variable that can contain Scheme +Registers an extension's global variable that can contain Racket pointers. The address of the global is given in @var{ptr}, and its size in bytes in @var{size}.In addition to global variables, this function can be used to register any permanent memory that the @@ -788,7 +788,7 @@ in the stack than @cpp{dummy}. To avoid these problems, use Like @cpp{scheme_set_stack_base}, except for the extra @var{stack_end} argument. If @var{stack_end} is non-@cpp{NULL}, then -it corresponds to a point of C-stack growth after which Scheme +it corresponds to a point of C-stack growth after which Racket should attempt to handle stack overflow. The @var{stack_end} argument should not correspond to the actual stack end, since detecting stack overflow may take a few frames, and since handling stack overflow @@ -895,9 +895,9 @@ To remove an added finalizer, use @cpp{scheme_subtract_finalizer}.} Installs a ``will''-like finalizer, similar to @scheme[will-register]. Scheme finalizers are called one at a time, requiring the collector to prove that a value has become inaccessible again before calling - the next Scheme finalizer. Finalizers registered with + the next Racket finalizer. Finalizers registered with @cpp{scheme_register_finalizer} or @cpp{scheme_add_finalizer} are - not called until all Scheme finalizers have been exhausted. + not called until all Racket finalizers have been exhausted. See @cpp{scheme_register_finalizer}, above, for information about the arguments. diff --git a/collects/scribblings/inside/misc.scrbl b/collects/scribblings/inside/misc.scrbl index bf059ed553..d8c8db9aba 100644 --- a/collects/scribblings/inside/misc.scrbl +++ b/collects/scribblings/inside/misc.scrbl @@ -4,7 +4,7 @@ @title{Miscellaneous Utilities} The @cppi{MZSCHEME_VERSION} preprocessor macro is defined as a string -describing the version of Scheme. The @cppi{MZSCHEME_VERSION_MAJOR} +describing the version of Racket. The @cppi{MZSCHEME_VERSION_MAJOR} and @cppi{MZSCHEME_VERSION_MINOR} macros are defined as the major and minor version numbers, respectively. @@ -35,7 +35,7 @@ Like @cpp{scheme_equal}, but accepts an extra value for cycle tracking. This procedure is meant to be called by a procedure installed with @cpp{scheme_set_type_equality}.} -Returns 1 if the Scheme values are @scheme[equal?].} +Returns 1 if the Racket values are @scheme[equal?].} @function[(long scheme_equal_hash_key [Scheme_Object* obj])]{ @@ -150,13 +150,13 @@ The same as @scheme[namespace-require].} @function[(Scheme_Object* scheme_load [char* file])]{ -Loads the specified Scheme file, returning the value of the last +Loads the specified Racket file, returning the value of the last expression loaded, or @cpp{NULL} if the load fails.} @function[(Scheme_Object* scheme_load_extension [char* filename])]{ -Loads the specified Scheme extension file, returning the value provided +Loads the specified Racket extension file, returning the value provided by the extension's initialization function.} @function[(Scheme_Hash_Table* scheme_make_hash_table @@ -170,7 +170,7 @@ table hashes on a key's pointer address, while @cpp{SCHEME_hash_string} uses a key as a @cpp{char*} and hashes on the null-terminated string content. Since a hash table created with @cpp{SCHEME_hash_string} (instead of @cpp{SCHEME_hash_ptr}) does not -use a key as a Scheme value, it cannot be used from Scheme code. +use a key as a Racket value, it cannot be used from Racket code. Although the hash table interface uses the type @cpp{Scheme_Object*} for both keys and values, the table functions never inspect values, @@ -212,7 +212,7 @@ that will be encountered.} @function[(Scheme_Hash_Table* scheme_make_hash_table_equal)]{ Like @cpp{scheme_make_hash_table}, except that keys are treated as -Scheme values and hashed based on @scheme[equal?] instead of +Racket values and hashed based on @scheme[equal?] instead of @scheme[eq?].} @function[(void scheme_hash_set @@ -334,8 +334,8 @@ Returns the current process ``time'' in milliseconds, just like @function[(char* scheme_banner)]{ -Returns the string that is used as the Scheme startup banner.} +Returns the string that is used as the Racket startup banner.} @function[(char* scheme_version)]{ -Returns a string for the executing version of Scheme.} +Returns a string for the executing version of Racket.} diff --git a/collects/scribblings/inside/namespaces.scrbl b/collects/scribblings/inside/namespaces.scrbl index c97ba9a896..d1084ed161 100644 --- a/collects/scribblings/inside/namespaces.scrbl +++ b/collects/scribblings/inside/namespaces.scrbl @@ -3,17 +3,17 @@ @title[#:tag "im:env"]{Namespaces and Modules} -A Scheme namespace (a top-level environment) is represented by a value -of type @cppi{Scheme_Env*} --- which is also a Scheme value, castable +A Racket namespace (a top-level environment) is represented by a value +of type @cppi{Scheme_Env*} --- which is also a Racket value, castable to @cpp{Scheme_Object*}. Calling @cppi{scheme_basic_env} returns a -namespace that includes all of Scheme's standard global procedures +namespace that includes all of Racket's standard global procedures and syntax. The @cpp{scheme_basic_env} function must be called once by an -embedding program, before any other PLT Scheme function is called +embedding program, before any other Racket function is called (except @cpp{scheme_make_param}), but @cpp{scheme_main_setup} automatically calls @cpp{scheme_basic_env}. The returned namespace is -the initial current namespace for the main Scheme thread. Scheme +the initial current namespace for the main Racket thread. Racket extensions cannot call @cpp{scheme_basic_env}. The current thread's current namespace is available from @@ -22,7 +22,7 @@ The current thread's current namespace is available from New values can be added as @as-index{globals} in a namespace using @cppi{scheme_add_global}. The @cppi{scheme_lookup_global} function -takes a Scheme symbol and returns the global value for that name, or +takes a Racket symbol and returns the global value for that name, or @cpp{NULL} if the symbol is undefined. A @as-index{module}'s set of top-level bindings is implemented using @@ -37,8 +37,8 @@ module files). After installing variables into the module with to make the module declaration available. All defined variables are exported from the primitive module. -The Scheme @indexed-scheme[#%variable-reference] form produces a value -that is opaque to Scheme code. Use @cpp{SCHEME_PTR_VAL} on the result +The Racket @indexed-scheme[#%variable-reference] form produces a value +that is opaque to Racket code. Use @cpp{SCHEME_PTR_VAL} on the result of @scheme[#%variable-reference] to obtain the same kind of value as returned by @cpp{scheme_global_bucket} (i.e., a bucket containing the variable's value, or @cpp{NULL} if the variable is not yet defined). @@ -95,7 +95,7 @@ The @cppi{Scheme_Bucket} structure is defined as: Like @cpp{scheme_global_bucket}, but finds a variable in a module. The @var{mod} and @var{symbol} arguments are as for - @scheme[dynamic-require] in Scheme. The @var{pos} argument should be + @scheme[dynamic-require] in Racket. The @var{pos} argument should be @cpp{-1} always. The @var{env} argument represents the namespace in which the module is declared.} diff --git a/collects/scribblings/inside/numbers.scrbl b/collects/scribblings/inside/numbers.scrbl index 8a93a2afbf..fcb2a2f89b 100644 --- a/collects/scribblings/inside/numbers.scrbl +++ b/collects/scribblings/inside/numbers.scrbl @@ -3,9 +3,9 @@ @title{Bignums, Rationals, and Complex Numbers} -Scheme supports integers of an arbitrary magnitude; when an integer +Racket supports integers of an arbitrary magnitude; when an integer cannot be represented as a fixnum (i.e., 30 or 62 bits plus a sign -bit), then it is represented by the Scheme type +bit), then it is represented by the Racket type @cppi{scheme_bignum_type}. There is no overlap in integer values represented by fixnums and bignums. @@ -60,7 +60,7 @@ unspecified accuracy.} @function[(float scheme_bignum_to_float [Scheme_Object* n])]{ -If PLT Scheme is not compiled with single-precision floats, this procedure +If Racket is not compiled with single-precision floats, this procedure is actually a macro alias for @cpp{scheme_bignum_to_double}.} @function[(Scheme_Object* scheme_bignum_from_double @@ -72,7 +72,7 @@ number @var{d}. The conversion accuracy is reasonable but unspecified.} @function[(Scheme_Object* scheme_bignum_from_float [float f])]{ -If PLT Scheme is not compiled with single-precision floats, this procedure +If Racket is not compiled with single-precision floats, this procedure is actually a macro alias for @cpp{scheme_bignum_from_double}.} @function[(char* scheme_bignum_to_string @@ -121,7 +121,7 @@ Converts the rational @var{n} to a @cpp{double}.} @function[(float scheme_rational_to_float [Scheme_Object* n])]{ -If PLT Scheme is not compiled with single-precision floats, this procedure +If Racket is not compiled with single-precision floats, this procedure is actually a macro alias for @cpp{scheme_rational_to_double}.} @function[(Scheme_Object* scheme_rational_numerator @@ -142,7 +142,7 @@ Converts the given @cpp{double} into a maximally-precise rational.} @function[(Scheme_Object* scheme_rational_from_float [float d])]{ -If PLT Scheme is not compiled with single-precision floats, this procedure +If Racket is not compiled with single-precision floats, this procedure is actually a macro alias for @cpp{scheme_rational_from_double}.} @function[(Scheme_Object* scheme_make_complex diff --git a/collects/scribblings/inside/overview.scrbl b/collects/scribblings/inside/overview.scrbl index e02bf2f0f9..f758a5d5c9 100644 --- a/collects/scribblings/inside/overview.scrbl +++ b/collects/scribblings/inside/overview.scrbl @@ -3,21 +3,31 @@ @title[#:tag "overview"]{Overview} +@section{``Scheme'' versus ``Racket''} + +The old name for Racket was ``PLT Scheme,'' and the core compiler and +run-time system used to be called ``MzScheme.'' The old names are +entrenched in Racket internals, to the point that most C bindings +defined in this manual start with @cpp{scheme_}. They all should be +renamed to start @cpp{racket_}. + +@; ---------------------------------------------------------------------- + @section{CGC versus 3m} -Before mixing any C code with MzScheme, first decide whether to use -the @bold{3m} variant of PLT Scheme, the @bold{CGC} variant of PLT -Scheme, or both: +Before mixing any C code with Racket, first decide whether to use the +@bold{3m} variant of Racket, the @bold{CGC} variant of Racket, or +both: @itemize[ -@item{@bold{@as-index{3m}} : the main variant of PLT Scheme, which +@item{@bold{@as-index{3m}} : the main variant of Racket, which uses @defterm{precise} garbage collection instead of conservative garbage collection, and it may move objects in memory during a collection.} -@item{@bold{@as-index{CGC}} : the original variant of PLT Scheme, - where memory management depends on a @defterm{conservative} garbage +@item{@bold{@as-index{CGC}} : the original variant of Racket, where + memory management depends on a @defterm{conservative} garbage collector. The conservative garbage collector can automatically find references to managed values from C local variables and (on some platforms) static variables.} @@ -29,9 +39,9 @@ At the C level, working with CGC can be much easier than working with @; ---------------------------------------------------------------------- -@section{Writing MzScheme Extensions} +@section{Writing Racket Extensions} -@section-index["extending MzScheme"] +@section-index["extending Racket"] The process of creating an extension for 3m or CGC is essentially the same, but the process for 3m is most easily understood as a variant of @@ -40,41 +50,41 @@ the process for CGC. @subsection{CGC Extensions} -To write a C/C++-based extension for PLT Scheme CGC, follow these +To write a C/C++-based extension for Racket CGC, follow these steps: @itemize[ - @item{@index['("header files")]{For} each C/C++ file that uses PLT - Scheme library functions, @cpp{#include} the file + @item{@index['("header files")]{For} each C/C++ file that uses + Racket library functions, @cpp{#include} the file @as-index{@filepath{escheme.h}}. - This file is distributed with the PLT software in an - @filepath{include} directory, but if @|mzc| is used to compile, this - path is found automatically.} + This file is distributed with the Racket software in an + @filepath{include} directory, but if @|mzc| is used to + compile, this path is found automatically.} @item{Define the C function @cppi{scheme_initialize}, which takes a @cpp{Scheme_Env*} namespace (see @secref["im:env"]) and returns a - @cpp{Scheme_Object*} Scheme value. + @cpp{Scheme_Object*} Racket value. This initialization function can install new global primitive procedures or other values into the namespace, or it can simply - return a Scheme value. The initialization function is called when the - extension is loaded with @scheme[load-extension] (the first time); + return a Racket value. The initialization function is called when the + extension is loaded with @racket[load-extension] (the first time); the return value from @cpp{scheme_initialize} is used as the return - value for @scheme[load-extension]. The namespace provided to + value for @racket[load-extension]. The namespace provided to @cpp{scheme_initialize} is the current namespace when - @scheme[load-extension] is called.} + @racket[load-extension] is called.} @item{Define the C function @cppi{scheme_reload}, which has the same arguments and return type as @cpp{scheme_initialize}. - This function is called if @scheme[load-extension] is called a second + This function is called if @racket[load-extension] is called a second time (or more times) for an extension. Like @cpp{scheme_initialize}, the return value from this function is the return value for - @scheme[load-extension].} + @racket[load-extension].} @item{Define the C function @cppi{scheme_module_name}, which takes @@ -84,7 +94,7 @@ steps: The function should return a symbol when the effect of calling @cpp{scheme_initialize} and @cpp{scheme_reload} is only to declare a module with the returned name. This function is called when the - extension is loaded to satisfy a @scheme[require] declaration. + extension is loaded to satisfy a @racket[require] declaration. The @cpp{scheme_module_name} function may be called before @cpp{scheme_initialize} and @cpp{scheme_reload}, after those @@ -95,7 +105,7 @@ steps: @item{Compile the extension C/C++ files to create platform-specific object files. - The @as-index{@|mzc|} compiler, which is distributed with PLT Scheme, + The @as-index{@|mzc|} compiler, which is distributed with Racket, compiles plain C files when the @as-index{@DFlag{cc}} flag is specified. More precisely, @|mzc| does not compile the files itself, but it locates a C compiler on the system and launches it with the @@ -104,7 +114,7 @@ steps: compiler or @exec{gcc} in the path, or a Mac OS X system with Apple's developer tools installed, then using @|mzc| is typically easier than working with the C compiler directly. Use the @as-index{@DFlag{cgc}} - flag to indicate that the build is for use with PLT Scheme CGC.} + flag to indicate that the build is for use with Racket CGC.} @item{Link the extension C/C++ files with @@ -115,50 +125,50 @@ steps: The @filepath{mzdyn} object file is distributed in the installation's @filepath{lib} directory. For Windows, the object file is in a - compiler-specific sub-directory of @filepath{plt\lib}. + compiler-specific sub-directory of @filepath{racket\lib}. The @|mzc| compiler links object files into an extension when the @as-index{@DFlag{ld}} flag is specified, automatically locating @filepath{mzdyn}. Again, use the @DFlag{cgc} flag with @|mzc|.} - @item{Load the shared object within Scheme using - @scheme[(load-extension _path)], where @scheme[_path] is the name of + @item{Load the shared object within Racket using + @racket[(load-extension _path)], where @racket[_path] is the name of the extension file generated in the previous step. Alternately, if the extension defines a module (i.e., @cpp{scheme_module_name} returns a symbol), then place the shared object in a special directory with a special name, so that it is - detected by the module loader when @scheme[require] is used. The + detected by the module loader when @racket[require] is used. The special directory is a platform-specific path that can be obtained by - evaluating @scheme[(build-path "compiled" "native" - (system-library-subpath))]; see @scheme[load/use-compiled] for more + evaluating @racket[(build-path "compiled" "native" + (system-library-subpath))]; see @racket[load/use-compiled] for more information. For example, if the shared object's name is - @filepath{example_ss.dll}, then @scheme[(require "example.ss")] will - be redirected to @filepath{example_ss.dll} if the latter is placed in - the sub-directory @scheme[(build-path "compiled" "native" - (system-library-subpath))] and if @filepath{example.ss} does not + @filepath{example_rkt.dll}, then @racket[(require "example.rkt")] will + be redirected to @filepath{example_rkt.dll} if the latter is placed in + the sub-directory @racket[(build-path "compiled" "native" + (system-library-subpath))] and if @filepath{example.rkt} does not exist or has an earlier timestamp. - Note that @scheme[(load-extension _path)] within a @scheme[module] + Note that @racket[(load-extension _path)] within a @racket[module] does @italic{not} introduce the extension's definitions into the - module, because @scheme[load-extension] is a run-time operation. To + module, because @racket[load-extension] is a run-time operation. To introduce an extension's bindings into a module, make sure that the extension defines a module, put the extension in the platform-specific location as described above, and use - @scheme[require].} + @racket[require].} ] -@index['("allocation")]{@bold{IMPORTANT:}} With PLT Scheme CGC, Scheme +@index['("allocation")]{@bold{IMPORTANT:}} With Racket CGC, Racket values are garbage collected using a conservative garbage collector, -so pointers to Scheme objects can be kept in registers, stack +so pointers to Racket objects can be kept in registers, stack variables, or structures allocated with @cppi{scheme_malloc}. However, static variables that contain pointers to collectable memory must be registered using @cppi{scheme_register_extension_global} (see @secref["im:memoryalloc"]). As an example, the following C code defines an extension that returns -@scheme["hello world"] when it is loaded: +@racket["hello world"] when it is loaded: @verbatim[#:indent 2]{ #include "escheme.h" @@ -176,18 +186,18 @@ As an example, the following C code defines an extension that returns Assuming that this code is in the file @filepath{hw.c}, the extension is compiled under Unix with the following two commands: -@commandline{mzc --cgc --cc hw.c} -@commandline{mzc --cgc --ld hw.so hw.o} +@commandline{raco ctool --cgc --cc hw.c} +@commandline{raco ctool --cgc --ld hw.so hw.o} (Note that the @DFlag{cgc}, @DFlag{cc}, and @DFlag{ld} flags are each prefixed by two dashes, not one.) -The @filepath{collects/mzscheme/examples} directory in the PLT +The @filepath{collects/mzscheme/examples} directory in the Racket distribution contains additional examples. @subsection{3m Extensions} -To build an extension to work with PLT Scheme 3m, the CGC instructions +To build an extension to work with Racket 3m, the CGC instructions must be extended as follows: @itemize[ @@ -213,12 +223,12 @@ must be extended as follows: For a relatively simple extension @filepath{hw.c}, the extension is compiled under Unix for 3m with the following three commands: -@commandline{mzc --xform hw.c} -@commandline{mzc --3m --cc hw.3m.c} -@commandline{mzc --3m --ld hw.so hw.o} +@commandline{raco ctool --xform hw.c} +@commandline{raco ctool --3m --cc hw.3m.c} +@commandline{raco ctool --3m --ld hw.so hw.o} Some examples in @filepath{collects/mzscheme/examples} work with -MzScheme3m in this way. A few examples are manually instrumented, in +Racket 3m in this way. A few examples are manually instrumented, in which case the @DFlag{xform} step should be skipped. @subsection{Declaring a Module in an Extension} @@ -228,7 +238,7 @@ To create an extension that behaves as a module, return a symbol from @cpp{scheme_rename} declare a module using @cpp{scheme_primitive_module}. For example, the following extension implements a module named -@scheme[hello] that exports a binding @scheme[greeting]: +@racket[hello] that exports a binding @racket[greeting]: @verbatim[#:indent 2]{ #include "escheme.h" @@ -253,96 +263,96 @@ For example, the following extension implements a module named } } -This extension could be compiled for 3m on Mac OS X for i386, for +This extension could be compiled for 3m on i386 Linux, for example, using the following sequence of @exec{mzc} commands: -@commandline{mzc --xform hi.c} -@commandline{mzc --3m --cc hi.3m.c} -@commandline{mkdir -p compiled/native/i386-macosx/3m} -@commandline{mzc --3m --ld compiled/native/i386-macosx/3m/hi_ss.dylib hi_3m.o} +@commandline{raco ctool --xform hi.c} +@commandline{raco ctool --3m --cc hi.3m.c} +@commandline{mkdir -p compiled/native/i386-linux/3m} +@commandline{raco ctool --3m --ld compiled/native/i386-linux/3m/hi_rkt.so hi_3m.o} The resulting module can be loaded with -@schemeblock[(require "hi.ss")] +@racketblock[(require "hi.rkt")] @; ---------------------------------------------------------------------- -@section[#:tag "embedding"]{Embedding MzScheme into a Program} +@section[#:tag "embedding"]{Embedding Racket into a Program} -@section-index["embedding MzScheme"] +@section-index["embedding Racket"] -Like creating extensions, the embedding process for PLT Scheme CGC or -PLT Scheme 3m is essentially the same, but the process for PLT Scheme +Like creating extensions, the embedding process for Racket CGC or +Racket 3m is essentially the same, but the process for Racket 3m is most easily understood as a variant of the process for -PLT Scheme CGC. +Racket CGC. @subsection{CGC Embedding} -To embed PLT Scheme CGC in a program, follow these steps: +To embed Racket CGC in a program, follow these steps: @itemize[ - @item{Locate or build the PLT Scheme CGC libraries. Since the + @item{Locate or build the Racket CGC libraries. Since the standard distribution provides 3m libraries, only, you will most likely have to build from source. - Under Unix, the libraries are @as-index{@filepath{libmzscheme.a}} + Under Unix, the libraries are @as-index{@filepath{libracket.a}} and @as-index{@filepath{libmzgc.a}} (or - @as-index{@filepath{libmzscheme.so}} and + @as-index{@filepath{libracket.so}} and @as-index{@filepath{libmzgc.so}} for a dynamic-library build, with - @as-index{@filepath{libmzscheme.la}} and + @as-index{@filepath{libracket.la}} and @as-index{@filepath{libmzgc.la}} files for use with @exec{libtool}). Building from source and installing places the libraries into the installation's @filepath{lib} directory. Be sure to build the CGC variant, since the default is 3m. Under Windows, stub libraries for use with Microsoft tools are - @filepath{libmzsch@italic{x}.lib} and + @filepath{libracket@italic{x}.lib} and @filepath{libmzgc@italic{x}.lib} (where @italic{x} represents the version number) are in a compiler-specific directory in - @filepath{plt\lib}. These libraries identify the bindings that are - provided by @filepath{libmzsch@italic{x}.dll} and + @filepath{racket\lib}. These libraries identify the bindings that are + provided by @filepath{libracket@italic{x}.dll} and @filepath{libmzgc@italic{x}.dll} --- which are typically installed - in @filepath{plt\lib}. When linking with Cygwin, link to - @filepath{libmzsch@italic{x}.dll} and + in @filepath{racket\lib}. When linking with Cygwin, link to + @filepath{libracket@italic{x}.dll} and @filepath{libmzgc@italic{x}.dll} directly. At run time, either - @filepath{libmzsch@italic{x}.dll} and + @filepath{libracket@italic{x}.dll} and @filepath{libmzgc@italic{x}.dll} must be moved to a location in the standard DLL search path, or your embedding application must ``delayload'' link the DLLs and explicitly load them before - use. (@filepath{MzScheme.exe} and @filepath{MrEd.exe} use the latter + use. (@filepath{Racket.exe} and @filepath{MrEd.exe} use the latter strategy.) Under Mac OS X, dynamic libraries are provided by the - @filepath{PLT_MzScheme} framework, which is typically installed in + @filepath{Racket} framework, which is typically installed in @filepath{lib} sub-directory of the installation. Supply - @exec{-framework PLT_MzScheme} to @exec{gcc} when linking, along + @exec{-framework Racket} to @exec{gcc} when linking, along with @exec{-F} and a path to the @filepath{lib} directory. Beware that CGC and 3m libraries are installed as different versions within a single framework, and installation marks one version or the other as the default (by setting symbolic links); install only CGC to simplify accessing the CGC version within the framework. At run - time, either @filepath{PLT_MzScheme.framework} must be moved to a + time, either @filepath{Racket.framework} must be moved to a location in the standard framework search path, or your embedding executable must provide a specific path to the framework (possibly an executable-relative path using the Mach-O @tt["@executable_path"] prefix).} - @item{For each C/C++ file that uses MzScheme library functions, + @item{For each C/C++ file that uses Racket library functions, @cpp{#include} the file @as-index{@filepath{scheme.h}}. The C preprocessor symbol @cppi{SCHEME_DIRECT_EMBEDDED} is defined as @cpp{1} when @filepath{scheme.h} is @cpp{#include}d, or as @cpp{0} when @filepath{escheme.h} is @cpp{#include}d. - The @filepath{scheme.h} file is distributed with the PLT software in + The @filepath{scheme.h} file is distributed with the Racket software in the installation's @filepath{include} directory. Building and installing from source also places this file in the installation's @filepath{include} directory.} @item{Start your main program through the @cpp{scheme_main_setup} (or @cpp{scheme_main_stack_setup}) trampoline, and put all uses of - MzScheme functions inside the function passed to + Racket functions inside the function passed to @cpp{scheme_main_setup}. The @cpp{scheme_main_setup} function registers the current C stack location with the memory manager. It also creates the initial namespace @cpp{Scheme_Env*} by calling @@ -353,11 +363,11 @@ To embed PLT Scheme CGC in a program, follow these steps: @item{Configure the namespace by adding module declarations. The initial namespace contains declarations only for a few primitive - modules, such as @scheme['#%kernel], and no bindings are imported + modules, such as @racket['#%kernel], and no bindings are imported into the top-level environment. - To embed a module like @schememodname[scheme/base] (along with all - its dependencies), use @exec{mzc --c-mods}, which generates a C file + To embed a module like @racketmodname[racket/base] (along with all + its dependencies), use @exec{raco ctool --c-mods}, which generates a C file that contains modules in bytecode form as encapsulated in a static array. The generated C file defines a @cppi{declare_modules} function that takes a @cpp{Scheme_Env*}, installs the modules into @@ -368,7 +378,7 @@ To embed PLT Scheme CGC in a program, follow these steps: @cpp{scheme_init_collection_paths} to configure and install a path for finding modules at run time.} - @item{Access Scheme through @cppi{scheme_dynamic_require}, + @item{Access Racket through @cppi{scheme_dynamic_require}, @cppi{scheme_load}, @cppi{scheme_eval}, and/or other functions described in this manual. @@ -379,13 +389,13 @@ To embed PLT Scheme CGC in a program, follow these steps: certain privileged operations, such as installing a @|PLaneT| package.} - @item{Compile the program and link it with the MzScheme libraries.} + @item{Compile the program and link it with the Racket libraries.} ] -@index['("allocation")]{With} PLT Scheme CGC, Scheme values are +@index['("allocation")]{With} Racket CGC, Racket values are garbage collected using a conservative garbage collector, so pointers -to Scheme objects can be kept in registers, stack variables, or +to Racket objects can be kept in registers, stack variables, or structures allocated with @cppi{scheme_malloc}. In an embedding application on some platforms, static variables are also automatically registered as roots for garbage collection (but see notes below @@ -393,12 +403,12 @@ specific to Mac OS X and Windows). For example, the following is a simple embedding program which evaluates all expressions provided on the command line and displays -the results, then runs a @scheme[read]-@scheme[eval]-@scheme[print] +the results, then runs a @racket[read]-@racket[eval]-@racket[print] loop. Run -@commandline{mzc --c-mods base.c ++lib scheme/base} +@commandline{raco ctool --c-mods base.c ++lib racket/base} -to generate @filepath{base.c}, which encapsulates @scheme[scheme/base] +to generate @filepath{base.c}, which encapsulates @racket[racket/base] and all of its transitive imports (so that they need not be found separately a run time). @@ -416,7 +426,7 @@ static int run(Scheme_Env *e, int argc, char *argv[]) /* Declare embedded modules in "base.c": */ declare_modules(e); - scheme_namespace_require(scheme_intern_symbol("scheme/base")); + scheme_namespace_require(scheme_intern_symbol("racket/base")); curout = scheme_get_param(scheme_current_config(), MZCONFIG_OUTPUT_PORT); @@ -433,7 +443,7 @@ static int run(Scheme_Env *e, int argc, char *argv[]) scheme_display(v, curout); scheme_display(scheme_make_char('\n'), curout); /* read-eval-print loop, uses initial Scheme_Env: */ - a[0] = scheme_intern_symbol("scheme/base"); + a[0] = scheme_intern_symbol("racket/base"); a[1] = scheme_intern_symbol("read-eval-print-loop"); scheme_apply(scheme_dynamic_require(2, a), 0, NULL); scheme_current_thread->error_buf = save; @@ -448,7 +458,7 @@ int main(int argc, char *argv[]) } } -Under Mac OS X, or under Windows when MzScheme is compiled to a DLL +Under Mac OS X, or under Windows when Racket is compiled to a DLL using Cygwin, the garbage collector cannot find static variables automatically. In that case, @cppi{scheme_main_setup} must be called with a non-zero first argument. @@ -467,7 +477,7 @@ pointer. For example, if @cpp{curout} above is made @cpp{static}, then @cpp{MZ_REGISTER_STATIC(curout)} should be inserted before the call to @cpp{scheme_get_param}. -When building an embedded MzSchemeCGC to use SenoraGC (SGC) instead of +When building an embedded Racket CGC to use SenoraGC (SGC) instead of the default collector, @cpp{scheme_main_setup} must be called with a non-zero first argument. See @secref["im:memoryalloc"] for more information. @@ -475,7 +485,7 @@ information. @subsection{3m Embedding} -MzScheme3m can be embedded mostly the same as MzScheme, as long as the +Racket 3m can be embedded mostly the same as Racket, as long as the embedding program cooperates with the precise garbage collector as described in @secref["im:3m"]. @@ -489,31 +499,31 @@ In addition, some library details are different: @itemize[ @item{Under Unix, the library is just - @as-index{@filepath{libmzscheme3m.a}} (or - @as-index{@filepath{libmzscheme3m.so}} for a dynamic-library build, - with @as-index{@filepath{libmzscheme3m.la}} for use with + @as-index{@filepath{libracket3m.a}} (or + @as-index{@filepath{libracket3m.so}} for a dynamic-library build, + with @as-index{@filepath{libracket3m.la}} for use with @exec{libtool}). There is no separate library for 3m analogous to CGC's @filepath{libmzgc.a}.} @item{Under Windows, the stub library for use with Microsoft tools is - @filepath{libmzsch3m@italic{x}.lib} (where @italic{x} represents the + @filepath{libracket3m@italic{x}.lib} (where @italic{x} represents the version number). This library identifies the bindings that are - provided by @filepath{libmzsch3m@italic{x}.dll}. There is no + provided by @filepath{libracket3m@italic{x}.dll}. There is no separate library for 3m analogous to CGC's @filepath{libmzgc@italic{x}.lib}.} @item{Under Mac OS X, 3m dynamic libraries are provided by the - @filepath{PLT_MzScheme} framework, just as for CGC, but as a version + @filepath{Racket} framework, just as for CGC, but as a version suffixed with @filepath{_3m}.} ] -For MzScheme3m, an embedding application must call @cpp{scheme_main_setup} +For Racket 3m, an embedding application must call @cpp{scheme_main_setup} with a non-zero first argument. The simple embedding program from the previous section can be -processed by @exec{mzc --xform}, then compiled and linked with -MzScheme3m. Alternately, the source code can be extended to work with +processed by @exec{raco ctool --xform}, then compiled and linked with +Racket 3m. Alternately, the source code can be extended to work with either CGC or 3m depending on whether @cpp{MZ_PRECISE_GC} is defined on the compiler's command line: @@ -541,7 +551,7 @@ static int run(Scheme_Env *e, int argc, char *argv[]) declare_modules(e); - v = scheme_intern_symbol("scheme/base"); + v = scheme_intern_symbol("racket/base"); scheme_namespace_require(v); config = scheme_current_config(); @@ -559,7 +569,7 @@ static int run(Scheme_Env *e, int argc, char *argv[]) v = scheme_make_char('\n'); scheme_display(v, curout); /* read-eval-print loop, uses initial Scheme_Env: */ - a[0] = scheme_intern_symbol("scheme/base"); + a[0] = scheme_intern_symbol("racket/base"); a[1] = scheme_intern_symbol("read-eval-print-loop"); v = scheme_dynamic_require(2, a); scheme_apply(v, 0, NULL); @@ -586,22 +596,22 @@ and when all temporary values are put into variables. @; ---------------------------------------------------------------------- -@section{MzScheme and Threads} +@section{Racket and Threads} -MzScheme implements threads for Scheme programs without aid from the -operating system, so that MzScheme threads are cooperative from the -perspective of C code. Under Unix, stand-alone MzScheme uses a single +Racket implements threads for Racket programs without aid from the +operating system, so that Racket threads are cooperative from the +perspective of C code. Under Unix, stand-alone Racket uses a single OS-implemented thread. Under Windows and Mac OS X, stand-alone -MzScheme uses a few private OS-implemented threads for background +Racket uses a few private OS-implemented threads for background tasks, but these OS-implemented threads are never exposed by the -MzScheme API. +Racket API. -In an embedding application, MzScheme can co-exist with additional +In an embedding application, Racket can co-exist with additional OS-implemented threads, but the additional OS threads must not call any @cpp{scheme_} function. Only the OS thread that originally calls @cpp{scheme_basic_env} can call @cpp{scheme_} functions. (This restriction is stronger than saying all calls must be serialized -across threads. MzScheme relies on properties of specific threads to +across threads. Racket relies on properties of specific threads to avoid stack overflow and garbage collection.) When @cpp{scheme_basic_env} is called a second time to reset the interpreter, it can be called in an OS thread that is different from @@ -609,19 +619,19 @@ the original call to @cpp{scheme_basic_env}. Thereafter, all calls to @cpp{scheme_} functions must originate from the new thread. See @secref["threads"] for more information about threads, including -the possible effects of MzScheme's thread implementation on extension +the possible effects of Racket's thread implementation on extension and embedding C code. @; ---------------------------------------------------------------------- -@section[#:tag "im:unicode"]{MzScheme, Unicode, Characters, and Strings} +@section[#:tag "im:unicode"]{Racket, Unicode, Characters, and Strings} -A character in MzScheme is a Unicode code point. In C, a character +A character in Racket is a Unicode code point. In C, a character value has type @cppi{mzchar}, which is an alias for @cpp{unsigned} --- -which is, in turn, 4 bytes for a properly compiled MzScheme. Thus, a +which is, in turn, 4 bytes for a properly compiled Racket. Thus, a @cpp{mzchar*} string is effectively a UCS-4 string. -Only a few MzScheme functions use @cpp{mzchar*}. Instead, most +Only a few Racket functions use @cpp{mzchar*}. Instead, most functions accept @cpp{char*} strings. When such byte strings are to be used as a character strings, they are interpreted as UTF-8 encodings. A plain ASCII string is always acceptable in such cases, @@ -633,7 +643,7 @@ See also @secref["im:strings"] and @secref["im:encodings"]. @section[#:tag "im:intsize"]{Integers} -MzScheme expects to be compiled in a mode where @cppi{short} is a +Racket expects to be compiled in a mode where @cppi{short} is a 16-bit integer, @cppi{int} is a 32-bit integer, and @cppi{long} has the same number of bits as @cpp{void*}. The @cppi{mzlonglong} type has 64 bits for compilers that support a 64-bit integer type, otherwise it diff --git a/collects/scribblings/inside/ports.scrbl b/collects/scribblings/inside/ports.scrbl index 4c8be45ac3..42f648d248 100644 --- a/collects/scribblings/inside/ports.scrbl +++ b/collects/scribblings/inside/ports.scrbl @@ -3,7 +3,7 @@ @title{Ports and the Filesystem} -Ports are represented as Scheme values with the types +Ports are represented as Racket values with the types @cppi{scheme_input_port_type} and @cppi{scheme_output_port_type}. The function @cppi{scheme_read} takes an input port value and returns the next S-expression from the port. The function @cppi{scheme_write} @@ -23,7 +23,7 @@ The contents of a string output port are obtained with Custom ports, with arbitrary read/write handlers, are created with @cppi{scheme_make_input_port} and @cppi{scheme_make_output_port}. -When opening a file for any reason using a name provided from Scheme, +When opening a file for any reason using a name provided from Racket, use @cppi{scheme_expand_filename} to normalize the filename and resolve relative paths. @@ -50,7 +50,7 @@ Like @cpp{scheme_write}, but the printing is truncated to @var{n} bytes. [Scheme_Object* obj] [Scheme_Object* port])]{ -@scheme[display]s the Scheme value @var{obj} to the given output +@scheme[display]s the Racket value @var{obj} to the given output port.} @function[(void scheme_display_w_max @@ -119,7 +119,7 @@ without the non-blocking option.} [Scheme_Object* obj] [long* len])]{ -Prints the Scheme value @var{obj} using @scheme[write] to a newly +Prints the Racket value @var{obj} using @scheme[write] to a newly allocated string. If @var{len} is not @cpp{NULL}, @cpp{*@var{len}} is set to the length of the bytes string.} @@ -136,7 +136,7 @@ Like @cpp{scheme_write_to_string}, but the string is truncated to [Scheme_Object* obj] [long* len])]{ -Prints the Scheme value @var{obj} using @scheme[display] to a newly +Prints the Racket value @var{obj} using @scheme[display] to a newly allocated string. If @var{len} is not @cpp{NULL}, @cpp{*@var{len}} is set to the length of the string.} @@ -154,7 +154,7 @@ Like @cpp{scheme_display_to_string}, but the string is truncated to @function[(void scheme_debug_print [Scheme_Object* obj])]{ -Prints the Scheme value @var{obj} using @scheme[write] to the main +Prints the Racket value @var{obj} using @scheme[write] to the main thread's output port.} @function[(void scheme_flush_output @@ -423,7 +423,7 @@ The functions are as follows. in @var{unless} becomes ready before bytes can be read. In particular, @var{get_bytes_fun} should check the event in @var{unless} before taking any action, and it should check the - event in @var{unless} after any operation that may allow Scheme + event in @var{unless} after any operation that may allow Racket thread swaps. If the read must block, then it should unblock if the event in @var{unless} becomes ready. @@ -439,7 +439,7 @@ The functions are as follows. use @cpp{scheme_block_until_unless} instead of @cpp{scheme_block_until}. Finally, in blocking mode, @var{get_bytes_fun} must return after immediately reading data, - without allowing a Scheme thread swap.} + without allowing a Racket thread swap.} @subfunction[(long peek_bytes_fun [Scheme_Input_Port* port] @@ -652,7 +652,7 @@ Opens @var{filename} for reading. In an exception is raised, the [FILE* fp] [Scheme_Object* name])]{ -Creates a Scheme input file port from an ANSI C file pointer. The file +Creates a Racket input file port from an ANSI C file pointer. The file must never block on reads. The @var{name} argument is used as the port's name.} @@ -667,7 +667,7 @@ Opens @var{filename} for writing in @scheme['truncate/replace] mode. If @function[(Scheme_Object* scheme_make_file_output_port [FILE* fp])]{ -Creates a Scheme output file port from an ANSI C file pointer. The +Creates a Racket output file port from an ANSI C file pointer. The file must never block on writes.} @function[(Scheme_Object* scheme_make_fd_input_port @@ -676,7 +676,7 @@ Creates a Scheme output file port from an ANSI C file pointer. The [int regfile] [int win_textmode])]{ -Creates a Scheme input port for a file descriptor @var{fd}. Under +Creates a Racket input port for a file descriptor @var{fd}. Under Windows, @var{fd} can be a @cpp{HANDLE} for a stream, and it should never be a file descriptor from the C library or a WinSock socket. @@ -702,7 +702,7 @@ Instead of calling both @cpp{scheme_make_fd_input_port} and [int win_textmode] [int read_too])]{ -Creates a Scheme output port for a file descriptor @var{fd}. Under +Creates a Racket output port for a file descriptor @var{fd}. Under Windows, @var{fd} can be a @cpp{HANDLE} for a stream, and it should never be a file descriptor from the C library or a WinSock socket. @@ -729,7 +729,7 @@ If @var{read_too} is non-zero, the function produces multiple values [Scheme_Object** inp] [Scheme_Object** outp])]{ -Creates Scheme input and output ports for a TCP socket @var{s}. The +Creates Racket input and output ports for a TCP socket @var{s}. The @var{name} argument supplies the name for the ports. If @var{close} is non-zero, then the ports assume responsibility for closing the socket. The resulting ports are written to @var{inp} and @var{outp}.} @@ -737,13 +737,13 @@ Creates Scheme input and output ports for a TCP socket @var{s}. The @function[(Scheme_Object* scheme_make_byte_string_input_port [char* str])]{ -Creates a Scheme input port from a byte string; successive +Creates a Racket input port from a byte string; successive @scheme[read-char]s on the port return successive bytes in the string.} @function[(Scheme_Object* scheme_make_byte_string_output_port)]{ -Creates a Scheme output port; all writes to the port are kept in a byte string, +Creates a Racket output port; all writes to the port are kept in a byte string, which can be obtained with @cpp{scheme_get_byte_string_output}.} @function[(char* scheme_get_byte_string_output @@ -843,12 +843,12 @@ character string or a path value.} @function[(Scheme_Object* scheme_char_string_to_path [Scheme_Object* s])]{ -Converts a Scheme character string into a Scheme path value.} +Converts a Racket character string into a Racket path value.} @function[(Scheme_Object* scheme_path_to_char_string [Scheme_Object* s])]{ -Converts a Scheme path value into a Scheme character string.} +Converts a Racket path value into a Racket character string.} @function[(Scheme_Object* scheme_make_path [char* bytes])]{ @@ -923,7 +923,7 @@ no 0, then an exception is raised if the operation fails.} [int noexn])]{ Sets the current working directory according to the operating system. This -is separate from MzScheme's current directory parameter. +is separate from Racket's current directory parameter. If @var{noexn} is not 0, then an exception is raised if the operation fails.} @@ -935,7 +935,7 @@ fails.} [Scheme_Object** argv] [long* rlen])]{ -Creates a string like MzScheme's @scheme[format] procedure, using the +Creates a string like Racket's @scheme[format] procedure, using the format string @var{format} (of length @var{flen}) and the extra arguments specified in @var{argc} and @var{argv}. If @var{rlen} is not @cpp{NULL}, @cpp{*@var{rlen}} is filled with the length of the @@ -947,7 +947,7 @@ resulting string.} [int argc] [Scheme_Object** argv])]{ -Writes to the current output port like MzScheme's @scheme[printf] +Writes to the current output port like Racket's @scheme[printf] procedure, using the format string @var{format} (of length @var{flen}) and the extra arguments specified in @var{argc} and @var{argv}.} diff --git a/collects/scribblings/inside/procedures.scrbl b/collects/scribblings/inside/procedures.scrbl index bc07c8a5c6..c2d53983df 100644 --- a/collects/scribblings/inside/procedures.scrbl +++ b/collects/scribblings/inside/procedures.scrbl @@ -3,11 +3,11 @@ @title{Procedures} -A @defterm{primitive procedure} is a Scheme-callable procedure that is -implemented in C. Primitive procedures are created in Scheme with +A @defterm{primitive procedure} is a Racket-callable procedure that is +implemented in C. Primitive procedures are created in Racket with the function @cppi{scheme_make_prim_w_arity}, which takes a C function pointer, the name of the primitive, and information about the number -of Scheme arguments that it takes; it returns a Scheme procedure +of Racket arguments that it takes; it returns a Racket procedure value. The C function implementing the procedure must take two arguments: an @@ -15,7 +15,7 @@ integer that specifies the number of arguments passed to the procedure, and an array of @cpp{Scheme_Object*} arguments. The number of arguments passed to the function will be checked using the arity information. (The arity information provided to -@cpp{scheme_make_prim_w_arity} is also used for the Scheme +@cpp{scheme_make_prim_w_arity} is also used for the Racket @scheme[arity] procedure.) The procedure implementation is not allowed to mutate the input array of arguments; as an exception, the procedure can mutate the array if it is the same a the result of @@ -60,7 +60,7 @@ maximum number of arguments that can be supplied to the procedure, or -1 if the procedure can take arbitrarily many arguments. The @var{mina} and @var{maxa} values are used for automatically checking the argument count before the primitive is invoked, and also for the -Scheme @indexed-scheme[arity] procedure. The @var{name} argument is +Racket @indexed-scheme[arity] procedure. The @var{name} argument is used to report application arity errors at run-time.} @function[(Scheme_Object* scheme_make_folding_prim diff --git a/collects/scribblings/inside/structures.scrbl b/collects/scribblings/inside/structures.scrbl index 1d1924c8d5..81ce46ec55 100644 --- a/collects/scribblings/inside/structures.scrbl +++ b/collects/scribblings/inside/structures.scrbl @@ -3,7 +3,7 @@ @title{Structures} -A new Scheme structure type is created with +A new Racket structure type is created with @cppi{scheme_make_struct_type}. This creates the structure type, but does not generate the constructor, etc. procedures. The @cppi{scheme_make_struct_values} function takes a structure type and @@ -42,6 +42,10 @@ be restricted by passing any combination of these flags: @item{@cppi{SCHEME_STRUCT_GEN_SET} --- the field-independent mutator procedure value/name is returned.} + @item{@cppi{SCHEME_STRUCT_NO_MAKE_PREFIX} --- the constructor name + omits a @schemeidfont{make-} prefix, like @racket[struct] instead of + @racket[define-struct].} + ] When all values or names are returned, they are returned as an array @@ -87,7 +91,7 @@ Creates and returns an array of standard structure value name symbols. The @var{base_name} argument is used as the name of the structure type; it should be the same symbol passed to the associated call to @cpp{scheme_make_struct_type}. The @var{field_names} argument -is a (Scheme) list of field name symbols. The @var{flags} argument +is a (Racket) list of field name symbols. The @var{flags} argument specifies which names should be generated, and if @var{count_out} is not @cpp{NULL}, @var{count_out} is filled with the number of names returned in the array.} diff --git a/collects/scribblings/inside/threads.scrbl b/collects/scribblings/inside/threads.scrbl index 5094199ede..de2c444234 100644 --- a/collects/scribblings/inside/threads.scrbl +++ b/collects/scribblings/inside/threads.scrbl @@ -5,10 +5,10 @@ @title[#:tag "threads"]{Threads} The initializer function @cppi{scheme_basic_env} creates the main -Scheme thread; all other threads are created through calls to +Racket thread; all other threads are created through calls to @cppi{scheme_thread}. -Information about each internal Scheme thread is kept in a +Information about each internal Racket thread is kept in a @cppi{Scheme_Thread} structure. A pointer to the current thread's structure is available as @cppi{scheme_current_thread}. A @cpp{Scheme_Thread} structure includes the following fields: @@ -43,7 +43,7 @@ The last thread in the list is always the main thread. @section{Integration with Threads} -Scheme's threads can break external C code under two circumstances: +Racket's threads can break external C code under two circumstances: @itemize[ @@ -53,18 +53,18 @@ Scheme's threads can break external C code under two circumstances: pointer in the global variable, it may point to data that is not currently on the stack.} - @item{@italic{C functions that can invoke Scheme (and also be invoked - by Scheme) depend on strict function-call nesting.} For example, + @item{@italic{C functions that can invoke Racket (and also be invoked + by Racket) depend on strict function-call nesting.} For example, suppose a function F uses an internal stack, pushing items on to the stack on entry and popping the same items on exit. Suppose also that - F invokes Scheme to evaluate an expression. If the evaluation of + F invokes Racket to evaluate an expression. If the evaluation of this expression invokes F again in a new thread, but then returns to the first thread before completing the second F, then F's internal stack will be corrupted.} ] -If either of these circumstances occurs, Scheme will probably crash. +If either of these circumstances occurs, Racket will probably crash. @; ---------------------------------------------------------------------- @@ -72,8 +72,8 @@ If either of these circumstances occurs, Scheme will probably crash. @section[#:tag "usefuel"]{Allowing Thread Switches} C code that performs substantial or unbounded work should occasionally -call @cppi{SCHEME_USE_FUEL}---actually a macro---which allows Scheme -to swap in another Scheme thread to run, and to check for breaks on +call @cppi{SCHEME_USE_FUEL}---actually a macro---which allows Racket +to swap in another Racket thread to run, and to check for breaks on the current thread. In particular, if breaks are enabled, then @cpp{SCHEME_USE_FUEL} may trigger an exception. @@ -110,18 +110,18 @@ expression. @section[#:tag "threadblock"]{Blocking the Current Thread} Embedding or extension code sometimes needs to block, but blocking -should allow other Scheme threads to execute. To allow other threads +should allow other Racket threads to execute. To allow other threads to run, block using @cppi{scheme_block_until}. This procedure takes two functions: a polling function that tests whether the blocking operation can be completed, and a prepare-to-sleep function that sets -bits in @cpp{fd_set}s when Scheme decides to sleep (because all Scheme +bits in @cpp{fd_set}s when Racket decides to sleep (because all Racket threads are blocked). Under Windows, an ``@cpp{fd_set}'' can also accommodate OS-level semaphores or other handles via @cpp{scheme_add_fd_handle}. Since the functions passed to @cppi{scheme_block_until} are called by -the Scheme thread scheduler, they must never raise exceptions, call -@cpp{scheme_apply}, or trigger the evaluation of Scheme code in any +the Racket thread scheduler, they must never raise exceptions, call +@cpp{scheme_apply}, or trigger the evaluation of Racket code in any way. The @cpp{scheme_block_until} function itself may call the current exception handler, however, in reaction to a break (if breaks are enabled). @@ -133,8 +133,8 @@ polling and sleeping functions with @cppi{scheme_add_evt}, or register a semaphore accessor with @cppi{scheme_add_evt_through_sema}. The @cppi{scheme_signal_received} function can be called to wake up -Scheme when it is sleeping. In particular, calling -@cppi{scheme_signal_received} ensures that Scheme will poll all +Racket when it is sleeping. In particular, calling +@cppi{scheme_signal_received} ensures that Racket will poll all blocking synchronizations soon afterward. Furthermore, @cpp{scheme_signal_received} can be called from any OS-level thread. Thus, when no adequate prepare-to-sleep function can be implemented @@ -144,17 +144,17 @@ changes will ensure that a poll is issued. @; ---------------------------------------------------------------------- -@section[#:tag "threadtime"]{Threads in Embedded Scheme with Event Loops} +@section[#:tag "threadtime"]{Threads in Embedded Racket with Event Loops} -When Scheme is embedded in an application with an event-based model -(i.e., the execution of Scheme code in the main thread is repeatedly +When Racket is embedded in an application with an event-based model +(i.e., the execution of Racket code in the main thread is repeatedly triggered by external events until the application exits) special hooks must be set to ensure that non-main threads execute correctly. For example, during the execution in the main thread, a new thread may be created; the new thread may still be running when the main thread returns to the event loop, and it may be arbitrarily long before the main thread continues from the event loop. Under such -circumstances, the embedding program must explicitly allow Scheme to +circumstances, the embedding program must explicitly allow Racket to execute the non-main threads; this can be done by periodically calling the function @cppi{scheme_check_threads}. @@ -167,11 +167,11 @@ when thread-checking becomes necessary, and then with 0 when thread checking is no longer necessary. An embedding program can use this information to prevent unnecessary @cpp{scheme_check_threads} polling. -The below code illustrates how MrEd formerly set up +The below code illustrates how GRacket formerly set up @cpp{scheme_check_threads} polling using the wxWindows @cpp{wxTimer} class. (Any regular event-loop-based callback is appropriate.) The @cpp{scheme_notify_multithread} pointer is set to -@cpp{MrEdInstallThreadTimer}. (MrEd no longer work this way, however.) +@cpp{MrEdInstallThreadTimer}. (GRacket no longer work this way, however.) @verbatim[#:indent 2]{ class MrEdThreadTimer : public wxTimer @@ -208,15 +208,15 @@ class. (Any regular event-loop-based callback is appropriate.) The } } -An alternate architecture, which MrEd now uses, is to send the main +An alternate architecture, which GRacket now uses, is to send the main thread into a loop, which blocks until an event is ready to handle. -Scheme automatically takes care of running all threads, and it does so +Racket automatically takes care of running all threads, and it does so efficiently because the main thread blocks on a file descriptor, as explained in @secref["threadblock"]. @subsection[#:tag "blockednonmainel"]{Callbacks for Blocked Threads} -Scheme threads are sometimes blocked on file descriptors, such as an +Racket threads are sometimes blocked on file descriptors, such as an input file or the X event socket. Blocked non-main threads do not block the main thread, and therefore do not affect the event loop, so @cppi{scheme_check_threads} is sufficient to implement this case @@ -237,7 +237,7 @@ sets up callbacks on the specified file descriptors. When input is ready on any of those file descriptors, the callbacks are removed and @cpp{scheme_wake_up} is called. -For example, the X Windows version of MrEd formerly set +For example, the X Windows version of GRacket formerly set @cpp{scheme_wakeup_on_input} to this @cpp{MrEdNeedWakeup}: @verbatim[#:indent 2]{ @@ -319,15 +319,15 @@ For example, the X Windows version of MrEd formerly set @; ---------------------------------------------------------------------- -@section[#:tag "sleeping"]{Sleeping by Embedded Scheme} +@section[#:tag "sleeping"]{Sleeping by Embedded Racket} -When all Scheme threads are blocked, Scheme must ``sleep'' for a +When all Racket threads are blocked, Racket must ``sleep'' for a certain number of seconds or until external input appears on some file descriptor. Generally, sleeping should block the main event loop of the entire application. However, the way in which sleeping is performed may depend on the embedding application. The global function pointer @cppi{scheme_sleep} can be set by an embedding application to -implement a blocking sleep, although Scheme implements this function +implement a blocking sleep, although Racket implements this function for you. A @cpp{scheme_sleep} function takes two arguments: a @cpp{float} and a @@ -348,7 +348,7 @@ manipulate each ``@cpp{fd_set}'' with @cpp{MZ_FD_SET}, The following function @cpp{mzsleep} is an appropriate @cpp{scheme_sleep} function for most any Unix or Windows application. -(This is approximately the built-in sleep used by Scheme.) +(This is approximately the built-in sleep used by Racket.) @verbatim[#:indent 2]{ void mzsleep(float v, void *fds) @@ -490,7 +490,7 @@ Blocks the current thread until @var{f} with @var{data} returns a true a @cpp{Scheme_Object*} value, because it is only used by @var{f} and @var{fdf}.) -If Scheme decides to sleep, then the @var{fdf} function is called to +If Racket decides to sleep, then the @var{fdf} function is called to sets bits in @var{fds}, conceptually an array of three @cpp{fd_set}s: one or reading, one for writing, and one for exceptions. Use @cpp{scheme_get_fdset} to get elements of this @@ -501,7 +501,7 @@ If Scheme decides to sleep, then the @var{fdf} function is called to The @var{fdf} argument can be @cpp{NULL}, which implies that the thread becomes unblocked (i.e., @var{ready} changes its result to true) only - through Scheme actions, and never through external processes (e.g., + through Racket actions, and never through external processes (e.g., through a socket or OS-level semaphore)---with the exception that @cpp{scheme_signal_received} may be called to indicate an external change. @@ -548,8 +548,8 @@ Like @cpp{scheme_block_until_enable_break}, but the function Indicates that an external event may have caused the result of a synchronization poll to have a different result. Unlike most other -Scheme functions, this one can be called from any OS-level thread, and -it wakes up if the Scheme thread if it is sleeping.} +Racket functions, this one can be called from any OS-level thread, and +it wakes up if the Racket thread if it is sleeping.} @function[(void scheme_check_threads)]{ @@ -577,12 +577,12 @@ Extracts an ``@cpp{fd_set}'' from an array passed to [int repost])]{ Adds an OS-level semaphore (Windows) or other waitable handle - (Windows) to the ``@cpp{fd_set}'' @var{fds}. When Scheme performs + (Windows) to the ``@cpp{fd_set}'' @var{fds}. When Racket performs a ``@cpp{select}'' to sleep on @var{fds}, it also waits on the given - semaphore or handle. This feature makes it possible for Scheme to + semaphore or handle. This feature makes it possible for Racket to sleep until it is awakened by an external process. -Scheme does not attempt to deallocate the given semaphore or handle, +Racket does not attempt to deallocate the given semaphore or handle, and the ``@cpp{select}'' call using @var{fds} may be unblocked due to some other file descriptor or handle in @var{fds}. If @var{repost} is a true value, then @var{h} must be an OS-level semaphore, and if the @@ -603,9 +603,9 @@ Under Unix and Mac OS X, this function has no effect.} [int mask])]{ Adds an OS-level event type (Windows) to the set of types in the - ``@cpp{fd_set}'' @var{fds}. When Scheme performs a + ``@cpp{fd_set}'' @var{fds}. When Racket performs a ``@cpp{select}'' to sleep on @var{fds}, it also waits on events of - them specified type. This feature makes it possible for Scheme to + them specified type. This feature makes it possible for Racket to sleep until it is awakened by an external process. The event mask is only used when some handle is installed with @@ -711,28 +711,28 @@ Calls @var{prim} with the given @var{argc} and @var{argv} with breaks [Scheme_Thread_Cell_Table* cells] [Scheme_Object* v])]{ -Prevents Scheme thread swaps until @cpp{scheme_end_atomic} or +Prevents Racket thread swaps until @cpp{scheme_end_atomic} or @cpp{scheme_end_atomic_no_swap} is called. Start-atomic and end-atomic pairs can be nested.} @function[(void scheme_end_atomic)]{ -Ends an atomic region with respect to Scheme threads. The current +Ends an atomic region with respect to Racket threads. The current thread may be swapped out immediately (i.e., the call to @cpp{scheme_end_atomic} is assumed to be a safe point for thread swaps).} @function[(void scheme_end_atomic_no_swap)]{ -Ends an atomic region with respect to Scheme threads, and also - prevents an immediate thread swap. (In other words, no Scheme +Ends an atomic region with respect to Racket threads, and also + prevents an immediate thread swap. (In other words, no Racket thread swaps will occur until a future safe point.)} @function[(void scheme_add_swap_callback [Scheme_Closure_Func f] [Scheme_Object* data])]{ -Registers a callback to be invoked just after a Scheme thread is +Registers a callback to be invoked just after a Racket thread is swapped in. The @var{data} is provided back to @var{f} when it is called, where @cpp{Closure_Func} is defined as follows: @@ -745,4 +745,4 @@ called, where @cpp{Closure_Func} is defined as follows: [Scheme_Object* data])]{ Like @cpp{scheme_add_swap_callback}, but registers a callback to be -invoked just before a Scheme thread is swapped out.} +invoked just before a Racket thread is swapped out.} diff --git a/collects/scribblings/inside/utils.rkt b/collects/scribblings/inside/utils.rkt index a66adf95f6..eb8075718c 100644 --- a/collects/scribblings/inside/utils.rkt +++ b/collects/scribblings/inside/utils.rkt @@ -152,7 +152,7 @@ (define cppdef (lambda (x) (as-cpp-defn x (cpp x)))) (define *var italic) -(define mzc (exec "mzc")) +(define mzc (exec "raco ctool")) (define (refsecref s) (secref #:doc '(lib "scribblings/reference/reference.scrbl") s)) diff --git a/collects/scribblings/inside/values.scrbl b/collects/scribblings/inside/values.scrbl index 08527b6f36..ff3a6e1a45 100644 --- a/collects/scribblings/inside/values.scrbl +++ b/collects/scribblings/inside/values.scrbl @@ -3,27 +3,27 @@ @title[#:tag "im:values+types"]{Values and Types} -A Scheme value is represented by a pointer-sized value. The low bit is +A Racket value is represented by a pointer-sized value. The low bit is a mark bit: a 1 in the low bit indicates an immediate integer, a 0 indicates a (word-aligned) pointer. -A pointer Scheme value references a structure that begins with a +A pointer Racket value references a structure that begins with a @cppi{Scheme_Object} sub-structure, which in turn starts with a tag that has the C type @cppi{Scheme_Type}. The rest of the structure, following the @cppi{Scheme_Object} header, is type-dependent. -PLT Scheme's C interface gives Scheme values the type +Racket's C interface gives Racket values the type @cpp{Scheme_Object*}. (The ``object'' here does not refer to objects -in the sense of the @schememodname[scheme/class] library.) +in the sense of the @schememodname[racket/class] library.) Examples of @cpp{Scheme_Type} values include @cpp{scheme_pair_type} and @cpp{scheme_symbol_type}. Some of these are implemented as instances of @cppi{Scheme_Simple_Object}, which is defined in @filepath{scheme.h}, but extension or embedding code should never access this structure directly. Instead, the code should use macros, such as -@cpp{SCHEME_CAR}, that provide access to the data of common Scheme +@cpp{SCHEME_CAR}, that provide access to the data of common Racket types. -For most Scheme types, a constructor is provided for creating values +For most Racket types, a constructor is provided for creating values of the type. For example, @cpp{scheme_make_pair} takes two @cpp{Scheme_Object*} values and returns the @scheme[cons] of the values. @@ -32,12 +32,12 @@ The macro @cppdef{SCHEME_TYPE} takes a @cpp{Scheme_Object *} and returns the type of the object. This macro performs the tag-bit check, and returns @cppi{scheme_integer_type} when the value is an immediate integer; otherwise, @cpp{SCHEME_TYPE} follows the pointer to get the -type tag. Macros are provided to test for common Scheme types; for +type tag. Macros are provided to test for common Racket types; for example, @cpp{SCHEME_PAIRP} returns @cpp{1} if the value is a cons cell, @cpp{0} otherwise. -In addition to providing constructors, PLT Scheme defines six global -constant Scheme values: @cppi{scheme_true}, @cppi{scheme_false}, +In addition to providing constructors, Racket defines six global +constant Racket values: @cppi{scheme_true}, @cppi{scheme_false}, @cppi{scheme_null}, @cppi{scheme_eof}, @cppi{scheme_void}, and @cppi{scheme_undefined}. Each of these has a type tag, but each is normally recognized via its constant address. @@ -46,7 +46,7 @@ normally recognized via its constant address. can create new a primitive data type by calling @cppi{scheme_make_type}, which returns a fresh @cpp{Scheme_Type} value. To create a collectable instance of this type, allocate memory -for the instance with @cpp{scheme_malloc}. From PLT Scheme's +for the instance with @cpp{scheme_malloc}. From Racket's perspective, the main constraint on the data format of such an instance is that the first @cpp{sizeof(Scheme_Object)} bytes must correspond to a @cpp{Scheme_Object} record; furthermore, the first @@ -54,7 +54,7 @@ correspond to a @cpp{Scheme_Object} record; furthermore, the first @cpp{scheme_make_type}. Extensions with modest needs can use @cppi{scheme_make_cptr}, instead of creating an entirely new type. -Scheme values should never be allocated on the stack, and they should +Racket values should never be allocated on the stack, and they should never contain pointers to values on the stack. Besides the problem of restricting the value's lifetime to that of the stack frame, allocating values on the stack creates problems for continuations and @@ -89,7 +89,7 @@ types: floating-point value; test for this type with @cppdef{SCHEME_DBLP}} @item{@cppdef{scheme_float_type} --- single-precision flonum - inexact numbers, when specifically enabled when compiling PLT Scheme; + inexact numbers, when specifically enabled when compiling Racket; @cppi{SCHEME_FLOAT_VAL} or @cppdef{SCHEME_FLT_VAL} extracts the floating-point value; test for this type with @cppdef{SCHEME_FLTP}} @@ -109,7 +109,7 @@ types: @item{@cppdef{scheme_char_string_type} --- @index['("strings" "conversion to C")]{@cppdef{SCHEME_CHAR_STR_VAL}} extracts the string as a @cpp{mzchar*}; the string is always nul-terminated, but may also - contain embedded nul characters, and the Scheme string is modified if + contain embedded nul characters, and the Racket string is modified if this string is modified; @cppdef{SCHEME_CHAR_STRLEN_VAL} extracts the string length (in characters, not counting the nul terminator); test for this type with @cppdef{SCHEME_CHAR_STRINGP}} @@ -117,7 +117,7 @@ types: @item{@cppdef{scheme_byte_string_type} --- @cppdef{SCHEME_BYTE_STR_VAL} extracts the string as a @cpp{char*}; the string is always nul-terminated, but may also contain embedded nul - characters, and the Scheme string is modified if this string is + characters, and the Racket string is modified if this string is modified; @cppdef{SCHEME_BYTE_STRLEN_VAL} extracts the string length (in bytes, not counting the nul terminator); test for this type with @cppdef{SCHEME_BYTE_STRINGP}} @@ -158,7 +158,7 @@ types: @item{@cppdef{scheme_vector_type} --- @cppdef{SCHEME_VEC_SIZE} extracts the length and @cppdef{SCHEME_VEC_ELS} extracts the array of - Scheme values (the Scheme vector is modified when this array is + Racket values (the Racket vector is modified when this array is modified); test for this type with @cppdef{SCHEME_VECTORP}; 3m: see @secref["im:3m"] for a caution about @cppi{SCHEME_VEC_ELS}} @@ -222,7 +222,7 @@ The following are the procedure types: @item{@cppdef{scheme_closed_prim_type} --- an old-style primitive procedure with a data pointer} - @item{@cppdef{scheme_compiled_closure_type} --- a Scheme + @item{@cppdef{scheme_compiled_closure_type} --- a Racket procedure} @item{@cppdef{scheme_cont_type} --- a continuation} @@ -289,9 +289,9 @@ There are six global constants: @section[#:tag "im:strings"]{Strings} -As noted in @secref["im:unicode"], a Scheme character is a Unicode +As noted in @secref["im:unicode"], a Racket character is a Unicode code point represented by a @cpp{mzchar} value, and character strings - are @cpp{mzchar} arrays. PLT Scheme also supplies byte strings, which + are @cpp{mzchar} arrays. Racket also supplies byte strings, which are @cpp{char} arrays. For a character string @var{s}, @cpp{@cpp{SCHEME_CHAR_STR_VAL}(@var{s})} @@ -319,7 +319,7 @@ For more fine-grained control over UTF-8 encoding, use the Returns the character value. The @var{ch} value must be a legal Unicode code point (and not a surrogate, for example). The first 256 -characters are represented by constant Scheme values, and others are +characters are represented by constant Racket values, and others are allocated.} @function[(Scheme_Object* scheme_make_char_or_null @@ -389,7 +389,7 @@ Creates an integer given the high and low @cpp{long}s of an unsigned Extracts the integer value. Unlike the @cppi{SCHEME_INT_VAL} macro, this procedure will extract an integer that fits in a @cpp{long} from - a Scheme bignum. If @var{o} fits in a @cpp{long}, the extracted + a Racket bignum. If @var{o} fits in a @cpp{long}, the extracted integer is placed in @var{*i} and 1 is returned; otherwise, 0 is returned and @var{*i} is unmodified.} @@ -422,13 +422,13 @@ Creates a new floating-point value.} [float d])]{ Creates a new single-precision floating-point value. The procedure is -available only when PLT Scheme is compiled with single-precision +available only when Racket is compiled with single-precision numbers enabled.} @function[(double scheme_real_to_double [Scheme_Object* o])]{ -Converts a Scheme real number to a double-precision floating-point +Converts a Racket real number to a double-precision floating-point value.} @function[(Scheme_Object* scheme_make_pair @@ -440,7 +440,7 @@ Makes a @scheme[cons] pair.} @function[(Scheme_Object* scheme_make_byte_string [char* bytes])]{ -Makes a Scheme byte string from a nul-terminated C string. The +Makes a Racket byte string from a nul-terminated C string. The @var{bytes} string is copied.} @function[(Scheme_Object* scheme_make_byte_string_without_copying @@ -475,7 +475,7 @@ Like @cpp{scheme_make_sized_byte_string}, except the @var{len} [long size] [char fill])]{ -Allocates a new Scheme byte string.} +Allocates a new Racket byte string.} @function[(Scheme_Object* scheme_append_byte_string [Scheme_Object* a] @@ -486,7 +486,7 @@ Creates a new byte string by appending the two given byte strings.} @function[(Scheme_Object* scheme_make_locale_string [char* bytes])]{ -Makes a Scheme string from a nul-terminated byte string that is a +Makes a Racket string from a nul-terminated byte string that is a locale-specific encoding of a character string; a new string is allocated during decoding. The ``locale in the name of this function thus refers to @var{bytes}, and not the resulting string (which is @@ -495,7 +495,7 @@ Makes a Scheme string from a nul-terminated byte string that is a @function[(Scheme_Object* scheme_make_utf8_string [char* bytes])]{ -Makes a Scheme string from a nul-terminated byte string that is a +Makes a Racket string from a nul-terminated byte string that is a UTF-8 encoding. A new string is allocated during decoding. The ``utf8'' in the name of this function thus refers to @var{bytes}, and not the resulting string (which is internally stored as UCS-4).} @@ -523,7 +523,7 @@ Like @cpp{scheme_make_sized_char_string}, except the @var{len} characters @function[(Scheme_Object* scheme_make_char_string [mzchar* chars])]{ -Makes a Scheme string from a nul-terminated UCS-4 string. The +Makes a Racket string from a nul-terminated UCS-4 string. The @var{chars} string is copied.} @function[(Scheme_Object* scheme_make_char_string_without_copying @@ -558,7 +558,7 @@ Like @cpp{scheme_make_sized_char_string}, except the @var{len} [long size] [mzchar fill])]{ -Allocates a new Scheme string.} +Allocates a new Racket string.} @function[(Scheme_Object* scheme_append_char_string [Scheme_Object* a] @@ -569,22 +569,22 @@ Creates a new string by appending the two given strings.} @function[(Scheme_Object* scheme_char_string_to_byte_string [Scheme_Object* s])]{ -Converts a Scheme character string into a Scheme byte string via UTF-8.} +Converts a Racket character string into a Racket byte string via UTF-8.} @function[(Scheme_Object* scheme_byte_string_to_char_string [Scheme_Object* s])]{ -Converts a Scheme byte string into a Scheme character string via UTF-8.} +Converts a Racket byte string into a Racket character string via UTF-8.} @function[(Scheme_Object* scheme_char_string_to_byte_string_locale [Scheme_Object* s])]{ -Converts a Scheme character string into a Scheme byte string via the locale's encoding.} +Converts a Racket character string into a Racket byte string via the locale's encoding.} @function[(Scheme_Object* scheme_byte_string_to_char_string_locale [Scheme_Object* s])]{ -Converts a Scheme byte string into a Scheme character string via the locale's encoding.} +Converts a Racket byte string into a Racket character string via the locale's encoding.} @function[(Scheme_Object* scheme_intern_symbol [char* name])]{ @@ -654,7 +654,7 @@ Creates a new weak box containing the value @var{v}.} @function[(Scheme_Type scheme_make_type [char* name])]{ -Creates a new type (not a Scheme value).} +Creates a new type (not a Racket value).} @function[(Scheme_Object* scheme_make_cptr [void* ptr] @@ -664,10 +664,10 @@ Creates a C-pointer object that encapsulates @var{ptr} and uses @var{typetag} to identify the type of the pointer. The @cppi{SCHEME_CPTRP} macro recognizes objects created by @cpp{scheme_make_cptr}. The @cppi{SCHEME_CPTR_VAL} macro extracts - the original @var{ptr} from the Scheme object, and + the original @var{ptr} from the Racket object, and @cppi{SCHEME_CPTR_TYPE} extracts the type tag. The @cppi{SCHEME_CPTR_OFFSETVAL} macro returns @cpp{0} - for the result Scheme object. + for the result Racket object. The @var{ptr} can refer to either memory managed by the garbage collector or by some other memory manager. Beware, however, of @@ -690,7 +690,7 @@ referencing memory managed by the garbage collector.} Creates a C-pointer object that encapsulates both @var{ptr} and @var{offset}. The @cppi{SCHEME_CPTR_OFFSETVAL} macro returns @var{offset} - for the result Scheme object (and the macro be used to change the offset, + for the result Racket object (and the macro be used to change the offset, since it also works on objects with no offset). The @var{ptr} can refer to either memory managed by the garbage