diff --git a/doc/ref/ChangeLog b/doc/ref/ChangeLog index 3b250ac94..e312ca50d 100644 --- a/doc/ref/ChangeLog +++ b/doc/ref/ChangeLog @@ -1,3 +1,14 @@ +2002-03-16 Neil Jerram + + * scheme-utility.texi (Hooks): Further updates. New material on + GC hooks. + + * scheme-evaluation.texi (Fly Evaluation): Note disappearance of + eval2 and read-and-eval!. + + * deprecated.texi (Deprecated): Remove docs about previously + deprecated items that have now been removed. + 2002-03-15 Thien-Thi Nguyen * tools.texi (guile-1.4 guile-snarf): Remove this node. diff --git a/doc/ref/deprecated.texi b/doc/ref/deprecated.texi index 3f423fe7f..8d335a936 100644 --- a/doc/ref/deprecated.texi +++ b/doc/ref/deprecated.texi @@ -1,138 +1,3 @@ @page @node Deprecated @chapter Deprecated - -@menu -* Shared And Read Only Strings:: -@end menu - - -@node Shared And Read Only Strings -@section Shared And Read Only Strings - -The procedures described in this section are deprecated because explicit -shared substrings are planned to disappear from Guile. - -Instead, all strings will be implemented using sharing internally, -combined with a copy-on-write strategy. Once internal string sharing -and copy-on-write have been implemented, it will be unnecessary to -preserve the concept of read only strings. - -@menu -* Shared Substrings:: Strings which share memory with each other. -* Read Only Strings:: Treating certain non-strings as strings. -@end menu - - -@node Shared Substrings -@subsection Shared Substrings - -Whenever you extract a substring using @code{substring}, the Scheme -interpreter allocates a new string and copies data from the old string. -This is expensive, but @code{substring} is so convenient for -manipulating text that programmers use it often. - -Guile Scheme provides the concept of the @dfn{shared substring} to -improve performance of many substring-related operations. A shared -substring is an object that mostly behaves just like an ordinary -substring, except that it actually shares storage space with its parent -string. - -@deffn {Scheme Procedure} make-shared-substring str [start [end]] -Return a shared substring of @var{str}. The arguments are the -same as for the @code{substring} function: the shared substring -returned includes all of the text from @var{str} between -indexes @var{start} (inclusive) and @var{end} (exclusive). If -@var{end} is omitted, it defaults to the end of @var{str}. The -shared substring returned by @code{make-shared-substring} -occupies the same storage space as @var{str}. -@end deffn - -Example: - -@example -(define foo "the quick brown fox") -(define bar (make-shared-substring some-string 4 9)) - -foo => "t h e q u i c k b r o w n f o x" -bar =========> |---------| -@end example - -The shared substring @var{bar} is not given its own storage space. -Instead, the Guile interpreter notes internally that @var{bar} points to -a portion of the memory allocated to @var{foo}. However, @var{bar} -behaves like an ordinary string in most respects: it may be used with -string primitives like @code{string-length}, @code{string-ref}, -@code{string=?}. Guile makes the necessary translation between indices -of @var{bar} and indices of @var{foo} automatically. - -@example -(string-length? bar) @result{} 5 ; bar only extends from indices 4 to 9 -(string-ref bar 3) @result{} #\c ; same as (string-ref foo 7) -(make-shared-substring bar 2) - @result{} "ick" ; can even make a shared substring! -@end example - -Because creating a shared substring does not require allocating new -storage from the heap, it is a very fast operation. However, because it -shares memory with its parent string, a change to the contents of the -parent string will implicitly change the contents of its shared -substrings. - -@example -(string-set! foo 7 #\r) -bar @result{} "quirk" -@end example - -Guile considers shared substrings to be immutable. This is because -programmers might not always be aware that a given string is really a -shared substring, and might innocently try to mutate it without -realizing that the change would affect its parent string. (We are -currently considering a "copy-on-write" strategy that would permit -modifying shared substrings without affecting the parent string.) - -In general, shared substrings are useful in circumstances where it is -important to divide a string into smaller portions, but you do not -expect to change the contents of any of the strings involved. - - -@node Read Only Strings -@subsection Read Only Strings - -In previous versions of Guile, there was the idea that some string-based -primitives such as @code{string-append} could equally accept symbols as -arguments. For example, one could write - -@lisp -(string-append '/home/ 'vigilia) -@end lisp - -@noindent -and get @code{"/home/vigilia"} as the result. The term @dfn{read only -string} was adopted to describe the argument type expected by such -primitives. - -This idea has now been removed. The predicate @code{read-only-string?} -still exists, but deprecated, and is equivalent to - -@lisp -(lambda (x) (or (string? x) (symbol? x))) -@end lisp - -@noindent -But no Guile primitives now use @code{read-only-string?} to validate -their arguments. - -String-based primitives such as @code{string-append} -now require strings: - -@lisp -(string-append '/home/ 'vigilia) -@result{} -ERROR: Wrong type argument (expecting STRINGP): /home/ -@end lisp - -@deffn {Scheme Procedure} read-only-string? obj -Return @code{#t} if @var{obj} is either a string or a symbol, -otherwise return @code{#f}. -@end deffn diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi index 58c9530c2..4e131332d 100644 --- a/doc/ref/guile.texi +++ b/doc/ref/guile.texi @@ -83,7 +83,7 @@ @dircategory The Algorithmic Language Scheme @direntry -* Guile Reference: (guile). The Guile reference manual. +* Guile Reference: (guile). The Guile reference manual. @end direntry @setchapternewpage off @@ -121,7 +121,7 @@ by the Free Software Foundation. @sp 10 @comment The title is printed in a large font. @title Guile Reference Manual -@subtitle $Id: guile.texi,v 1.14 2002-03-15 14:03:53 ossau Exp $ +@subtitle $Id: guile.texi,v 1.15 2002-03-16 13:51:03 ossau Exp $ @subtitle For use with Guile @value{VERSION} @c AUTHORS diff --git a/doc/ref/intro.texi b/doc/ref/intro.texi index 6a120c284..6d373a7cc 100644 --- a/doc/ref/intro.texi +++ b/doc/ref/intro.texi @@ -1,6 +1,3 @@ -@c $Id: intro.texi,v 1.8 2002-01-08 08:29:00 ttn Exp $ - - @page @node What is Guile? @chapter What is Guile? diff --git a/doc/ref/posix.texi b/doc/ref/posix.texi index 62063e7ad..724015f68 100644 --- a/doc/ref/posix.texi +++ b/doc/ref/posix.texi @@ -280,6 +280,7 @@ The return value is unspecified. @end deffn @deffn {Scheme Procedure} unread-char char [port] +@deffnx {C Function} scm_unread_char (char, port) Place @var{char} in @var{port} so that it will be read by the next read operation. If called multiple times, the unread characters will be read again in last-in first-out order. If @var{port} is @@ -395,14 +396,7 @@ the port was opened, since modes such as "append" which are used only during port creation are not retained. @end deffn -@deffn {Scheme Procedure} close-all-ports-except . ports -[DEPRECATED] Close all open file ports used by the interpreter -except for those supplied as arguments. This procedure -was intended to be used before an exec call to close file descriptors -which are not needed in the new process. However it has the -undesirable side-effect of flushing buffers, so it's deprecated. -Use port-for-each instead. -@end deffn +@vgone{close-all-ports-except,1.6} @deffn {Scheme Procedure} port-for-each proc @deffnx {C Function} scm_port_for_each (proc) @@ -2239,7 +2233,7 @@ number. @deffnx {C Function} scm_getsockname (sock) Return the address of @var{sock}, in the same form as the object returned by @code{accept}. On many systems the address -of a socket in the @code{AF_FILE} name space cannot be read. +of a socket in the @code{AF_FILE} namespace cannot be read. @end deffn @deffn {Scheme Procedure} getpeername sock @@ -2247,7 +2241,7 @@ of a socket in the @code{AF_FILE} name space cannot be read. Return the address that @var{sock} is connected to, in the same form as the object returned by @code{accept}. On many systems the address of a socket in the -@code{AF_FILE} name space cannot be read. +@code{AF_FILE} namespace cannot be read. @end deffn @deffn {Scheme Procedure} recv! sock buf [flags] diff --git a/doc/ref/scheme-evaluation.texi b/doc/ref/scheme-evaluation.texi index fbfcd87a8..059e664be 100644 --- a/doc/ref/scheme-evaluation.texi +++ b/doc/ref/scheme-evaluation.texi @@ -235,6 +235,9 @@ Evaluate @var{exp} in the top-level environment specified by the current module. @end deffn +@vgone{eval2,1.6} +@vgone{read-and-eval!,1.6} + @node Loading @section Loading Scheme Code from File diff --git a/doc/ref/scheme-utility.texi b/doc/ref/scheme-utility.texi index b1bb7dbd1..f544ac0da 100644 --- a/doc/ref/scheme-utility.texi +++ b/doc/ref/scheme-utility.texi @@ -572,25 +572,28 @@ code needs to do, you may prefer to use this interface. To create a C hook, you should allocate storage for a structure of type @code{scm_t_c_hook} and then initialize it using @code{scm_c_hook_init}. -@deffn {C Type} scm_t_c_hook +@deftp {C Type} scm_t_c_hook Data type for a C hook. The internals of this type should be treated as opaque. -@end deffn +@end deftp -@deffn {C Enum} scm_t_c_hook_type +@deftp {C Enum} scm_t_c_hook_type Enumeration of possible hook types, which are: @table @code @item SCM_C_HOOK_NORMAL +@vindex SCM_C_HOOK_NORMAL Type of hook for which all the registered functions will always be called. @item SCM_C_HOOK_OR +@vindex SCM_C_HOOK_OR Type of hook for which the sequence of registered functions will be called only until one of them returns C true (a non-NULL pointer). @item SCM_C_HOOK_AND +@vindex SCM_C_HOOK_AND Type of hook for which the sequence of registered functions will be called only until one of them returns C false (a NULL pointer). @end table -@end deffn +@end deftp @deftypefn {C Function} void scm_c_hook_init (scm_t_c_hook *hook, void *hook_data, scm_t_c_hook_type type) Initialize the C hook at memory pointed to by @var{hook}. @var{type} @@ -618,10 +621,10 @@ The call closure data specified by the @code{scm_c_hook_run} call that runs the hook. @end table -@deffn {C Type} scm_t_c_hook_function +@deftp {C Type} scm_t_c_hook_function Function type for a C hook function: takes three @code{void *} parameters and returns a @code{void *} result. -@end deffn +@end deftp @deftypefn {C Function} void scm_c_hook_add (scm_t_c_hook *hook, scm_t_c_hook_function func, void *func_data, int appendp) Add function @var{func}, with function closure data @var{func_data}, to @@ -654,13 +657,73 @@ function to be called. @node Guile Hooks @subsection Hooks Provided by Guile -@table @code -@item scm_before_gc_c_hook -@item scm_before_mark_c_hook -@item scm_before_sweep_c_hook -@item scm_after_sweep_c_hook -@item scm_after_gc_c_hook -@end table +@menu +* GC Hooks:: Garbage collection hooks. +* REPL Hooks:: Hooks into the Guile REPL. +@end menu + + +@node GC Hooks +@subsubsection Hooks for Garbage Collection + +Whenever Guile performs a garbage collection, it calls the following +hooks in the order shown. + +@defvr {C Hook} scm_before_gc_c_hook +C hook called at the very start of a garbage collection, after setting +@code{scm_gc_running_p} to 1, but before entering the GC critical +section. + +If garbage collection is blocked because @code{scm_block_gc} is +non-zero, GC exits early soon after calling this hook, and no further +hooks will be called. +@end defvr + +@defvr {C Hook} scm_before_mark_c_hook +C hook called before beginning the mark phase of garbage collection, +after the GC thread has entered a critical section. +@end defvr + +@defvr {C Hook} scm_before_sweep_c_hook +C hook called before beginning the sweep phase of garbage collection. +This is the same as at the end of the mark phase, since nothing else +happens between marking and sweeping. +@end defvr + +@defvr {C Hook} scm_after_sweep_c_hook +C hook called after the end of the sweep phase of garbage collection, +but while the GC thread is still inside its critical section. +@end defvr + +@defvr {C Hook} scm_after_gc_c_hook +C hook called at the very end of a garbage collection, after the GC +thread has left its critical section. +@end defvr + +@defvr {Scheme Hook} after-gc-hook +@vindex scm_after_gc_hook +Scheme hook with arity 0. This hook is run asynchronously +(@pxref{Asyncs}) soon after the GC has completed and any other events +that were deferred during garbage collection have been processed. (Also +accessible from C with the name @code{scm_after_gc_hook}.) +@end defvr + +All the C hooks listed here have type @code{SCM_C_HOOK_NORMAL}, are +initialized with hook closure data NULL, are are invoked by +@code{scm_c_hook_run} with call closure data NULL. + +@cindex guardians, testing for GC'd objects +The Scheme hook @code{after-gc-hook} is particularly useful in +conjunction with guardians (@pxref{Guardians}). Typically, if you are +using a guardian, you want to call the guardian after garbage collection +to see if any of the objects added to the guardian have been collected. +By adding a thunk that performs this call to @code{after-gc-hook}, you +can ensure that your guardian is tested after every garbage collection +cycle. + + +@node REPL Hooks +@subsubsection Hooks into the Guile REPL @c Local Variables: diff --git a/doc/ref/scripts.texi b/doc/ref/scripts.texi index 4a121e5fc..10549dc12 100644 --- a/doc/ref/scripts.texi +++ b/doc/ref/scripts.texi @@ -101,7 +101,7 @@ slow down execution. By default, the debugging evaluator is only used when entering an interactive session. When executing a script with @code{-s} or @code{-c}, the normal, faster evaluator is used by default. -@vnew{1.6} +@vnew{1.8} @item --no-debug Do not use the debugging evaluator, even when entering an interactive session.