+2002-03-16 Neil Jerram <neil@ossau.uklinux.net>
+
+ * 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 <ttn@giblet.glug.org>
* tools.texi (guile-1.4 guile-snarf): Remove this node.
-@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
+@page
+@node Deprecated
+@chapter Deprecated
@dircategory The Algorithmic Language Scheme
@direntry
-* Guile Reference: (guile). The Guile reference manual.
+* Guile Reference: (guile). The Guile reference manual.
@end direntry
@setchapternewpage off
@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
-@c $Id: intro.texi,v 1.8 2002-01-08 08:29:00 ttn Exp $
-
-
@page
@node What is Guile?
@chapter What is Guile?
@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
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)
@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
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]
the current module.
@end deffn
+@vgone{eval2,1.6}
+@vgone{read-and-eval!,1.6}
+
@node Loading
@section Loading Scheme Code from File
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}
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
@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:
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.
HCoop / bpt / guile.git / commitdiff