From bcadf5ac699fa5035a9eefda88444fc5a4bb648b Mon Sep 17 00:00:00 2001 From: Matthew Flatt Date: Sun, 31 Jan 2010 01:10:56 +0000 Subject: [PATCH] doc improvements: some details on reachability for weak references; module example in insidemz; clarification for 'read-language' related to readtables and #reader svn: r17905 --- collects/scribblings/inside/overview.scrbl | 46 ++++++++++++++++++- .../scribblings/reference/eval-model.scrbl | 10 ++++ collects/scribblings/reference/mpairs.scrbl | 2 +- collects/scribblings/reference/pairs.scrbl | 2 +- collects/scribblings/reference/read.scrbl | 23 ++++++---- .../scribblings/reference/readtables.scrbl | 2 +- collects/scribblings/reference/vectors.scrbl | 4 +- 7 files changed, 75 insertions(+), 14 deletions(-) diff --git a/collects/scribblings/inside/overview.scrbl b/collects/scribblings/inside/overview.scrbl index ccf65c5d32..e02bf2f0f9 100644 --- a/collects/scribblings/inside/overview.scrbl +++ b/collects/scribblings/inside/overview.scrbl @@ -213,7 +213,7 @@ 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 --cc hw.c} +@commandline{mzc --xform hw.c} @commandline{mzc --3m --cc hw.3m.c} @commandline{mzc --3m --ld hw.so hw.o} @@ -221,6 +221,50 @@ Some examples in @filepath{collects/mzscheme/examples} work with MzScheme3m 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} + +To create an extension that behaves as a module, return a symbol from +@cpp{scheme_module_name}, and have @cpp{scheme_initialize} and +@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]: + +@verbatim[#:indent 2]{ + #include "escheme.h" + + Scheme_Object *scheme_initialize(Scheme_Env *env) { + Scheme_Env *mod_env; + mod_env = scheme_primitive_module(scheme_intern_symbol("hi"), + env); + scheme_add_global("greeting", + scheme_make_utf8_string("hello"), + mod_env); + scheme_finish_primitive_module(mod_env); + return scheme_void; + } + + Scheme_Object *scheme_reload(Scheme_Env *env) { + return scheme_initialize(env); /* Nothing special for reload */ + } + + Scheme_Object *scheme_module_name() { + return scheme_intern_symbol("hi"); + } +} + +This extension could be compiled for 3m on Mac OS X for i386, 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} + +The resulting module can be loaded with + +@schemeblock[(require "hi.ss")] + @; ---------------------------------------------------------------------- @section[#:tag "embedding"]{Embedding MzScheme into a Program} diff --git a/collects/scribblings/reference/eval-model.scrbl b/collects/scribblings/reference/eval-model.scrbl index 0dbd964e09..e65caaf16b 100644 --- a/collects/scribblings/reference/eval-model.scrbl +++ b/collects/scribblings/reference/eval-model.scrbl @@ -366,6 +366,16 @@ via a @tech{weak reference}, then the object can be reclaimed, and the @tech{weak reference} is replaced by a different @tech{value} (typically @scheme[#f]). +As a special case, a @tech{fixnum} is always considered reachable by +the garbage collector. Many other values are always reachable due to +the way they are implemented and used: A @tech{character} in the +Latin-1 range is always reachable, because @scheme[equal?] Latin-1 +characters are always @scheme[eq?], and all of the Latin-1 characters +are referenced by an internal module. Similarly, @scheme[null], +@scheme[#t], @scheme[#f], @scheme[eof], and @|void-const| and are +always reachable. Values produced by @scheme[quote] remain reachable +when the @scheme[quote] expression itself is reachable. + @;------------------------------------------------------------------------ @section{Procedure Applications and Local Variables} diff --git a/collects/scribblings/reference/mpairs.scrbl b/collects/scribblings/reference/mpairs.scrbl index 8f2178157f..0edb8084e4 100644 --- a/collects/scribblings/reference/mpairs.scrbl +++ b/collects/scribblings/reference/mpairs.scrbl @@ -19,7 +19,7 @@ instead created with mutable pairs. @defproc[(mpair? [v any/c]) boolean?]{Returns @scheme[#t] if @scheme[v] is a mutable pair, @scheme[#f] otherwise.} -@defproc[(mcons [a any/c] [d any/c]) pair?]{Returns a mutable pair whose first +@defproc[(mcons [a any/c] [d any/c]) pair?]{Returns a newly allocated mutable pair whose first element is @scheme[a] and second element is @scheme[d].} @defproc[(mcar [p mpair?]) any/c]{Returns the first element of the diff --git a/collects/scribblings/reference/pairs.scrbl b/collects/scribblings/reference/pairs.scrbl index 564a9cf695..0c87b8e370 100644 --- a/collects/scribblings/reference/pairs.scrbl +++ b/collects/scribblings/reference/pairs.scrbl @@ -107,7 +107,7 @@ the empty list, @scheme[#f] otherwise. (null? (cdr (list 1))) ]} -@defproc[(cons [a any/c] [d any/c]) pair?]{Returns a pair whose first +@defproc[(cons [a any/c] [d any/c]) pair?]{Returns a newly allocated pair whose first element is @scheme[a] and second element is @scheme[d]. @mz-examples[ (cons 1 2) diff --git a/collects/scribblings/reference/read.scrbl b/collects/scribblings/reference/read.scrbl index 71e6c1a8ac..812e8ba018 100644 --- a/collects/scribblings/reference/read.scrbl +++ b/collects/scribblings/reference/read.scrbl @@ -114,14 +114,21 @@ soon as a @tech{reader language} (or its absence) is determined. A @deftech{reader language} is specified by @litchar{#lang} or @litchar{#!} (see @secref["parse-reader"]) at the beginning of the -input, though possibly after comment forms. Instead of dispatching to -a @schemeidfont{read} or @schemeidfont{read-syntax} form as -@scheme[read] and @scheme[read-syntax] do, @scheme[read-language] -dispatches to a @schemeidfont{get-info} function (if any) exported by -the same module. The result of the @schemeidfont{get-info} function is -the result of @scheme[read-language] if it is a function of two -arguments; if @schemeidfont{get-info} produces any other kind of -result, the @exnraise[exn:fail:contract]. +input, though possibly after comment forms. The default +@tech{readtable} is used by @scheme[read-language] (instead of the +value of @scheme[current-readtable]), and @litchar{#reader} forms +(which might produce comments) are not allowed before @litchar{#lang} +or @litchar{#!}. + +When it finds a @litchar{#lang} or @litchar{#!} specification, instead +of dispatching to a @schemeidfont{read} or @schemeidfont{read-syntax} +form as @scheme[read] and @scheme[read-syntax] do, +@scheme[read-language] dispatches to a @schemeidfont{get-info} +function (if any) exported by the same module. The result of the +@schemeidfont{get-info} function is the result of +@scheme[read-language] if it is a function of two arguments; if +@schemeidfont{get-info} produces any other kind of result, the +@exnraise[exn:fail:contract]. The function produced by @schemeidfont{get-info} reflects information about the expected syntax of the input stream. The first argument to the diff --git a/collects/scribblings/reference/readtables.scrbl b/collects/scribblings/reference/readtables.scrbl index acbf2dff83..2e90650e99 100644 --- a/collects/scribblings/reference/readtables.scrbl +++ b/collects/scribblings/reference/readtables.scrbl @@ -5,7 +5,7 @@ @title[#:style 'toc]{Reader Extension} Scheme's reader can be extended in three ways: through a reader-macro -procedure in a readtable (see @secref["readtables"]), through a +procedure in a @tech{readtable} (see @secref["readtables"]), through a @litchar{#reader} form (see @secref["parse-reader"]), or through a custom-port byte reader that returns a ``special'' result procedure (see @secref["customport"]). All three kinds of @deftech{reader diff --git a/collects/scribblings/reference/vectors.scrbl b/collects/scribblings/reference/vectors.scrbl index fd90298fb3..89ed54b763 100644 --- a/collects/scribblings/reference/vectors.scrbl +++ b/collects/scribblings/reference/vectors.scrbl @@ -36,7 +36,7 @@ initialized to contain @scheme[v].} @defproc[(vector [v any/c] ...) vector?]{ -Returns a mutable vector with as many slots as provided @scheme[v]s, +Returns a newly allocated mutable vector with as many slots as provided @scheme[v]s, where the slots are initialized to contain the given @scheme[v]s in order.} @@ -44,7 +44,7 @@ order.} @defproc[(vector-immutable [v any/c] ...) (and/c vector? immutable?)]{ -Returns an immutable vector with as many slots as provided +Returns a newly allocated immutable vector with as many slots as provided @scheme[v]s, where the slots are contain the given @scheme[v]s in order.}