diff options
author | Ludovic Courtès <ludo@gnu.org> | 2008-09-10 23:09:30 +0200 |
---|---|---|
committer | Ludovic Courtès <ludo@gnu.org> | 2008-09-10 23:09:30 +0200 |
commit | 6f03035fe80d1c25ffadc42ec59c473402f65f60 (patch) | |
tree | a552a077bafe408ced8737674aecdf3007f31679 /doc | |
parent | 328efeb9a66dddcf78a24fad96d3db58e9c3375d (diff) | |
parent | c5cd474d8c37bf32d7236e63d754a0eee9eb9071 (diff) | |
download | guile-6f03035fe80d1c25ffadc42ec59c473402f65f60.tar.gz |
Merge branch 'master' into boehm-demers-weiser-gc
Conflicts:
libguile/Makefile.am
libguile/coop-defs.h
libguile/gc-card.c
libguile/gc-freelist.c
libguile/gc-malloc.c
libguile/gc-mark.c
libguile/gc-segment.c
libguile/gc.c
libguile/gc.h
libguile/gc_os_dep.c
libguile/hashtab.c
libguile/hashtab.h
libguile/inline.h
libguile/private-gc.h
libguile/struct.c
libguile/struct.h
libguile/threads.c
libguile/threads.h
libguile/vectors.h
libguile/weaks.h
test-suite/tests/gc.test
Diffstat (limited to 'doc')
-rw-r--r-- | doc/.gitignore | 1 | ||||
-rw-r--r-- | doc/COPYING | 0 | ||||
-rw-r--r-- | doc/ChangeLog | 10 | ||||
-rw-r--r-- | doc/Makefile.am | 7 | ||||
-rw-r--r-- | doc/example-smob/COPYING | 0 | ||||
-rw-r--r-- | doc/example-smob/ChangeLog | 4 | ||||
-rw-r--r-- | doc/goops/ChangeLog | 5 | ||||
-rw-r--r-- | doc/goops/goops-tutorial.texi | 39 | ||||
-rw-r--r-- | doc/oldfmt.c | 49 | ||||
-rw-r--r-- | doc/ref/.cvsignore | 1 | ||||
-rw-r--r-- | doc/ref/.gitignore | 2 | ||||
-rw-r--r-- | doc/ref/ChangeLog | 206 | ||||
-rw-r--r-- | doc/ref/Makefile.am | 5 | ||||
-rwxr-xr-x | doc/ref/api-data.texi | 68 | ||||
-rw-r--r-- | doc/ref/api-debug.texi | 437 | ||||
-rw-r--r-- | doc/ref/api-modules.texi | 12 | ||||
-rw-r--r-- | doc/ref/api-options.texi | 17 | ||||
-rw-r--r-- | doc/ref/api-scheduling.texi | 157 | ||||
-rw-r--r-- | doc/ref/autoconf.texi | 41 | ||||
-rw-r--r-- | doc/ref/guile.texi | 10 | ||||
-rw-r--r-- | doc/ref/libguile-concepts.texi | 2 | ||||
-rw-r--r-- | doc/ref/posix.texi | 30 | ||||
-rw-r--r-- | doc/ref/scheme-debugging.texi | 396 | ||||
-rw-r--r-- | doc/ref/scheme-using.texi | 176 | ||||
-rw-r--r-- | doc/ref/srfi-modules.texi | 590 |
25 files changed, 1485 insertions, 780 deletions
diff --git a/doc/.gitignore b/doc/.gitignore new file mode 100644 index 000000000..ecbb7fc6d --- /dev/null +++ b/doc/.gitignore @@ -0,0 +1 @@ +stamp-vti diff --git a/doc/COPYING b/doc/COPYING deleted file mode 100644 index e69de29bb..000000000 --- a/doc/COPYING +++ /dev/null diff --git a/doc/ChangeLog b/doc/ChangeLog index cab132e16..4153ad873 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,13 @@ +2008-04-26 Ludovic Courtès <ludo@gnu.org> + + * Makefile.am (EXAMPLE_SMOB_FILES): Remove `COPYING'. + +2008-01-22 Neil Jerram <neil@ossau.uklinux.net> + + * COPYING: Removed. + + * oldfmt.c: Update copyright statement to LGPL. + 2002-09-14 Rob Browning <rlb@defaultvalue.org> * .cvsignore: add stamp-vti.1 diff --git a/doc/Makefile.am b/doc/Makefile.am index a9a072225..188fa8334 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -1,6 +1,6 @@ ## Process this file with Automake to create Makefile.in ## -## Copyright (C) 1998, 2002, 2006 Free Software Foundation, Inc. +## Copyright (C) 1998, 2002, 2006, 2008 Free Software Foundation, Inc. ## ## This file is part of GUILE. ## @@ -27,7 +27,7 @@ SUBDIRS = ref tutorial goops r5rs # man_MANS = guile.1 EXAMPLE_SMOB_FILES = \ - ChangeLog Makefile README COPYING image-type.c image-type.h myguile.c + ChangeLog Makefile README image-type.c image-type.h myguile.c OLDFMT = oldfmt.c @@ -43,9 +43,8 @@ EXTRA_DIST = groupings.alist # guile-api.alist # pending the papers from Robert Merkel # EXTRA_DIST = guile.1 -if MAINTAINER_MODE include $(top_srcdir)/am/maintainer-dirs guile-api.alist: guile-api.alist-FORCE ( cd $(top_builddir) ; $(mscripts)/update-guile-api.alist ) guile-api.alist-FORCE: -endif + diff --git a/doc/example-smob/COPYING b/doc/example-smob/COPYING deleted file mode 100644 index e69de29bb..000000000 --- a/doc/example-smob/COPYING +++ /dev/null diff --git a/doc/example-smob/ChangeLog b/doc/example-smob/ChangeLog index 3984686fc..931860849 100644 --- a/doc/example-smob/ChangeLog +++ b/doc/example-smob/ChangeLog @@ -1,3 +1,7 @@ +2008-01-22 Neil Jerram <neil@ossau.uklinux.net> + + * COPYING: Removed. + 2004-09-24 Marius Vollmer <mvo@zagadka.de> * image-type.c: Updated from manual. diff --git a/doc/goops/ChangeLog b/doc/goops/ChangeLog index b0e742b71..a5a637d7b 100644 --- a/doc/goops/ChangeLog +++ b/doc/goops/ChangeLog @@ -1,3 +1,8 @@ +2008-02-06 Neil Jerram <neil@ossau.uklinux.net> + + * goops-tutorial.texi (Next-method): Minor improvements to the + text. + 2006-09-28 Neil Jerram <neil@ossau.uklinux.net> * goops.texi (Slot Options): Added example from Ludovic Courtès diff --git a/doc/goops/goops-tutorial.texi b/doc/goops/goops-tutorial.texi index 7ab6ebcf0..11155dfae 100644 --- a/doc/goops/goops-tutorial.texi +++ b/doc/goops/goops-tutorial.texi @@ -690,11 +690,12 @@ In this case, @node Next-method, Example, Generic functions and methods, Generic functions @subsection Next-method -When a generic function is called, the list of applicable methods is -built. As mentioned before, the most specific method of this list is -applied (see@ @ref{Generic functions and methods}). This method may call -the next method in the list of applicable methods. This is done by using -the special form @code{next-method}. Consider the following definitions +When you call a generic function, with a particular set of arguments, +GOOPS builds a list of all the methods that are applicable to those +arguments and orders them by how closely the method definitions match +the actual argument types. It then calls the method at the top of this +list. If the selected method's code wants to call on to the next method +in this list, it can do so by using @code{next-method}. @lisp (define-method (Test (a <integer>)) (cons 'integer (next-method))) @@ -702,7 +703,7 @@ the special form @code{next-method}. Consider the following definitions (define-method (Test a) (list 'top)) @end lisp -With those definitions, +With these definitions, @lisp (Test 1) @result{} (integer number top) @@ -710,6 +711,32 @@ With those definitions, (Test #t) @result{} (top) @end lisp +@code{next-method} is always called as just @code{(next-method)}. The +arguments for the next method call are always implicit, and always the +same as for the original method call. + +If you want to call on to a method with the same name but with a +different set of arguments (as you might with overloaded methods in C++, +for example), you do not use @code{next-method}, but instead simply +write the new call as usual: + +@lisp +(define-method (Test (a <number>) min max) + (if (and (>= a min) (<= a max)) + (display "Number is in range\n")) + (Test a)) + +(Test 2 1 10) +@print{} +Number is in range +@result{} +(integer number top) +@end lisp + +(You should be careful in this case that the @code{Test} calls do not +lead to an infinite recursion, but this consideration is just the same +as in Scheme code in general.) + @node Example, , Next-method, Generic functions @subsection Example diff --git a/doc/oldfmt.c b/doc/oldfmt.c index 0d2c86ead..fc82ba92a 100644 --- a/doc/oldfmt.c +++ b/doc/oldfmt.c @@ -1,43 +1,18 @@ -/* Copyright (C) 2000,2001, 2006 Free Software Foundation, Inc. +/* Copyright (C) 2000,2001, 2006, 2008 Free Software Foundation, Inc. * - * This program is free software; you can redistribute it and/or modify - * it under the terms of the GNU General Public License as published by - * the Free Software Foundation; either version 2, or (at your option) - * any later version. - * - * This program is distributed in the hope that it will be useful, - * but WITHOUT ANY WARRANTY; without even the implied warranty of - * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the - * GNU General Public License for more details. - * - * You should have received a copy of the GNU General Public License - * along with this software; see the file COPYING. If not, write to - * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, - * Boston, MA 02110-1301 USA - * - * As a special exception, the Free Software Foundation gives permission - * for additional uses of the text contained in its release of GUILE. + * This library is free software; you can redistribute it and/or + * modify it under the terms of the GNU Lesser General Public + * License as published by the Free Software Foundation; either + * version 2.1 of the License, or (at your option) any later version. * - * The exception is that, if you link the GUILE library with other files - * to produce an executable, this does not by itself cause the - * resulting executable to be covered by the GNU General Public License. - * Your use of that executable is in no way restricted on account of - * linking the GUILE library code into it. - * - * This exception does not however invalidate any other reasons why - * the executable file might be covered by the GNU General Public License. - * - * This exception applies only to the code released by the - * Free Software Foundation under the name GUILE. If you copy - * code from other Free Software Foundation releases into a copy of - * GUILE, as the General Public License permits, the exception does - * not apply to the code that you add in this way. To avoid misleading - * anyone as to the status of such modified files, you must delete - * this exception notice from them. + * This library is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + * Lesser General Public License for more details. * - * If you write modifications of your own for GUILE, it is your choice - * whether to permit this exception to apply to your modifications. - * If you do not wish that, delete this exception notice. + * You should have received a copy of the GNU Lesser General Public + * License along with this library; if not, write to the Free Software + * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA */ diff --git a/doc/ref/.cvsignore b/doc/ref/.cvsignore index 5a9c9005d..b78625611 100644 --- a/doc/ref/.cvsignore +++ b/doc/ref/.cvsignore @@ -22,6 +22,7 @@ Makefile Makefile.in autoconf-macros.texi mdate-sh +lib-version.texi stamp-vti stamp-vti.1 texinfo.tex diff --git a/doc/ref/.gitignore b/doc/ref/.gitignore new file mode 100644 index 000000000..fc69e3188 --- /dev/null +++ b/doc/ref/.gitignore @@ -0,0 +1,2 @@ +autoconf-macros.texi +lib-version.texi diff --git a/doc/ref/ChangeLog b/doc/ref/ChangeLog index ebb38fa33..e4ae0b1ae 100644 --- a/doc/ref/ChangeLog +++ b/doc/ref/ChangeLog @@ -1,3 +1,153 @@ +2008-07-17 Neil Jerram <neil@ossau.uklinux.net> + + * scheme-using.texi (Evaluating Scheme Code): Document use of + `C-u' prefix with evaluation commands. + +2008-07-05 Ludovic Courtès <ludo@gnu.org> + + * api-data.texi (Symbol Primitives): Add `scm_c_symbol_length ()'. + +2008-06-30 Julian Graham <joolean@gmail.com> + + * srfi-modules.texi (SRFI-18): New section. + (SRFI-19 Time): Mention SRFI-18's `current-time'. + +2008-06-28 Ludovic Courtès <ludo@gnu.org> + + * api-modules.texi (Using Guile Modules): Substitute "syntax + transformer" to "system transformer". Reported by Sebastian + Tennant <sebyte@smolny.plus.com>. + +2008-06-01 Ludovic Courtès <ludo@gnu.org> + + * srfi-modules.texi (SRFI-88): Fix URL. + +2008-05-14 Julian Graham <joolean@gmail.com> + + * api-scheduling.texi (Mutexes and Condition Variables): Add + documentation for new functions "scm_mutex_owner", + "scm_mutex_level", and "scm_mutex_locked_p". Update + documentation for function "scm_lock_mutex_timed" to reflect + addition of optional ownership argument. + +2008-05-07 Ludovic Courtès <ludo@gnu.org> + + * Makefile.am (autoconf-macros.texi): Avoid use of GNU Make + specific `$<' variable. This broke with BSD Make as found on + FreeBSD 6.2. + +2008-05-05 Neil Jerram <neil@ossau.uklinux.net> + + * scheme-using.texi (Using Guile in Emacs): Add concept index + entries `GDS' and `Emacs'. + + * api-debug.texi (Debugging): Add concept index entry `Debugging'. + +2008-05-04 Ludovic Courtès <ludo@gnu.org> + + * guile.texi (Guile Modules): Include `autoconf.texi'. + * autoconf.texi (Autoconf Support): Mention `pkg-config'. + (Autoconf Macros): Document `pkg-config' support. + +2008-04-26 Ludovic Courtès <ludo@gnu.org> + + * srfi-modules.texi (SRFI-88): New section. + * api-data.texi (Keyword Read Syntax): Add reference to + `SRFI-88'. + +2008-04-17 Neil Jerram <neil@ossau.uklinux.net> + + * posix.texi (File System): New doc for file-exists?. + +2008-04-15 Ludovic Courtès <ludo@gnu.org> + + * api-data.texi (Keywords): Mention postfix syntax. + (Keyword Read Syntax): Document `postfix' read option. + * api-options.texi (Reader options): Update examples. + (Examples of option use): Likewise. + +2008-03-28 Neil Jerram <neil@ossau.uklinux.net> + + * libguile-concepts.texi (Multi-Threading): Fix typo. + +2008-03-24 Neil Jerram <neil@ossau.uklinux.net> + + Applying patch from Julian Graham, containing minor fixes to his + thread enhancements: + + * api-scheduling.texi (Mutexes and Condition Variables): Change + `flag' to `flags' in docstring. + +2008-03-19 Neil Jerram <neil@ossau.uklinux.net> + + * api-debug.texi (Low Level Trap Calls): Removed (material + duplicated elsewhere); doc for with-traps and debug-object? moved + to section on evaluator trap options. + (High Level Traps): Renamed just `Traps'. Add references to + evaluator trap options and debug options. Make language + appropriate for core Guile (as opposed to previously separate + package). + (Location Traps): Corrected to reflect that location traps now + specify a specific position, not a range of positions. + (Debugging Examples): New (content moved here from + scheme-debugging.texi, and updated to use traps instead of + breakpoints). + + * api-modules.texi (Included Guile Modules): Change `Debugging + Features' reference to `Tracing'. + + * api-options.texi (Evaluator trap options): Doc for with-traps + and debug-object? is now here. + + * guile.texi, scheme-debugging.texi: Move the `Tracing' content of + scheme-debugging.texi to the Modules section. + + * scheme-using.texi (Using Guile in Emacs, GDS Getting Started): + Minor edits. + + * scheme-debugging.texi (Debugging Features, Intro to + Breakpoints): Removed. + (Examples): Moved to api-debug.texi. + (Tracing, Old Tracing): Promoted one level. + (New Tracing, Tracing Compared): Removed. + +2008-03-08 Julian Graham <joolean@gmail.com> + + * api-scheduling.texi (Threads): Add documentation for new + functions "scm_thread_p" and new "scm_join_thread_timed". + (Mutexes and Condition Variables): Add documentation for new + functions "scm_make_mutex_with_flags", "scm_mutex_p", + "scm_lock_mutex_timed", "scm_unlock_mutex_timed", and + "scm_condition_variable_p". + +2008-02-11 Neil Jerram <neil@ossau.uklinux.net> + + * api-data.texi (Random): New text about the default random state, + following suggestions by Stephen Uitti. + +2008-02-01 Neil Jerram <neil@ossau.uklinux.net> + + * api-scheduling.texi (Threads): Add "C Function scm_join_thread" + to doc for join-thread. Thanks to Antoine Mathys for reporting + that scm_join_thread was missing. + +2007-12-09 Stephen Compall <s11@member.fsf.org> + + * srfi-modules.texi (SRFI-69): Avoid use of the first person. + +2007-12-03 Stephen Compall <s11@member.fsf.org> + + * srfi-modules.texi: Describe SRFI-69 in a new subsection. + +2007-10-29 Julian Graham <joolean@gmail.com> + + * api-scheduling.texi (Threads): Document `cancel-thread', + `set-thread-cleanup!' and `thread-cleanup'. + +2007-10-24 Neil Jerram <neil@ossau.uklinux.net> + + * .cvsignore: Add lib-version.texi. + 2007-10-02 Ludovic Courtès <ludo@gnu.org> * slib.texi (SLIB installation): Don't recommend using the site @@ -129,7 +279,7 @@ (lib-version.texi): New target. * guile.texi: Include `lib-version.texi'. - + * api-data.texi (Conversion): Link to `The ice-9 i18n Module' when describing `string->number'. (String Comparison): Likewise. @@ -317,7 +467,7 @@ * api-debug.texi (Debug on Error): Note need to handling of errors in C. - + * api-debug.texi (Debugging): New intro text. New subsection "Evaluation Model". Moved existing subsections "Capturing the Stack or Innermost Stack Frame", "Examining the Stack", "Examining @@ -353,7 +503,7 @@ * api-evaluation.texi (Fly Evaluation): Add scm_c_eval_string. (Loading): Add scm_c_primitive_load. Reported by Jon Wilson. - + 2006-06-25 Kevin Ryde <user42@zip.com.au> * posix.texi (Time): In tm:gmtoff, give example values, note not the @@ -487,7 +637,7 @@ * api-data.texi (Operations Related to Symbols): Documented `scm_take_locale_symbol ()'. - + 2005-12-15 Kevin Ryde <user42@zip.com.au> * api-evaluation.texi (Fly Evaluation): Add scm_call_4, suggested by @@ -578,7 +728,7 @@ * misc-modules.texi (Formatted Output): Show modifiers like ~:d instead of in words. - + 2005-08-06 Kevin Ryde <user42@zip.com.au> * api-compound.texi (List Modification): In filter, return may share a @@ -925,7 +1075,7 @@ * api-i18n.texi: New file. * Makefile.am (guile_TEXINFOS): Added it. * guile.texi: Include it. - + 2004-09-16 Kevin Ryde <user42@zip.com.au> * api-utility.texi (Equality): Revise for clarity. @@ -980,16 +1130,16 @@ Ran a (docstring-process-module "(guile)") and moved entries from new-docstrings.texi to their appropriate place. - + * api-undocumented.texi: New file. 2004-08-21 Marius Vollmer <mvo@zagadka.de> From Richard Todd, Thanks! - + * scheme-scripts.texi (Invoking Guile): documented new '-L' switch. - + 2004-08-20 Marius Vollmer <mvo@zagadka.de> * gh.texi: Updated transition section with new recommended things. @@ -1000,7 +1150,7 @@ mutation-sharing substrings. (Symbols): Document scm_from_locale_symbol and scm_from_locale_symboln. - + 2004-08-18 Kevin Ryde <user42@zip.com.au> * posix.texi (Network Sockets and Communication): Add SOCK_RDM and @@ -1062,7 +1212,7 @@ scm_is_complex, scm_is_number, scm_c_make_rectangular, scm_c_make_polar, scm_c_real_part, scm_c_imag_part, scm_c_magnitude, and scm_c_angle. - + 2004-08-02 Marius Vollmer <marius.vollmer@uni-dortmund.de> * gh.texi: Replaced references to scm_num2* with scm_to_* and @@ -1098,7 +1248,7 @@ * api-deprecated.texi: Removed. * intro.texi (Discouraged and Deprecated): General information about deprecation, etc. - + 2004-07-30 Marius Vollmer <marius.vollmer@uni-dortmund.de> * misc-modules.texi (Formatted Output): Changed @w to @w{} in @@ -1183,7 +1333,7 @@ * Makefile.am (CLEANFILES): Remove guile.cps guile.fns guile.rns guile.tps guile.vrs guile.tmp, cleaned by automake these days. - + 2004-05-06 Marius Vollmer <marius.vollmer@uni-dortmund.de> * scheme-smobs.texi: Updated for new SCM_SMOB_* macros. @@ -1266,7 +1416,7 @@ * scheme-control.texi (while do): Expand and clarify `do', in particular note iteration binds fresh locations, rather than values "stored". - + * srfi-modules.texi (SRFI-4): Revise for clarity, give each function explicitly rather than showing TAG so Emacs info-look can find them, merge "SRFI-4 - Read Syntax" and "SRFI-4 - Procedures" into just one @@ -1296,7 +1446,7 @@ 2004-01-21 Marius Vollmer <mvo@zagadka.de> Added copyright notices to all TeXinfo files. - + * fdl.texi: New. * guile.texi: Include it as an appendix. * preface.texi: State that the manual is FDL. @@ -1318,7 +1468,7 @@ * misc-modules.texi (Queues): New chapter. * guile.texi (Top): Add it. - + 2004-01-09 Kevin Ryde <user42@zip.com.au> * scheme-compound.texi (Bit Vectors): Revise for clarity, following @@ -1373,7 +1523,7 @@ * scheme-data.texi: Include exact rationals. From Stephen Compall. Thanks! - + * intro.texi (What is Guile?): Add @acronym for POSIX, R5RS, GUI, and HTTP. Conclude linking libguile. Say what one can find *for*. @@ -1454,7 +1604,7 @@ * data-rep.texi, scheme-memory.texi (scm_remember_upto_here_1, scm_remember_upto_here_2): Moved from data-rep.texi to scheme-memory.texi. - + 2003-10-02 Kevin Ryde <user42@zip.com.au> * scheme-io.texi (String Ports): In call-with-output-string, note proc @@ -1785,7 +1935,7 @@ remainder and modulo round their results. * scheme-io.texi (Reading): In read-char and peek-char, fix typos "?" - in @rnindex. In port-column, use @: after i.e. + in @rnindex. In port-column, use @: after i.e. (Writing): In get-print-state, two spaces after full stop. Add write, revise display. @@ -1804,7 +1954,7 @@ 2003-04-30 Marius Vollmer <marius.vollmer@uni-dortmund.de> - * posix.texi (scm_c_port_for_each): Added. + * posix.texi (scm_c_port_for_each): Added. 2003-04-26 Neil Jerram <neil@ossau.uklinux.net> @@ -1935,7 +2085,7 @@ Configuration. The following doc updates are from Ian Sheldon - thanks! - + * scheme-data.texi (Appending Strings, Regexp Functions, Match Structures): Add examples. (Regular Expressions): Add instruction to use (ice-9 regex) @@ -1973,7 +2123,7 @@ * intro.texi: Updated GNu ftp server name. Use "-lguile" instead of "libguile.a". Some small fixes/improvements. - + * scheme-reading.texi: Added www.schemers.org. Removed foldoc, it's too generic. Updated 'teach yourself ...' URL. @@ -1984,7 +2134,7 @@ 2002-08-14 Marius Vollmer <mvo@zagadka.ping.de> - * scheme-evaluation.texi (eval-string): Updated. + * scheme-evaluation.texi (eval-string): Updated. * scheme-scheduling.texi (Fluids): Touched up a bit, added with-fluids. @@ -2024,7 +2174,7 @@ * scheme-memory.texi (Memory Blocks): add scm_calloc, scm_gc_calloc. correct typos. - + 2002-08-05 Marius Vollmer <marius.vollmer@uni-dortmund.de> * intro.texi, srfi-modules.texi: Added (use-modules (ice-9 @@ -2068,7 +2218,7 @@ rather than deprecated section. Hence this change. Added `@deftp' for scm_t_bits data type so that a proper index entry is added for this. Thanks to Richard Y. Kim! - + * data-rep.texi (Subrs): Changed scm_make_gsubr to scm_c_define_gsubr. Thanks to Richard Y. Kim! @@ -2105,13 +2255,13 @@ * scheme-debug.texi (Debugging): Rename chapter `Debugging Infrastructure' and reorganize its contents. - + * scheme-debug.texi (Debugging), scheme-control.texi (Handling Errors): Move display-error to error-focussed section. * scheme-debug.texi (Debugging), debugging.texi (Backtrace): Move backtrace to user-level debugging chapter. - + * scheme-debug.texi (Debugging), scheme-procedures.texi (Procedure Properties): Move procedure-name, procedure-source and procedure-environment to procedures chapter. @@ -2194,7 +2344,7 @@ * scheme-utility.texi (Hooks): Further updates. New material on GC hooks. - + * scheme-evaluation.texi (Fly Evaluation): Note disappearance of eval2 and read-and-eval!. diff --git a/doc/ref/Makefile.am b/doc/ref/Makefile.am index 6ab2171af..60e23c27d 100644 --- a/doc/ref/Makefile.am +++ b/doc/ref/Makefile.am @@ -1,6 +1,6 @@ ## Process this file with Automake to create Makefile.in ## -## Copyright (C) 1998, 2004, 2006 Free Software Foundation, Inc. +## Copyright (C) 1998, 2004, 2006, 2008 Free Software Foundation, Inc. ## ## This file is part of GUILE. ## @@ -86,7 +86,8 @@ include $(top_srcdir)/am/pre-inst-guile autoconf.texi: autoconf-macros.texi autoconf-macros.texi: $(top_srcdir)/guile-config/guile.m4 - $(preinstguiletool)/snarf-guile-m4-docs $< > $(srcdir)/$@ + $(preinstguiletool)/snarf-guile-m4-docs $(top_srcdir)/guile-config/guile.m4 \ + > $(srcdir)/$@ lib-version.texi: $(top_srcdir)/GUILE-VERSION cat "$^" | grep '^LIBGUILE_.*_MAJOR' | \ diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi index 41bb9ac9c..e1db2a612 100755 --- a/doc/ref/api-data.texi +++ b/doc/ref/api-data.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Guile Reference Manual. -@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007 +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008 @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @@ -1733,6 +1733,46 @@ The global random state used by the above functions when the @var{state} parameter is not given. @end defvar +Note that the initial value of @code{*random-state*} is the same every +time Guile starts up. Therefore, if you don't pass a @var{state} +parameter to the above procedures, and you don't set +@code{*random-state*} to @code{(seed->random-state your-seed)}, where +@code{your-seed} is something that @emph{isn't} the same every time, +you'll get the same sequence of ``random'' numbers on every run. + +For example, unless the relevant source code has changed, @code{(map +random (cdr (iota 30)))}, if the first use of random numbers since +Guile started up, will always give: + +@lisp +(map random (cdr (iota 19))) +@result{} +(0 1 1 2 2 2 1 2 6 7 10 0 5 3 12 5 5 12) +@end lisp + +To use the time of day as the random seed, you can use code like this: + +@lisp +(let ((time (gettimeofday))) + (set! *random-state* + (seed->random-state (+ (car time) + (cdr time))))) +@end lisp + +@noindent +And then (depending on the time of day, of course): + +@lisp +(map random (cdr (iota 19))) +@result{} +(0 0 1 0 2 4 5 4 5 5 9 3 10 1 8 3 14 17) +@end lisp + +For security applications, such as password generation, you should use +more bits of seed. Otherwise an open source password generator could +be attacked by guessing the seed@dots{} but that's a subject for +another manual. + @node Characters @subsection Characters @@ -4607,6 +4647,11 @@ immediately after creating the Scheme string. In certain cases, Guile can then use @var{str} directly as its internal representation. @end deftypefn +The size of a symbol can also be obtained from C: + +@deftypefn {C Function} size_t scm_c_symbol_length (SCM sym) +Return the number of characters in @var{sym}. +@end deftypefn Finally, some applications, especially those that generate new Scheme code dynamically, need to generate symbols for use in the generated @@ -4861,7 +4906,7 @@ makes them easy to type. Guile's keyword support conforms to R5RS, and adds a (switchable) read syntax extension to permit keywords to begin with @code{:} as well as -@code{#:}. +@code{#:}, or to end with @code{:}. @menu * Why Use Keywords?:: Motivation for keyword usage. @@ -5006,9 +5051,16 @@ If the @code{keyword} read option is set to @code{'prefix}, Guile also recognizes the alternative read syntax @code{:NAME}. Otherwise, tokens of the form @code{:NAME} are read as symbols, as required by R5RS. +@cindex SRFI-88 keyword syntax + +If the @code{keyword} read option is set to @code{'postfix}, Guile +recognizes the SRFI-88 read syntax @code{NAME:} (@pxref{SRFI-88}). +Otherwise, tokens of this form are read as symbols. + To enable and disable the alternative non-R5RS keyword syntax, you use the @code{read-set!} procedure documented in @ref{User level options -interfaces} and @ref{Reader options}. +interfaces} and @ref{Reader options}. Note that the @code{prefix} and +@code{postfix} syntax are mutually exclusive. @smalllisp (read-set! keywords 'prefix) @@ -5021,6 +5073,16 @@ interfaces} and @ref{Reader options}. @result{} #:type +(read-set! keywords 'postfix) + +type: +@result{} +#:type + +:type +@result{} +:type + (read-set! keywords #f) #:type diff --git a/doc/ref/api-debug.texi b/doc/ref/api-debug.texi index 68c202266..d99a56724 100644 --- a/doc/ref/api-debug.texi +++ b/doc/ref/api-debug.texi @@ -8,6 +8,7 @@ @node Debugging @section Debugging Infrastructure +@cindex Debugging In order to understand Guile's debugging facilities, you first need to understand a little about how the evaluator works and what the Scheme stack is. With that in place we explain the low level trap calls that @@ -17,9 +18,9 @@ infrastructure that builds on top of those calls. @menu * Evaluation Model:: Evaluation and the Scheme stack. * Debug on Error:: Debugging when an error occurs. -* Low Level Trap Calls:: -* High Level Traps:: +* Traps:: * Breakpoints:: +* Debugging Examples:: @end menu @node Evaluation Model @@ -610,65 +611,8 @@ Invoke the Guile debugger to explore the context of the last error. @end deffn -@node Low Level Trap Calls -@subsection Low Level Trap Calls - -@cindex Low level trap calls -@cindex Evaluator trap calls -Guile's evaluator can be configured to call the following four user-specified -procedures at various points in its operation. - -@table @dfn -@item apply-frame-handler -@item enter-frame-handler -@item exit-frame-handler -@item memoize-symbol-handler -@end table - -These procedures, and the circumstances under which the evaluator -calls them, are configured by the ``evaluator trap options'' interface -(@pxref{Evaluator trap options}), and by the @code{trace} and -@code{breakpoints} fields of the ``debug options'' interface -(@pxref{Debugger options}). - -It is not necessary to understand the fine details of these low level -calls, and of the options which configure them, in order to use the -class-based trap interface effectively. @code{guile-debugging} takes -care of setting these options as required for whatever set of -installed trap objects the user specifies.@footnote{And consequently, -when using the class-based trap interface, users/applications should -@emph{not} modify these options themselves, to avoid interfering with -@code{guile-debugging}'s option settings.} It is useful, though, to -have a overall idea of how the evaluator works and when these low -level calls can happen, as follows. - -@cindex Frame entry -@cindex Frame exit -On the basis of this description, we can now specify the points where -low level trap calls may occur (subject to configuration). Namely, -whenever a new frame is added to the stack, because the evaluator is -about to begin a new evaluation or to perform a new application, and -whenever a frame is being removed from the stack because the -computation that it refers to has completed and is returning its -value@footnote{If this raises the question of how expressions with -no return value are handled, the answer is that all computations in -Guile return a value. Those that appear to have no return value do so -by using the special @code{*unspecified*} value, which the Guile REPL -avoids displaying to the user.} to its caller. - -@deffn {Scheme Procedure} with-traps thunk -@deffnx {C Function} scm_with_traps (thunk) -Call @var{thunk} with traps enabled. -@end deffn - -@deffn {Scheme Procedure} debug-object? obj -@deffnx {C Function} scm_debug_object_p (obj) -Return @code{#t} if @var{obj} is a debug object. -@end deffn - - -@node High Level Traps -@subsection High Level Traps +@node Traps +@subsection Traps @cindex Traps @cindex Evaluator trap calls @@ -678,29 +622,33 @@ Return @code{#t} if @var{obj} is a debug object. @cindex Code coverage @cindex Profiling The low level C code of Guile's evaluator can be configured to call -out at key points to arbitrary user-specified code. In principle this -allows Scheme code to implement any model it chooses for examining the -evaluation stack as program execution proceeds, and for suspending -execution to be resumed later. Possible applications of this feature -include breakpoints, runtime tracing, code coverage, and profiling. +out at key points to arbitrary user-specified procedures. These +procedures, and the circumstances under which the evaluator calls +them, are configured by the ``evaluator trap options'' interface +(@pxref{Evaluator trap options}), and by the @code{trace} and +@code{breakpoints} fields of the ``debug options'' interface +(@pxref{Debugger options}). In principle this allows Scheme code to +implement any model it chooses for examining the evaluation stack as +program execution proceeds, and for suspending execution to be resumed +later. Possible applications of this feature include breakpoints, +runtime tracing, code coverage, and profiling. @cindex Trap classes @cindex Trap objects -Based on these low level trap calls, the enhancements described here -provide a much higher level, object-oriented interface for the -manipulation of traps. Different kinds of trap are represented as -GOOPS classes; for example, the @code{<procedure-trap>} class -describes traps that are triggered by invocation of a specified -procedure. A particular instance of a trap class --- or @dfn{trap -object} --- describes the condition under which a single trap will be -triggered, and what will happen then; for example, an instance of -@code{<procedure-trap>} whose @code{procedure} and @code{behaviour} -slots contain @code{my-factorial} and @code{debug-trap} would be a -trap that enters the command line debugger when the -@code{my-factorial} procedure is invoked. - -The following subsubsections describe all this in greater detail, for both -the user wanting to use traps, and the developer interested in +Based on these low level trap calls, Guile provides a higher level, +object-oriented interface for the manipulation of traps. Different +kinds of trap are represented as GOOPS classes; for example, the +@code{<procedure-trap>} class describes traps that are triggered by +invocation of a specified procedure. A particular instance of a trap +class --- or @dfn{trap object} --- describes the condition under which +a single trap will be triggered, and what will happen then; for +example, an instance of @code{<procedure-trap>} whose @code{procedure} +and @code{behaviour} slots contain @code{my-factorial} and +@code{debug-trap} would be a trap that enters the command line +debugger when the @code{my-factorial} procedure is invoked. + +The following subsections describe all this in detail, for both the +user wanting to use traps, and the developer interested in understanding how the interface hangs together. @@ -813,8 +761,8 @@ shorthands for setting common kinds of traps. @xref{Trap Shorthands}, for some examples. The ability to install, uninstall and reinstall a trap without losing -its definition is @code{guile-debugging}'s equivalent of the -disable/enable commands provided by debuggers like GDB. +its definition is Guile's equivalent of the disable/enable commands +provided by debuggers like GDB. @deffn {Generic Function} install-trap trap Install the trap object @var{trap}, so that its behaviour will be @@ -832,9 +780,9 @@ met. @subsubsection Specifying Trap Behaviour @cindex Trap behaviour -@code{guile-debugging} provides several ``out-of-the-box'' behaviours -for common needs. All of the following can be used directly as the -value of the @code{#:behaviour} option when creating a trap object. +Guile provides several ``out-of-the-box'' behaviours for common needs. +All of the following can be used directly as the value of the +@code{#:behaviour} option when creating a trap object. @deffn {Procedure} debug-trap trap-context Enter Guile's command line debugger to explore the stack at @@ -1179,9 +1127,9 @@ guile> (rev '(a b c)) @node Tracing and (ice-9 debug) @subsubsection Tracing and (ice-9 debug) -The @code{(ice-9 debug)} module of the core Guile distribution -provides a tracing facility that is roughly similar to that described -here, but there are important differences. +The @code{(ice-9 debug)} module provides a tracing facility +(@pxref{Tracing}) that is roughly similar to that described here, but +there are important differences. @itemize @bullet @item @@ -1202,35 +1150,30 @@ in stack depth, by using indentation like this: @end lisp However its output can @emph{only} show the information seen here, -which corresponds to @code{guile-debugging}'s @code{trace/info} -procedure; it cannot be configured to show other pieces of information -about the trap context in the way that @code{guile-debugging}'s trace -feature can. +which corresponds to @code{(ice-9 debugging trace)}'s +@code{trace/info} procedure; it cannot be configured to show other +pieces of information about the trap context in the way that the +@code{(ice-9 debugging trace)} implementation can. @item The @code{(ice-9 debug)} trace only allows the tracing of procedure -applications and their return values, whereas @code{guile-debugging}'s -trace allows any kind of trap to be traced. +applications and their return values, whereas the @code{(ice-9 debugging +trace)} implementation allows any kind of trap to be traced. It's interesting to note that @code{(ice-9 debug)}'s restriction here, which might initially appear to be just a straightforward consequence of its implementation, is also somewhat dictated by its pictorial display. The use of indentation in the output relies on hooking into the low level trap calls in such a way that the trapped application -entries and exits exactly balance each other. -@code{guile-debugging}'s more general traps interface allows traps to -be installed such that entry and exit traps don't necessarily balance, -which means that, in general, indentation diagrams like the one above -don't work. +entries and exits exactly balance each other. The @code{ice-9 +debugging trace} implementation allows traps to be installed such that +entry and exit traps don't necessarily balance, which means that, in +general, indentation diagrams like the one above don't work. @end itemize It isn't currently possible to use both @code{(ice-9 debug)} trace and -@code{guile-debugging} in the same Guile session, because their settings -of the low level trap options conflict with each other. (It should be -possible to fix this, by modifying @code{(ice-9 debug)} to use -@code{guile-debugging}'s trap installation interface, but only if and -when @code{guile-debugging} is integrated into the core Guile -distribution.) +@code{(ice-9 debugging trace)} in the same Guile session, because +their settings of the low level trap options conflict with each other. @node Traps Installing More Traps @@ -1456,9 +1399,9 @@ user would intuitively think of as single-stepping through their code, either through code in general (roughly corresponding to GDB's @code{step} command, for example), or through code from a particular source file (roughly corresponding to GDB's @code{next}). Therefore -if you are using @code{guile-debugging} to single-step through code -and finding its behaviour counter-intuitive, please let me know so -that I can improve it. +if you are using a step trap to single-step through code and finding +its behaviour counter-intuitive, please report that so we can improve +it. The implementation and options of the @code{<step-trap>} class are complicated by the fact that it is unreliable to determine whether a @@ -1620,16 +1563,16 @@ following subsubsection. @subsubsection Location Traps The @code{<location-trap>} class implements traps that are triggered -by evaluation of code at a specific source location or within a -specified range of source locations. When compared with source traps, -they are easier to set, and do not become irrelevant when the relevant -code is reloaded; but unfortunately they are considerably less -efficient, as they require running some ``are we in the right place -for a trap'' code on every low level frame entry trap call. +by evaluation of code at a specific source location. When compared +with source traps, they are easier to set, and do not become +irrelevant when the relevant code is reloaded; but unfortunately they +are a lot less efficient, as they require running some ``are we in the +right place for a trap'' code on every low level frame entry trap +call. @deffn {Class} <location-trap> Class for traps triggered by evaluation of code at a specific source -location or in a specified range of source locations. +location. @end deffn @deffn {Trap Option} #:file-regexp regexp @@ -1637,31 +1580,27 @@ A regular expression specifying the filenames that will match this trap. This option must be specified when creating a location trap. @end deffn -@deffn {Trap Option} #:line line-spec -If specified, @var{line-spec} describes either a single line, in which -case it is a single integer, or a range of lines, in which case it is -a pair of the form @code{(@var{min-line} . @var{max-line})}. All line -numbers are 0-based, and the range form is inclusive-inclusive. If -@code{#f} or not specified, the trap is not restricted by line number. -(Default value @code{#f}.) +@deffn {Trap Option} #:line line +The line number (0-based) of the source location at which the trap +should be triggered. This option must be specified when creating a +location trap. @end deffn -@deffn {Trap Option} #:column column-spec -If specified, @var{column-spec} describes either a single column, in -which case it is a single integer, or a range of columns, in which -case it is a pair of the form @code{(@var{min-column} -. @var{max-column})}. All column numbers are 0-based, and the range -form is inclusive-inclusive. If @code{#f} or not specified, the trap -is not restricted by column number. (Default value @code{#f}.) +@deffn {Trap Option} #:column column +The column number (0-based) of the source location at which the trap +should be triggered. This option must be specified when creating a +location trap. @end deffn @noindent -Example: +Here is an example, which matches the @code{(facti (- n 1) (* a n))} +expression in @file{ice-9/debugging/example-fns.scm}: @lisp (install-trap (make <location-trap> #:file-regexp "example-fns.scm" - #:line '(11 . 13) + #:line 11 + #:column 6 #:behaviour gds-debug-trap)) @end lisp @@ -1672,8 +1611,7 @@ Example: If the code described in the preceding subsubsections for creating and manipulating traps seems a little long-winded, it is of course possible to define more convenient shorthand forms for typical usage -patterns. For example, my own @file{.guile} file contains the -following definitions for setting breakpoints and for tracing. +patterns. Here are some examples. @lisp (define (break! proc) @@ -1694,11 +1632,11 @@ following definitions for setting breakpoints and for tracing. trace-until-exit)))) @end lisp -Definitions like these are not provided out-of-the-box by -@code{guile-debugging}, because different users will have different -ideas about what their default debugger should be, or, for example, -which of the common trap options (@pxref{Common Trap Options}) it -might be useful to expose through such shorthand procedures. +Definitions like these are not provided out-of-the-box by Guile, +because different users will have different ideas about what their +default debugger should be, or, for example, which of the common trap +options (@pxref{Common Trap Options}) it might be useful to expose +through such shorthand procedures. @node Trap Utilities @@ -1760,12 +1698,11 @@ While they are an important piece of infrastructure, and directly usable in some scenarios, traps are still too low level to meet some of the requirements of interactive development. -For example, in my experience a common scenario is that a newly -written procedure is not working properly, and so you'd like to be -able to step or trace through its code to find out why. Ideally this -should be possible from the IDE and without having to modify the -source code. There are two problems with using traps directly in this -scenario. +A common scenario is that a newly written procedure is not working +properly, and so you'd like to be able to step or trace through its +code to find out why. Ideally this should be possible from the IDE +and without having to modify the source code. There are two problems +with using traps directly in this scenario. @enumerate @item @@ -1885,6 +1822,216 @@ be managed through GDS. For the details of GDS's breakpoints interface, see @ref{Setting and Managing Breakpoints}. +@node Debugging Examples +@subsection Debugging Examples + +Here we present some examples of what you can do with the debugging +facilities just described. + +@menu +* Single Stepping through a Procedure's Code:: +* Profiling or Tracing a Procedure's Code:: +@end menu + + +@node Single Stepping through a Procedure's Code +@subsubsection Single Stepping through a Procedure's Code + +A good way to explore in detail what a Scheme procedure does is to set +a trap on it and then single step through what it does. To do this, +make and install a @code{<procedure-trap>} with the @code{debug-trap} +behaviour from @code{(ice-9 debugging ice-9-debugger-extensions)}. + +The following sample session illustrates this. It assumes that the +file @file{matrix.scm} defines a procedure @code{mkmatrix}, which is +the one we want to explore, and another procedure @code{do-main} which +calls @code{mkmatrix}. + +@lisp +$ /usr/bin/guile -q +guile> (use-modules (ice-9 debugger) + (ice-9 debugging ice-9-debugger-extensions) + (ice-9 debugging traps)) +guile> (load "matrix.scm") +guile> (install-trap (make <procedure-trap> + #:procedure mkmatrix + #:behaviour debug-trap)) +guile> (do-main 4) +This is the Guile debugger -- for help, type `help'. +There are 3 frames on the stack. + +Frame 2 at matrix.scm:8:3 + [mkmatrix] +debug> next +Frame 3 at matrix.scm:4:3 + (let ((x 1)) (quote this-is-a-matric)) +debug> info frame +Stack frame: 3 +This frame is an evaluation. +The expression being evaluated is: +matrix.scm:4:3: + (let ((x 1)) (quote this-is-a-matric)) +debug> next +Frame 3 at matrix.scm:5:21 + (quote this-is-a-matric) +debug> bt +In unknown file: + ?: 0* [primitive-eval (do-main 4)] +In standard input: + 4: 1* [do-main 4] +In matrix.scm: + 8: 2 [mkmatrix] + ... + 5: 3 (quote this-is-a-matric) +debug> quit +this-is-a-matric +guile> +@end lisp + +Or you can use Guile's Emacs interface (GDS), by using the module +@code{(ice-9 gds-client)} instead of @code{(ice-9 debugger)} and +@code{(ice-9 debugging ice-9-debugger-extensions)}, and changing +@code{debug-trap} to @code{gds-debug-trap}. Then the stack and +corresponding source locations are displayed in Emacs instead of on +the Guile command line. + + +@node Profiling or Tracing a Procedure's Code +@subsubsection Profiling or Tracing a Procedure's Code + +What if you wanted to get a trace of everything that the Guile +evaluator does within a given procedure, but without Guile stopping +and waiting for your input at every step? For this requirement you +can install a trap on the procedure, as in the previous example, but +instead of @code{debug-trap} or @code{gds-debug-trap}, use the +@code{trace-trap} and @code{trace-until-exit} behaviours provided by +the @code{(ice-9 debugging trace)} module. + +@lisp +guile> (use-modules (ice-9 debugging traps) (ice-9 debugging trace)) +guile> (load "matrix.scm") +guile> (install-trap (make <procedure-trap> + #:procedure mkmatrix + #:behaviour (list trace-trap trace-until-exit))) +guile> (do-main 4) +| 2: [mkmatrix] +| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> define #f] +| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> define #f] +| 4: (and (memq sym bindings) (let ...)) +| 5: (memq sym bindings) +| 5: [memq define (debug)] +| 5: =>#f +| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> define #f] +| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> define #f] +| 4: (and (memq sym bindings) (let ...)) +| 5: (memq sym bindings) +| 5: [memq define (debug)] +| 5: =>#f +| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> let #f] +| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> let #f] +| 4: (and (memq sym bindings) (let ...)) +| 5: (memq sym bindings) +| 5: [memq let (debug)] +| 5: =>#f +| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> let #f] +| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> let #f] +| 4: (and (memq sym bindings) (let ...)) +| 5: (memq sym bindings) +| 5: [memq let (debug)] +| 5: =>#f +| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> let #f] +| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> let #f] +| 4: (and (memq sym bindings) (let ...)) +| 5: (memq sym bindings) +| 5: [memq let (debug)] +| 5: =>#f +| 2: (letrec ((yy 23)) (let ((x 1)) (quote this-is-a-matric))) +| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> let #f] +| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> let #f] +| 4: (and (memq sym bindings) (let ...)) +| 5: (memq sym bindings) +| 5: [memq let (debug)] +| 5: =>#f +| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> let #f] +| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> let #f] +| 4: (and (memq sym bindings) (let ...)) +| 5: (memq sym bindings) +| 5: [memq let (debug)] +| 5: =>#f +| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> let #f] +| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> let #f] +| 4: (and (memq sym bindings) (let ...)) +| 5: (memq sym bindings) +| 5: [memq let (debug)] +| 5: =>#f +| 2: (let ((x 1)) (quote this-is-a-matric)) +| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> let #f] +| 3: [#<procedure #f (a sym definep)> #<autoload # b7c93870> let #f] +| 4: (and (memq sym bindings) (let ...)) +| 5: (memq sym bindings) +| 5: [memq let (debug)] +| 5: =>#f +| 2: [let (let # #) (# # #)] +| 2: [let (let # #) (# # #)] +| 2: =>(#@@let* (x 1) #@@let (quote this-is-a-matric)) +this-is-a-matric +guile> (do-main 4) +| 2: [mkmatrix] +| 2: (letrec ((yy 23)) (let* ((x 1)) (quote this-is-a-matric))) +| 2: (let* ((x 1)) (quote this-is-a-matric)) +| 2: (quote this-is-a-matric) +| 2: =>this-is-a-matric +this-is-a-matric +guile> +@end lisp + +This example shows the default configuration for how each line of trace +output is formatted, which is: + +@itemize +@item +the character @code{|}, a visual clue that the line is a line of trace +output, followed by + +@item +a number indicating the real evaluator stack depth (where ``real'' means +not counting tail-calls), followed by + +@item +a summary of the expression being evaluated (@code{(@dots{})}), the +procedure being called (@code{[@dots{}]}), or the value being returned +from an evaluation or procedure call (@code{=>@dots{}}). +@end itemize + +@noindent +You can customize @code{(ice-9 debugging trace)} to show different +information in each trace line using the @code{set-trace-layout} +procedure. The next example shows how to get the source location in +each trace line instead of the stack depth. + +@lisp +guile> (set-trace-layout "|~16@@a: ~a\n" trace/source trace/info) +guile> (do-main 4) +| matrix.scm:7:2: [mkmatrix] +| : (letrec ((yy 23)) (let* ((x 1)) (quote this-is-a-matric))) +| matrix.scm:3:2: (let* ((x 1)) (quote this-is-a-matric)) +| matrix.scm:4:4: (quote this-is-a-matric) +| matrix.scm:4:4: =>this-is-a-matric +this-is-a-matric +guile> +@end lisp + +(For anyone wondering why the first @code{(do-main 4)} call above +generates lots more trace lines than the subsequent calls: these +examples also demonstrate how the Guile evaluator ``memoizes'' code. +When Guile evaluates a source code expression for the first time, it +changes some parts of the expression so that they will be quicker to +evaluate when that expression is evaluated again; this is called +memoization. The trace output from the first @code{(do-main 4)} call +shows memoization steps, such as an internal define being transformed to +a letrec.) + + @c Local Variables: @c TeX-master: "guile.texi" @c End: diff --git a/doc/ref/api-modules.texi b/doc/ref/api-modules.texi index 415c9cba6..9aeb08a44 100644 --- a/doc/ref/api-modules.texi +++ b/doc/ref/api-modules.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Guile Reference Manual. -@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007 +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2008 @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @@ -329,12 +329,12 @@ Signal error if module name is not resolvable. @c FIXME::martin: Is this correct, and is there more to say? -@c FIXME::martin: Define term and concept `system transformer' somewhere. +@c FIXME::martin: Define term and concept `syntax transformer' somewhere. @deffn syntax use-syntax module-name -Load the module @code{module-name} and use its system -transformer as the system transformer for the currently defined module, -as well as installing it as the current system transformer. +Load the module @code{module-name} and use its syntax +transformer as the syntax transformer for the currently defined module, +as well as installing it as the current syntax transformer. @end deffn @deffn syntax @@ module-name binding-name @@ -679,7 +679,7 @@ Guile starts up. @item (ice-9 debug) Mikael Djurfeldt's source-level debugging support for Guile -(@pxref{Debugging Features}). +(@pxref{Tracing}). @item (ice-9 expect) Actions based on matching input from a port (@pxref{Expect}). diff --git a/doc/ref/api-options.texi b/doc/ref/api-options.texi index 493e2385d..c6ce34623 100644 --- a/doc/ref/api-options.texi +++ b/doc/ref/api-options.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Guile Reference Manual. -@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006 +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2008 @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @@ -491,7 +491,7 @@ Here is the list of reader options generated by typing values. @smalllisp -keywords #f Style of keyword recognition: #f or 'prefix +keywords #f Style of keyword recognition: #f, 'prefix or 'postfix case-insensitive no Convert symbols to lower case. positions yes Record positions of source code expressions. copy no Copy source code expressions. @@ -613,7 +613,6 @@ way. @var{retval} is the return value. @end deffn - @deffn memoize-symbol-handler key cont expression env Called when the evaluator memoizes the value of a procedure symbol @@ -626,6 +625,16 @@ way. @var{retval} is the return value. @end deffn +@deffn {Scheme Procedure} with-traps thunk +@deffnx {C Function} scm_with_traps (thunk) +Call @var{thunk} with traps enabled. +@end deffn + +@deffn {Scheme Procedure} debug-object? obj +@deffnx {C Function} scm_debug_object_p (obj) +Return @code{#t} if @var{obj} is a debug object. +@end deffn + @node Debugger options @subsubsection Debugger options @@ -720,7 +729,7 @@ ABORT: (misc-error) Type "(backtrace)" to get more information. guile> (read-options 'help) -keywords #f Style of keyword recognition: #f or 'prefix +keywords #f Style of keyword recognition: #f, 'prefix or 'postfix case-insensitive no Convert symbols to lower case. positions yes Record positions of source code expressions. copy no Copy source code expressions. diff --git a/doc/ref/api-scheduling.texi b/doc/ref/api-scheduling.texi index 1eaafc48d..3b622868c 100644 --- a/doc/ref/api-scheduling.texi +++ b/doc/ref/api-scheduling.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Guile Reference Manual. -@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004 +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007 @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @@ -90,8 +90,8 @@ execution and triggering this execution. They will not be executed automatically. @menu -* System asyncs:: -* User asyncs:: +* System asyncs:: +* User asyncs:: @end menu @node System asyncs @@ -267,11 +267,24 @@ Once @var{body} or @var{handler} returns, the return value is made the @emph{exit value} of the thread and the thread is terminated. @end deftypefn +@deffn {Scheme Procedure} thread? obj +@deffnx {C Function} scm_thread_p (obj) +Return @code{#t} iff @var{obj} is a thread; otherwise, return +@code{#f}. +@end deffn + @c begin (texi-doc-string "guile" "join-thread") -@deffn {Scheme Procedure} join-thread thread +@deffn {Scheme Procedure} join-thread thread [timeout [timeoutval]] +@deffnx {C Function} scm_join_thread (thread) +@deffnx {C Function} scm_join_thread_timed (thread, timeout, timeoutval) Wait for @var{thread} to terminate and return its exit value. Threads that have not been created with @code{call-with-new-thread} or -@code{scm_spawn_thread} have an exit value of @code{#f}. +@code{scm_spawn_thread} have an exit value of @code{#f}. When +@var{timeout} is given, it specifies a point in time where the waiting +should be aborted. It can be either an integer as returned by +@code{current-time} or a pair as returned by @code{gettimeofday}. +When the waiting is aborted, @var{timeoutval} is returned (if it is +specified; @code{#f} is returned otherwise). @end deffn @deffn {Scheme Procedure} thread-exited? thread @@ -285,6 +298,42 @@ If one or more threads are waiting to execute, calling yield forces an immediate context switch to one of them. Otherwise, yield has no effect. @end deffn +@deffn {Scheme Procedure} cancel-thread thread +@deffnx {C Function} scm_cancel_thread (thread) +Asynchronously notify @var{thread} to exit. Immediately after +receiving this notification, @var{thread} will call its cleanup handler +(if one has been set) and then terminate, aborting any evaluation that +is in progress. + +Because Guile threads are isomorphic with POSIX threads, @var{thread} +will not receive its cancellation signal until it reaches a cancellation +point. See your operating system's POSIX threading documentation for +more information on cancellation points; note that in Guile, unlike +native POSIX threads, a thread can receive a cancellation notification +while attempting to lock a mutex. +@end deffn + +@deffn {Scheme Procedure} set-thread-cleanup! thread proc +@deffnx {C Function} scm_set_thread_cleanup_x (thread, proc) +Set @var{proc} as the cleanup handler for the thread @var{thread}. +@var{proc}, which must be a thunk, will be called when @var{thread} +exits, either normally or by being canceled. Thread cleanup handlers +can be used to perform useful tasks like releasing resources, such as +locked mutexes, when thread exit cannot be predicted. + +The return value of @var{proc} will be set as the @emph{exit value} of +@var{thread}. + +To remove a cleanup handler, pass @code{#f} for @var{proc}. +@end deffn + +@deffn {Scheme Procedure} thread-cleanup thread +@deffnx {C Function} scm_thread_cleanup (thread) +Return the cleanup handler currently installed for the thread +@var{thread}. If no cleanup handler is currently installed, +thread-cleanup returns @code{#f}. +@end deffn + Higher level thread procedures are available by loading the @code{(ice-9 threads)} module. These provide standardized thread creation. @@ -326,20 +375,54 @@ Acquiring requisite mutexes in a fixed order (like always A before B) in all threads is one way to avoid such problems. @sp 1 -@deffn {Scheme Procedure} make-mutex +@deffn {Scheme Procedure} make-mutex . flags @deffnx {C Function} scm_make_mutex () -Return a new standard mutex. It is initially unlocked. +@deffnx {C Function} scm_make_mutex_with_flags (SCM flags) +Return a new mutex. It is initially unlocked. If @var{flags} is +specified, it must be a list of symbols specifying configuration flags +for the newly-created mutex. The supported flags are: +@table @code +@item unchecked-unlock +Unless this flag is present, a call to `unlock-mutex' on the returned +mutex when it is already unlocked will cause an error to be signalled. + +@item allow-external-unlock +Allow the returned mutex to be unlocked by the calling thread even if +it was originally locked by a different thread. + +@item recursive +The returned mutex will be recursive. + +@end table +@end deffn + +@deffn {Scheme Procedure} mutex? obj +@deffnx {C Function} scm_mutex_p (obj) +Return @code{#t} iff @var{obj} is a mutex; otherwise, return +@code{#f}. @end deffn @deffn {Scheme Procedure} make-recursive-mutex @deffnx {C Function} scm_make_recursive_mutex () -Create a new recursive mutex. It is initialloy unlocked. +Create a new recursive mutex. It is initially unlocked. Calling this +function is equivalent to calling `make-mutex' and specifying the +@code{recursive} flag. @end deffn -@deffn {Scheme Procedure} lock-mutex mutex +@deffn {Scheme Procedure} lock-mutex mutex [timeout [owner]] @deffnx {C Function} scm_lock_mutex (mutex) -Lock @var{mutex}. If the mutex is already locked by another thread -then block and return only when @var{mutex} has been acquired. +@deffnx {C Function} scm_lock_mutex_timed (mutex, timeout, owner) +Lock @var{mutex}. If the mutex is already locked, then block and +return only when @var{mutex} has been acquired. + +When @var{timeout} is given, it specifies a point in time where the +waiting should be aborted. It can be either an integer as returned +by @code{current-time} or a pair as returned by @code{gettimeofday}. +When the waiting is aborted, @code{#f} is returned. + +When @var{owner} is given, it specifies an owner for @var{mutex} other +than the calling thread. @var{owner} may also be @code{#f}, +indicating that the mutex should be locked but left unowned. For standard mutexes (@code{make-mutex}), and error is signalled if the thread has itself already locked @var{mutex}. @@ -349,6 +432,10 @@ itself already locked @var{mutex}, then a further @code{lock-mutex} call increments the lock count. An additional @code{unlock-mutex} will be required to finally release. +If @var{mutex} was locked by a thread that exited before unlocking it, +the next attempt to lock @var{mutex} will succeed, but +@code{abandoned-mutex-error} will be signalled. + When a system async (@pxref{System asyncs}) is activated for a thread blocked in @code{lock-mutex}, the wait is interrupted and the async is executed. When the async returns, the wait resumes. @@ -367,10 +454,46 @@ If @var{mutex} is locked by some other thread then nothing is done and the return is @code{#f}. @end deffn -@deffn {Scheme Procedure} unlock-mutex mutex +@deffn {Scheme Procedure} unlock-mutex mutex [condvar [timeout]] @deffnx {C Function} scm_unlock_mutex (mutex) -Unlock @var{mutex}. An error is signalled if @var{mutex} is not -locked by the calling thread. +@deffnx {C Function} scm_unlock_mutex_timed (mutex, condvar, timeout) +Unlock @var{mutex}. An error is signalled if @var{mutex} is not locked +and was not created with the @code{unchecked-unlock} flag set, or if +@var{mutex} is locked by a thread other than the calling thread and was +not created with the @code{allow-external-unlock} flag set. + +If @var{condvar} is given, it specifies a condition variable upon +which the calling thread will wait to be signalled before returning. +(This behavior is very similar to that of +@code{wait-condition-variable}, except that the mutex is left in an +unlocked state when the function returns.) + +When @var{timeout} is also given, it specifies a point in time where +the waiting should be aborted. It can be either an integer as +returned by @code{current-time} or a pair as returned by +@code{gettimeofday}. When the waiting is aborted, @code{#f} is +returned. Otherwise the function returns @code{#t}. +@end deffn + +@deffn {Scheme Procedure} mutex-owner mutex +@deffnx {C Function} scm_mutex_owner (mutex) +Return the current owner of @var{mutex}, in the form of a thread or +@code{#f} (indicating no owner). Note that a mutex may be unowned but +still locked. +@end deffn + +@deffn {Scheme Procedure} mutex-level mutex +@deffnx {C Function} scm_mutex_level (mutex) +Return the current lock level of @var{mutex}. If @var{mutex} is +currently unlocked, this value will be 0; otherwise, it will be the +number of times @var{mutex} has been recursively locked by its current +owner. +@end deffn + +@deffn {Scheme Procedure} mutex-locked? mutex +@deffnx {C Function} scm_mutex_locked_p (mutex) +Return @code{#t} if @var{mutex} is locked, regardless of ownership; +otherwise, return @code{#f}. @end deffn @deffn {Scheme Procedure} make-condition-variable @@ -378,6 +501,12 @@ locked by the calling thread. Return a new condition variable. @end deffn +@deffn {Scheme Procedure} condition-variable? obj +@deffnx {C Function} scm_condition_variable_p (obj) +Return @code{#t} iff @var{obj} is a condition variable; otherwise, +return @code{#f}. +@end deffn + @deffn {Scheme Procedure} wait-condition-variable condvar mutex [time] @deffnx {C Function} scm_wait_condition_variable (condvar, mutex, time) Wait until @var{condvar} has been signalled. While waiting, diff --git a/doc/ref/autoconf.texi b/doc/ref/autoconf.texi index 828155c3d..83686dada 100644 --- a/doc/ref/autoconf.texi +++ b/doc/ref/autoconf.texi @@ -8,10 +8,10 @@ @node Autoconf Support @chapter Autoconf Support -When Guile is installed, a set of autoconf macros is also installed as -PREFIX/share/aclocal/guile.m4. This chapter documents the macros provided in -that file, as well as the high-level guile-tool Autofrisk. @xref{Top,The GNU -Autoconf Manual,,autoconf}, for more info. +When Guile is installed, a pkg-config description file and a set of +Autoconf macros is installed. This chapter documents pkg-config and +Autoconf support, as well as the high-level guile-tool Autofrisk. +@xref{Top,The GNU Autoconf Manual,,autoconf}, for more info. @menu * Autoconf Background:: Why use autoconf? @@ -45,7 +45,38 @@ checks. @node Autoconf Macros @section Autoconf Macros -The macro names all begin with "GUILE_". +@cindex pkg-config +@cindex autoconf + +GNU Guile provides a @dfn{pkg-config} description file, installed as +@file{@var{prefix}/lib/pkgconfig/guile-1.8.pc}, which contains all the +information necessary to compile and link C applications that use Guile. +The @code{pkg-config} program is able to read this file and provide this +information to application programmers; it can be obtained at +@url{http://pkg-config.freedesktop.org/}. + +The following command lines give respectively the C compilation and link +flags needed to build Guile-using programs: + +@example +pkg-config guile-1.8 --cflags +pkg-config guile-1.8 --libs +@end example + +To ease use of pkg-config with Autoconf, pkg-config comes with a +convenient Autoconf macro. The following example looks for Guile and +sets the @code{GUILE_CFLAGS} and @code{GUILE_LIBS} variables +accordingly, or prints an error and exits if Guile was not found: + +@findex PKG_CHECK_MODULES + +@example +PKG_CHECK_MODULES([GUILE], [guile-1.8]) +@end example + +Guile comes with additional Autoconf macros providing more information, +installed as @file{@var{prefix}/share/aclocal/guile.m4}. Their names +all begin with @code{GUILE_}. @c see Makefile.am @include autoconf-macros.texi diff --git a/doc/ref/guile.texi b/doc/ref/guile.texi index 109a50b7f..a56f95cf8 100644 --- a/doc/ref/guile.texi +++ b/doc/ref/guile.texi @@ -138,7 +138,7 @@ x @comment The title is printed in a large font. @title Guile Reference Manual @subtitle Edition @value{MANUAL-EDITION}, for use with Guile @value{VERSION} -@c @subtitle $Id: guile.texi,v 1.48 2006-11-18 18:14:55 civodul Exp $ +@c @subtitle $Id: guile.texi,v 1.49 2008-03-19 22:51:23 ossau Exp $ @c See preface.texi for the list of authors @author The Guile Developers @@ -177,6 +177,8 @@ x * Guile Modules:: +* Autoconf Support:: + Appendices * Data Representation:: All the details. @@ -222,7 +224,6 @@ etc. that make up Guile's application programming interface (API), * Guile Scripting:: How to write Guile scripts. * Using Guile Interactively:: Guile's REPL features. * Using Guile in Emacs:: Guile and Emacs. -* Debugging Features:: Features for finding errors. * Further Reading:: Where to find out more about Scheme. @end menu @@ -230,7 +231,6 @@ etc. that make up Guile's application programming interface (API), @include scheme-intro.texi @include scheme-scripts.texi @include scheme-using.texi -@include scheme-debugging.texi @include scheme-reading.texi @node Programming in C @@ -351,6 +351,7 @@ available through both Scheme and C interfaces. * Buffered Input:: Ports made from a reader function. * Expect:: Controlling interactive programs with Guile. * The Scheme shell (scsh):: Using scsh interfaces in Guile. +* Tracing:: Tracing program execution. @end menu @include slib.texi @@ -361,6 +362,9 @@ available through both Scheme and C interfaces. @include misc-modules.texi @include expect.texi @include scsh.texi +@include scheme-debugging.texi + +@include autoconf.texi @include data-rep.texi @include fdl.texi diff --git a/doc/ref/libguile-concepts.texi b/doc/ref/libguile-concepts.texi index 6fef7a79a..20c0f72ca 100644 --- a/doc/ref/libguile-concepts.texi +++ b/doc/ref/libguile-concepts.texi @@ -474,7 +474,7 @@ multiple threads using them concurrently. This means that there is no risk of the internal data structures of libguile becoming corrupted in such a way that the process crashes. -A program might still produce non-sensical results, though. Taking +A program might still produce nonsensical results, though. Taking hashtables as an example, Guile guarantees that you can use them from multiple threads concurrently and a hashtable will always remain a valid hashtable and Guile will not crash when you access it. It does not diff --git a/doc/ref/posix.texi b/doc/ref/posix.texi index f81abbc6b..a91bdb969 100644 --- a/doc/ref/posix.texi +++ b/doc/ref/posix.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Guile Reference Manual. -@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007 +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008 @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @@ -956,6 +956,11 @@ If @var{suffix} is provided, and is equal to the end of @end lisp @end deffn +@deffn {Scheme Procedure} file-exists? filename +Return @code{#t} if the file named @var{filename} exists, @code{#f} if +not. +@end deffn + @node User Information @subsection User Information @@ -1259,27 +1264,8 @@ formatting. If @code{setlocale} has been called (@pxref{Locales}), month and day names are from the current locale and in the locale character set. -Note that @samp{%Z} might print the @code{tm:zone} in @var{tm} or it -might print just the current zone (@code{tzset} above). A GNU system -prints @code{tm:zone}, a strict C99 system like NetBSD prints the -current zone. Perhaps in the future Guile will try to get -@code{tm:zone} used always. -@c -@c The issue in the above is not just whether tm_zone exists in -@c struct tm, but whether libc feels it should read it. Being a -@c non-C99 field, a strict C99 program won't know to set it, quite -@c likely leaving garbage there. NetBSD, which has the field, -@c therefore takes the view that it mustn't read it. See the PR -@c about this at -@c -@c http://www.netbsd.org/cgi-bin/query-pr-single.pl?number=21722 -@c -@c Uniformly making tm:zone used on all systems (all those which have -@c %Z at all of course) might be nice (either mung TZ and tzset, or -@c mung tzname[]). On the other hand it would make us do more than -@c C99 says, and we really don't want to get intimate with the gory -@c details of libc time funcs, no more than can be helped. -@c +Note that @samp{%Z} always ignores the @code{tm:zone} in @var{tm}; +instead it prints just the current zone (@code{tzset} above). @end deffn @deffn {Scheme Procedure} strptime format string diff --git a/doc/ref/scheme-debugging.texi b/doc/ref/scheme-debugging.texi index 32a6a46bd..07511263b 100644 --- a/doc/ref/scheme-debugging.texi +++ b/doc/ref/scheme-debugging.texi @@ -5,280 +5,8 @@ @c See the file guile.texi for copying conditions. @page -@node Debugging Features -@section Debugging Features - -Guile includes debugging tools to help you work out what is going wrong -when a program signals an error or behaves differently to how you would -expect. This chapter describes how to use these tools. - -Broadly speaking, Guile's debugging support allows you to do two things: - -@itemize @bullet -@item -specify @dfn{breakpoints} --- points in the execution of a program where -execution should pause so you can see what is going on - -@item -examine in detail the ``scene of the crime'' --- in other words, the -execution context at a breakpoint, or when the last error occurred. -@end itemize - -@noindent -The details are more complex and more powerful @dots{} - -@menu -* Examples:: -* Intro to Breakpoints:: Setting and manipulating them. -* Tracing:: Tracing program execution. -@end menu - - -@node Examples -@subsection Examples - -Before we dive into the details and reference documentation of -guile-debugging's features, this chapter sets the scene by presenting a -few examples of what you can do with guile-debugging. - -@menu -* Single Stepping through a Procedure's Code:: -* Profiling or Tracing a Procedure's Code:: -@end menu - - -@node Single Stepping through a Procedure's Code -@subsubsection Single Stepping through a Procedure's Code - -A good way to explore in detail what a Scheme procedure does is to set a -breakpoint on it and then single step through what it does. To do this, -use the @code{break-in} procedure from the @code{(ice-9 debugging -breakpoints)} module with the @code{debug-trap} behaviour from -@code{(ice-9 debugging ice-9-debugger-extensions)}. The following -sample session illustrates this. It assumes that the file -@file{matrix.scm} defines a procedure @code{mkmatrix}, which is the one -we want to explore, and another procedure @code{do-main} which calls -@code{mkmatrix}. - -@lisp -$ /usr/bin/guile -q -guile> (use-modules (ice-9 debugger) - (ice-9 debugging ice-9-debugger-extensions) - (ice-9 debugging breakpoints)) -guile> (load "matrix.scm") -guile> (break-in 'mkmatrix #:behaviour debug-trap) -#<<break-in> 808cb70> -guile> (do-main 4) -This is the Guile debugger -- for help, type `help'. -There are 3 frames on the stack. - -Frame 2 at matrix.scm:8:3 - [mkmatrix] -debug> next -Frame 3 at matrix.scm:4:3 - (let ((x 1)) (quote this-is-a-matric)) -debug> info frame -Stack frame: 3 -This frame is an evaluation. -The expression being evaluated is: -matrix.scm:4:3: - (let ((x 1)) (quote this-is-a-matric)) -debug> next -Frame 3 at matrix.scm:5:21 - (quote this-is-a-matric) -debug> bt -In unknown file: - ?: 0* [primitive-eval (do-main 4)] -In standard input: - 4: 1* [do-main 4] -In matrix.scm: - 8: 2 [mkmatrix] - ... - 5: 3 (quote this-is-a-matric) -debug> quit -this-is-a-matric -guile> -@end lisp - -Or you can use guile-debugging's Emacs interface (GDS), by using the -module @code{(ice-9 gds-client)} instead of @code{(ice-9 debugger)} and -@code{(ice-9 debugging ice-9-debugger-extensions)}, and changing -@code{debug-trap} to @code{gds-debug-trap}. Then the stack and -corresponding source locations are displayed in Emacs instead of on the -Guile command line. - - -@node Profiling or Tracing a Procedure's Code -@subsubsection Profiling or Tracing a Procedure's Code - -What if you wanted to get a trace of everything that the Guile evaluator -does within a given procedure, but without Guile stopping and waiting -for your input at every step? In this case you set a breakpoint on the -procedure using @code{break-in} (the same as in the previous example), -but use the @code{trace-trap} and @code{trace-until-exit} behaviours -provided by the @code{(ice-9 debugging trace)} module. - -@lisp -guile> (use-modules (ice-9 debugging breakpoints) (ice-9 debugging trace)) -guile> (load "matrix.scm") -guile> (break-in 'mkmatrix #:behaviour (list trace-trap trace-until-exit)) -#<<break-in> 808b430> -guile> (do-main 4) -| 2: [mkmatrix] -| 3: [define (define yy 23) ((()) #<eval-closure 4028db30>)] -| 3: [define (define yy 23) ((()) #<eval-closure 4028db30>)] -| 3: =>(#@@define yy 23) -| 3: [let (let # #) (# #)] -| 3: [let (let # #) (# #)] -| 3: =>(#@@let* (x 1) #@@let (quote this-is-a-matric)) -| 2: (letrec ((yy 23)) (let ((x 1)) (quote this-is-a-matric))) -| 3: [let (let # #) (# # #)] -| 3: [let (let # #) (# # #)] -| 3: =>(#@@let* (x 1) #@@let (quote this-is-a-matric)) -| 2: (let ((x 1)) (quote this-is-a-matric)) -| 3: [quote (quote this-is-a-matric) ((x . 1) ((yy) 23) (()) ...)] -| 3: [quote (quote this-is-a-matric) ((x . 1) ((yy) 23) (()) ...)] -| 3: =>(#@@quote this-is-a-matric) -| 2: (quote this-is-a-matric) -| 2: =>this-is-a-matric -this-is-a-matric -guile> (do-main 4) -| 2: [mkmatrix] -| 2: (letrec ((yy 23)) (let ((x 1)) (quote this-is-a-matric))) -| 2: (let ((x 1)) (quote this-is-a-matric)) -| 2: (quote this-is-a-matric) -| 2: =>this-is-a-matric -this-is-a-matric -guile> -@end lisp - -This example shows the default configuration for how each line of trace -output is formatted, which is: - -@itemize -@item -the character @code{|}, a visual clue that the line is a line of trace -output, followed by - -@item -a number indicating the real evaluator stack depth (where ``real'' means -not counting tail-calls), followed by - -@item -a summary of the expression being evaluated (@code{(@dots{})}), the -procedure being called (@code{[@dots{}]}), or the value being returned -from an evaluation or procedure call (@code{=>@dots{}}). -@end itemize - -@noindent -You can customize @code{(ice-9 debugging trace)} to show different -information in each trace line using the @code{set-trace-layout} -procedure. The next example shows how to get the source location in -each trace line instead of the stack depth. - -@lisp -guile> (set-trace-layout "|~16@@a: ~a\n" trace/source trace/info) -guile> (do-main 4) -| matrix.scm:7:2: [mkmatrix] -| : (letrec ((yy 23)) (let ((x 1)) (quote this-is-a-matric))) -| matrix.scm:3:2: (let ((x 1)) (quote this-is-a-matric)) -| matrix.scm:4:20: (quote this-is-a-matric) -| matrix.scm:4:20: =>this-is-a-matric -this-is-a-matric -guile> -@end lisp - -(For anyone wondering why the first @code{(do-main 4)} call above -generates lots more trace lines than the subsequent calls: these -examples also demonstrate how the Guile evaluator ``memoizes'' code. -When Guile evaluates a source code expression for the first time, it -changes some parts of the expression so that they will be quicker to -evaluate when that expression is evaluated again; this is called -memoization. The trace output from the first @code{(do-main 4)} call -shows memoization steps, such as an internal define being transformed to -a letrec.) - - -@node Intro to Breakpoints -@subsection Intro to Breakpoints - -Sometimes a piece of Scheme code isn't working and you'd like to go -through it step by step. You can do this in Guile by setting a -breakpoint at the start of the relevant code, and then using the command -line or Emacs interface to step through it. - -A breakpoint can be specified by procedure name or by location -- the -relevant code's file name, line number and column number. For details -please see the full documentation for @code{break-in} and -@code{break-at} in @ref{Intro to Breakpoints}. - -When you set a breakpoint, you can specify any ``behaviour'' you like -for what should happen when the breakpoint is hit; a breakpoint -``behaviour'' is just a Scheme procedure with the right signature. - -@menu -* Breakpoints Overview:: -@end menu - - -@node Breakpoints Overview -@subsubsection How Breakpoints Work and Why They Are Useful - -Often, debugging the last error is not enough to tell you what went -wrong. For example, the root cause of the error may have arisen a long -time before the error was signalled, in which case the execution context -of the error is too late to be useful. Or your program might not signal -an error at all, just return an unexpected result or have some incorrect -side effect. - -In many such cases, it's useful to pause the program at or before the -point where you suspect the problem arises. Then you can explore the -stack, display the values of key variables, and generally check that the -state of the program is as you expect. If all is well, you can let the -program continue running normally, or step more slowly through each -expression that the Scheme interpreter evaluates. Single-stepping may -reveal that the program is going through blocks of code that you didn't -intend --- a useful data point for understanding what the underlying -problem is. - -Telling Guile where or when to pause a program is called @dfn{setting a -breakpoint}. When a breakpoint is hit, Guile's default behaviour is to -enter the interactive debugger, where there are now two sets of commands -available: - -@itemize @bullet -@item -all the commands as described for last error debugging -(@pxref{Interactive Debugger}), which allow you to explore the stack and -so on - -@item -additional commands for continuing program execution in various ways: -@code{next}, @code{step}, @code{finish}, @code{trace-finish} and -@code{continue}. -@end itemize - -Use of the interactive debugger is described in @ref{Interactive -Debugger}. - - @node Tracing -@subsection Tracing - -Tracing has already been described as a breakpoint behaviour, but we -mention it again here because it is so useful, and because Guile -actually now has @emph{two} mechanisms for tracing, and its worth -clarifying the differences between them. - -@menu -* Old Tracing:: Tracing provided by (ice-9 debug). -* New Tracing:: Breakpoint-based tracing. -* Tracing Compared:: Differences between old and new. -@end menu - - -@node Old Tracing -@subsubsection Tracing Provided by @code{(ice-9 debug)} +@section Tracing The @code{(ice-9 debug)} module implements tracing of procedure applications. When a procedure is @dfn{traced}, it means that every @@ -391,128 +119,6 @@ there is no need for Guile to create a new stack frame for each iteration. Tracing reveals this optimization in operation. -@node New Tracing -@subsubsection Breakpoint-based Tracing - -Guile's newer mechanism implements tracing as an optional behaviour for -any kind of breakpoint. - -To trace a procedure (in the same kind of way as the older tracing), use -the @code{trace!} procedure to set a procedure breakpoint with -@code{trace-here} behaviour: - -@lisp -(trace! fact1) -@print{} -Set breakpoint 1: [fact1] -@result{} -#<<procedure-breakpoint> 40337bf0> - -(fact1 4) -@print{} -| [fact1 4] -| | [fact1 3] -| | | [fact1 2] -| | | | [fact1 1] -| | | | | [fact1 0] -| | | | | 1 -| | | | 2 -| | | 6 -| | 24 -| 24 -@result{} -24 -@end lisp - -To trace evaluation of a source expression, evaluate code containing a -breakpoint marker @code{##} in the appropriate place, then use -@code{set-breakpoint} to change the behaviour of the new breakpoint to -@code{trace-here}: - -@lisp -(define (fact1 n) - (if ##(= n 0) - 1 - (* n (fact1 (- n 1))))) -@print{} -Set breakpoint 4: standard input:13:9: (= n 0) - -(use-modules (ice-9 debugger behaviour)) -(set-breakpoint! trace-here 4) -@print{} -Breakpoint 4: standard input:13:9: (= n 0) - enabled? = #t - behaviour = #<procedure trace-here ()> - -(fact1 4) -@print{} -| (= n 0) -| #f -| (= n 0) -| #f -| (= n 0) -| #f -| (= n 0) -| #f -| (= n 0) -| #t -@result{} -24 -@end lisp - -@noindent -(Note --- this example reveals a bug: each occurrence of @code{(= n 0)} -should be shown indented with respect to the one before it, as -@code{fact1} does not call itself tail-recursively.) - -You can also give a breakpoint the @code{trace-subtree} behaviour, which -means to trace the breakpoint location itself plus any evaluations and -applications that occur below it in the call stack. In the following -example, this allows us to see the evaluated arguments that are being -compared by the @code{=} procedure: - -@lisp -(set-breakpoint! trace-subtree 4) -@print{} -Breakpoint 4: standard input:13:9: (= n 0) - enabled? = #t - behaviour = #<procedure trace-subtree ()> - -(fact1 4) -@print{} -| (= n 0) -| [= 4 0] -| #f -| (= n 0) -| [= 3 0] -| #f -| (= n 0) -| [= 2 0] -| #f -| (= n 0) -| [= 1 0] -| #f -| (= n 0) -| [= 0 0] -| #t -@result{} -24 -@end lisp - - -@node Tracing Compared -@subsubsection Differences Between Old and New Tracing Mechanisms - -The newer tracing mechanism is more general and so more powerful than -the older one: it works for expressions as well as procedure -applications, and it implements the useful @code{trace-subtree} -behaviour as well as the more traditional @code{trace-here}. - -The older mechanism will probably become obsolete eventually, but it's -worth keeping it around for a while until we are sure that the new -mechanism is correct and does what programmers need. - - @c Local Variables: @c TeX-master: "guile.texi" @c End: diff --git a/doc/ref/scheme-using.texi b/doc/ref/scheme-using.texi index 93d0949f8..96273b7d0 100644 --- a/doc/ref/scheme-using.texi +++ b/doc/ref/scheme-using.texi @@ -163,10 +163,10 @@ The interactive debugger is documented further in the following section. @node Interactive Debugger @subsection Using the Interactive Debugger -Guile's interactive debugger is a command line application that accepts -commands from you for examining the stack and, if at a breakpoint, for -continuing program execution in various ways. Unlike in the normal -Guile REPL, commands are typed mostly without parentheses. +Guile's interactive debugger is a command line application that +accepts commands from you for examining the stack and, if stopped at a +trap, for continuing program execution in various ways. Unlike in the +normal Guile REPL, commands are typed mostly without parentheses. When you first enter the debugger, it introduces itself with a message like this: @@ -359,15 +359,17 @@ debugger to continue.) @node Using Guile in Emacs @section Using Guile in Emacs -There are quite a few options for working on Guile Scheme code in -Emacs. The simplest options are to use Emacs's standard -@code{scheme-mode} for editing code, and to run the interpreter when you -need it by typing ``guile'' at the prompt of a @code{*shell*} buffer, -but there are Emacs libraries available which add various bells and -whistles to this. The following diagram shows these libraries and how -they relate to each other, with the arrows indicating ``builds on'' or -``extends''. For example, the Quack library builds on cmuscheme, which -in turn builds on the standard scheme mode. +@cindex GDS +@cindex Emacs +There are several options for working on Guile Scheme code in Emacs. +The simplest are to use Emacs's standard @code{scheme-mode} for +editing code, and to run the interpreter when you need it by typing +``guile'' at the prompt of a @code{*shell*} buffer, but there are +Emacs libraries available which add various bells and whistles to +this. The following diagram shows these libraries and how they relate +to each other, with the arrows indicating ``builds on'' or +``extends''. For example, the Quack library builds on cmuscheme, +which in turn builds on the standard scheme mode. @example scheme @@ -408,25 +410,24 @@ interpreters and remembers which one you used last time; and so on. Quack is available from @uref{http://www.neilvandyke.org/quack}. @dfn{GDS}, written by Neil Jerram, also builds on the scheme/cmuscheme -combination, but with a fundamental change to the way that Scheme code -fragments are sent to the interpreter for evaluation. cmuscheme and -Quack send code fragments to the interpreter's standard input, on the -assumption that the interpreter is expecting to read Scheme expressions -there, and then monitor the interpreter's standard output to infer what -the result of the evaluation is. GDS doesn't use standard input and +combination, but with a change to the way that Scheme code fragments +are sent to the interpreter for evaluation. cmuscheme and Quack send +code fragments to the interpreter's standard input, on the assumption +that the interpreter is expecting to read Scheme expressions there, +and then monitor the interpreter's standard output to infer what the +result of the evaluation is. GDS doesn't use standard input and output like this. Instead, it sets up a socket connection between the Scheme interpreter and Emacs, and sends and receives messages using a simple protocol through this socket. The messages include requests to evaluate Scheme code, and responses conveying the results of an -evaluation, thus providing similar function to cmuscheme or Quack. They -also include requests for setting breakpoints, stack exploration and -debugging, which go beyond what cmuscheme or Quack can do. The price of -this extra power, however, is that GDS is Guile-specific. GDS requires -the Scheme interpreter, or any program that GDS is debugging, to run -some GDS-specific library code; currently this code is written as a -Guile module and uses a lot of debugging-related features that are +evaluation, thus providing similar function to cmuscheme or Quack. +They also include requests for stack exploration and debugging, which +go beyond what cmuscheme or Quack can do. The price of this extra +power, however, is that GDS is Guile-specific. GDS requires the +Scheme interpreter to run some GDS-specific library code; currently +this code is written as a Guile module and uses features that are specific to Guile. GDS is now included in the Guile distribution; for -previous Guile releases (1.8.x and earlier) it can be obtained as part +previous Guile releases (1.8.4 and earlier) it can be obtained as part of the @code{guile-debugging} package from @uref{http://www.ossau.uklinux.net/guile}. @@ -540,7 +541,7 @@ Emacs. This code, consisting of the installed files @file{gds.el} and @file{gds-server.el}, is responsible for displaying information from Guile in Emacs windows, and for responding to Emacs commands and keystrokes by sending instructions back to the Guile program being -debugged. +worked on. @item The GDS @dfn{server} code is written in Scheme and runs as an Emacs @@ -584,12 +585,12 @@ The data exchanged between client and server components, and between server and interface, is a sequence of sexps (parenthesised expressions) that are designed so as to be directly readable by both Scheme and Emacs Lisp. The use of a TCP connection means that the server and Emacs -interface can theoretically be on a different computer from the programs -being debugged, but in practice there are currently two problems with +interface can theoretically be on a different computer from the client +programs, but in practice there are currently two problems with this. Firstly the GDS API doesn't provide any way of specifying a non-local server to connect to, and secondly there is no security or authentication mechanism in the GDS protocol. These are issues that -should be addressed in the near future. +should be addressed in the future. @node GDS Getting Started @@ -620,7 +621,7 @@ and the @code{gds-debug} buffer will contain a Scheme backtrace ending with the message: @lisp -no code for module (ossau gds-server) +no code for module (ice-9 gds-server) @end lisp @noindent @@ -645,10 +646,10 @@ Emacs to open the file @file{gds-tutorial.txt} (which should have been installed as part of Guile, perhaps under @file{/usr/share/doc/guile}), and then follow the steps in that file. -When you want to use GDS to explore or debug an independent Guile +When you want to use GDS to work on an independent Guile application, you need to add something to that application's Scheme code to cause it to connect to and interact with GDS at the right times. The -following subsections describe the various ways of doing this. +following subsections describe the ways of doing this. @subsubsection Setting Specific Breakpoints @@ -667,10 +668,10 @@ the following. @end lisp @noindent -The @code{#:behaviour gds-debug-trap} clauses mean to use GDS to display -the stack when one of these breakpoints is hit. For more on -breakpoints, @code{break-in} and @code{break-at}, see @ref{Intro to -Breakpoints}. +The @code{#:behaviour gds-debug-trap} clauses mean to use GDS to +display the stack when one of these breakpoints is hit. For more on +breakpoints, @code{break-in} and @code{break-at}, see +@ref{Breakpoints}. @subsubsection Setting GDS-managed Breakpoints @@ -723,7 +724,7 @@ is pre-1.8) around the code of interest like this: (gds-debug-trap (throw->trap-context key args)))) @end lisp -In all cases you will need to use the @code{(ice-9 gds-client)} and +Either way, you will need to use the @code{(ice-9 gds-client)} and @code{(ice-9 debugging traps)} modules. Two special cases of this are the lazy-catch that the Guile REPL code @@ -738,7 +739,6 @@ procedure as follows. @lisp (use-modules (ice-9 gds-client) (ice-9 debugging traps)) - (on-lazy-handler-dispatch gds-debug-trap) @end lisp @@ -787,16 +787,12 @@ This approach is not yet implemented, though. @subsubsection Utility Guile Implementation -We conclude this subsection with an aside, by noting that the -``utility'' Guile client described above is nothing more than a -combination of the previous options. - -To be precise, the code for the utility Guile client is essentially just -this: +The ``utility'' Guile client mentioned above is a simple combination +of the mechanisms that we have just described. In fact the code for +the utility Guile client is essentially just this: @lisp (use-modules (ice-9 gds-client)) - (set-gds-breakpoints) (named-module-use! '(guile-user) '(ice-9 session)) (gds-accept-input #f)) @@ -805,17 +801,22 @@ this: @code{set-gds-breakpoints} works as already described. The @code{named-module-use!} line ensures that the client can process @code{help} and @code{apropos} expressions, to implement lookups in -Guile's online help. The @code{#f} parameter to @code{gds-accept-input} -means that the @code{continue} instruction will not cause the -instruction loop to exit, which makes sense here because the utility -client has nothing to do except to process GDS instructions. - -(The utility client does not use @code{on-lazy-handler-dispatch}, -because it has its own mechanism for catching and reporting exceptions -in the code that it is asked to evaluate. This mechanism summarizes the -exception and gives the user a button they can click to see the full -stack, so the end result is very similar to what -@code{on-lazy-handler-dispatch} provides.) +Guile's online help. The @code{#f} parameter to +@code{gds-accept-input} means that the @code{continue} instruction +will not cause the instruction loop to exit, which makes sense here +because the utility client has nothing to do except to process GDS +instructions. + +The utility client does not use @code{on-lazy-handler-dispatch} at its +top level, because it has its own mechanism for catching and reporting +exceptions in the code that it is asked to evaluate. This mechanism +summarizes the exception and gives the user a button they can click to +see the full stack, so the end result is very similar to what +@code{on-lazy-handler-dispatch} provides. Deep inside +@code{gds-accept-input}, in the part that handles evaluating +expressions from Emacs, the GDS client code uses +@code{throw->trap-context} and @code{gds-debug-trap} to implement +this. @node Working with GDS in Scheme Buffers @@ -850,7 +851,7 @@ or before the cursor but can also be entered or edited in the minibuffer. The available help is popped up in a temporary Emacs window. -@item C-h C-g +@item C-h G @findex gds-apropos List all accessible Guile symbols matching a given regular expression, with the same results as if you had typed @code{(apropos REGEXP)} into @@ -987,6 +988,14 @@ region contains a balanced expression, or try to expand the region so that it does; it uses the region exactly as it is. @end table +If you type @kbd{C-u} before one of these commands, GDS will +immediately pop up a Scheme stack buffer, showing the requested +evaluation, so that you can single step through it. (This is achieved +by setting a @code{<source-trap>} trap at the start of the requested +evaluation; see @ref{Source Traps} for more on how those work.) The +Scheme stack display, and the options for continuing through the code, +are described in the next two sections. + @node Displaying the Scheme Stack @subsection Displaying the Scheme Stack @@ -1211,35 +1220,9 @@ display in action. To do this add @noindent to your @file{testgds.scm} buffer and type @kbd{C-x C-e} (which -evaluates the expression that the cursor is just after the end of). The -result is: - -@lisp -(fact1 4) - -;;; Evaluating in current module (guile-user) - @result{} 24 - ---:** *Guile Evaluation* (Scheme:ready)--All------------ -@end lisp - -@noindent -which is correct, but indicates that we forgot the step needed to enable -the trap mechanism. To do this, type @kbd{C-c C-e} and then enter - -@lisp -(trap-enable 'traps) -@end lisp - -@noindent -into the minibuffer. (You could equally have typed this into your test -file and evaluated it from there; we use @kbd{C-c C-e} here to -demonstrate the minibuffer option and because you typically wouldn't -want to leave this kind of global setting in the source code that you -are working on.) - -If you now type @kbd{C-x C-e} to evaluate @code{(fact1 4)} again, a GDS -stack window like the following appears: +evaluates the expression that the cursor is just after the end of). +The result should be that a GDS stack window like the following +appears: @lisp Calling procedure: @@ -1250,19 +1233,10 @@ Calling procedure: --:** PID 28729 (Guile-Debug)--All------------ @end lisp -GDS's most compelling feature is its single-stepping. To get an -immediate feel for what this is like, make sure your Emacs is prepared -as described in @ref{GDS Getting Started}, then type the following code -into an interactive Guile session. - -@lisp -(fact1 4) -@end lisp - -@noindent -This will cause the GDS Guile-Debug window to pop up in Emacs, where -you can then press @kbd{i} once and @kbd{@key{SPC}} repeatedly to -single-step through the code from the point of the initial trap. +This stack tells you that Guile is about to call the @code{fact1} +procedure, with argument 4, and you can step through this call in +detail by pressing @kbd{i} once and then @kbd{@key{SPC}} +(@pxref{Continuing Execution}). (@kbd{i} is needed as the first keystroke rather than @kbd{@key{SPC}}, because the aim here is to step through code in the @code{(ice-9 diff --git a/doc/ref/srfi-modules.texi b/doc/ref/srfi-modules.texi index cacd769c2..b1fdde1c3 100644 --- a/doc/ref/srfi-modules.texi +++ b/doc/ref/srfi-modules.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Guile Reference Manual. -@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007 +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008 @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @@ -34,6 +34,7 @@ get the relevant SRFI documents from the SRFI home page * SRFI-14:: Character-set library. * SRFI-16:: case-lambda * SRFI-17:: Generalized set! +* SRFI-18:: Multithreading support * SRFI-19:: Time/Date library. * SRFI-26:: Specializing parameters * SRFI-31:: A special form `rec' for recursive evaluation @@ -44,6 +45,8 @@ get the relevant SRFI documents from the SRFI home page * SRFI-55:: Requiring Features. * SRFI-60:: Integers as bits. * SRFI-61:: A more general `cond' clause +* SRFI-69:: Basic hash tables. +* SRFI-88:: Keyword objects. @end menu @@ -1676,6 +1679,344 @@ The same as the Guile core @code{make-procedure-with-setter} @end defun +@node SRFI-18 +@subsection SRFI-18 - Multithreading support +@cindex SRFI-18 + +This is an implementation of the SRFI-18 threading and synchronization +library. The functions and variables described here are provided by + +@example +(use-modules (srfi srfi-18)) +@end example + +As a general rule, the data types and functions in this SRFI-18 +implementation are compatible with the types and functions in Guile's +core threading code. For example, mutexes created with the SRFI-18 +@code{make-mutex} function can be passed to the built-in Guile +function @code{lock-mutex} (@pxref{Mutexes and Condition Variables}), +and mutexes created with the built-in Guile function @code{make-mutex} +can be passed to the SRFI-18 function @code{mutex-lock!}. Cases in +which this does not hold true are noted in the following sections. + +@menu +* SRFI-18 Threads:: Executing code +* SRFI-18 Mutexes:: Mutual exclusion devices +* SRFI-18 Condition variables:: Synchronizing of groups of threads +* SRFI-18 Time:: Representation of times and durations +* SRFI-18 Exceptions:: Signalling and handling errors +@end menu + +@node SRFI-18 Threads +@subsubsection SRFI-18 Threads + +Threads created by SRFI-18 differ in two ways from threads created by +Guile's built-in thread functions. First, a thread created by SRFI-18 +@code{make-thread} begins in a blocked state and will not start +execution until @code{thread-start!} is called on it. Second, SRFI-18 +threads are constructed with a top-level exception handler that +captures any exceptions that are thrown on thread exit. In all other +regards, SRFI-18 threads are identical to normal Guile threads. + +@defun current-thread +Returns the thread that called this function. This is the same +procedure as the same-named built-in procedure @code{current-thread} +(@pxref{Threads}). +@end defun + +@defun thread? obj +Returns @code{#t} if @var{obj} is a thread, @code{#f} otherwise. This +is the same procedure as the same-named built-in procedure +@code{thread?} (@pxref{Threads}). +@end defun + +@defun make-thread thunk [name] +Call @code{thunk} in a new thread and with a new dynamic state, +returning the new thread and optionally assigning it the object name +@var{name}, which may be any Scheme object. + +Note that the name @code{make-thread} conflicts with the +@code{(ice-9 threads)} function @code{make-thread}. Applications +wanting to use both of these functions will need to refer to them by +different names. +@end defun + +@defun thread-name thread +Returns the name assigned to @var{thread} at the time of its creation, +or @code{#f} if it was not given a name. +@end defun + +@defun thread-specific thread +@defunx thread-specific-set! thread obj +Get or set the ``object-specific'' property of @var{thread}. In +Guile's implementation of SRFI-18, this value is stored as an object +property, and will be @code{#f} if not set. +@end defun + +@defun thread-start! thread +Unblocks @var{thread} and allows it to begin execution if it has not +done so already. +@end defun + +@defun thread-yield! +If one or more threads are waiting to execute, calling +@code{thread-yield!} forces an immediate context switch to one of them. +Otherwise, @code{thread-yield!} has no effect. @code{thread-yield!} +behaves identically to the Guile built-in function @code{yield}. +@end defun + +@defun thread-sleep! timeout +The current thread waits until the point specified by the time object +@var{timeout} is reached (@pxref{SRFI-18 Time}). This blocks the +thread only if @var{timeout} represents a point in the future. it is +an error for @var{timeout} to be @code{#f}. +@end defun + +@defun thread-terminate! thread +Causes an abnormal termination of @var{thread}. If @var{thread} is +not already terminated, all mutexes owned by @var{thread} become +unlocked/abandoned. If @var{thread} is the current thread, +@code{thread-terminate!} does not return. Otherwise +@code{thread-terminate!} returns an unspecified value; the termination +of @var{thread} will occur before @code{thread-terminate!} returns. +Subsequent attempts to join on @var{thread} will cause a ``terminated +thread exception'' to be raised. + +@code{thread-terminate!} is compatible with the thread cancellation +procedures in the core threads API (@pxref{Threads}) in that if a +cleanup handler has been installed for the target thread, it will be +called before the thread exits and its return value (or exception, if +any) will be stored for later retrieval via a call to +@code{thread-join!}. +@end defun + +@defun thread-join! thread [timeout [timeout-val]] +Wait for @var{thread} to terminate and return its exit value. When a +time value @var{timeout} is given, it specifies a point in time where +the waiting should be aborted. When the waiting is aborted, +@var{timeoutval} is returned if it is specified; otherwise, a +@code{join-timeout-exception} exception is raised +(@pxref{SRFI-18 Exceptions}). Exceptions may also be raised if the +thread was terminated by a call to @code{thread-terminate!} +(@code{terminated-thread-exception} will be raised) or if the thread +exited by raising an exception that was handled by the top-level +exception handler (@code{uncaught-exception} will be raised; the +original exception can be retrieved using +@code{uncaught-exception-reason}). +@end defun + + +@node SRFI-18 Mutexes +@subsubsection SRFI-18 Mutexes + +The behavior of Guile's built-in mutexes is parameterized via a set of +flags passed to the @code{make-mutex} procedure in the core +(@pxref{Mutexes and Condition Variables}). To satisfy the requirements +for mutexes specified by SRFI-18, the @code{make-mutex} procedure +described below sets the following flags: +@itemize @bullet +@item +@code{recursive}: the mutex can be locked recursively +@item +@code{unchecked-unlock}: attempts to unlock a mutex that is already +unlocked will not raise an exception +@item +@code{allow-external-unlock}: the mutex can be unlocked by any thread, +not just the thread that locked it originally +@end itemize + +@defun make-mutex [name] +Returns a new mutex, optionally assigning it the object name +@var{name}, which may be any Scheme object. The returned mutex will be +created with the configuration described above. Note that the name +@code{make-mutex} conflicts with Guile core function @code{make-mutex}. +Applications wanting to use both of these functions will need to refer +to them by different names. +@end defun + +@defun mutex-name mutex +Returns the name assigned to @var{mutex} at the time of its creation, +or @code{#f} if it was not given a name. +@end defun + +@defun mutex-specific mutex +@defunx mutex-specific-set! mutex obj +Get or set the ``object-specific'' property of @var{mutex}. In Guile's +implementation of SRFI-18, this value is stored as an object property, +and will be @code{#f} if not set. +@end defun + +@defun mutex-state mutex +Returns information about the state of @var{mutex}. Possible values +are: +@itemize @bullet +@item +thread @code{T}: the mutex is in the locked/owned state and thread T +is the owner of the mutex +@item +symbol @code{not-owned}: the mutex is in the locked/not-owned state +@item +symbol @code{abandoned}: the mutex is in the unlocked/abandoned state +@item +symbol @code{not-abandoned}: the mutex is in the +unlocked/not-abandoned state +@end itemize +@end defun + +@defun mutex-lock! mutex [timeout [thread]] +Lock @var{mutex}, optionally specifying a time object @var{timeout} +after which to abort the lock attempt and a thread @var{thread} giving +a new owner for @var{mutex} different than the current thread. This +procedure has the same behavior as the @code{lock-mutex} procedure in +the core library. +@end defun + +@defun mutex-unlock! mutex [condition-variable [timeout]] +Unlock @var{mutex}, optionally specifying a condition variable +@var{condition-variable} on which to wait, either indefinitely or, +optionally, until the time object @var{timeout} has passed, to be +signalled. This procedure has the same behavior as the +@code{unlock-mutex} procedure in the core library. +@end defun + + +@node SRFI-18 Condition variables +@subsubsection SRFI-18 Condition variables + +SRFI-18 does not specify a ``wait'' function for condition variables. +Waiting on a condition variable can be simulated using the SRFI-18 +@code{mutex-unlock!} function described in the previous section, or +Guile's built-in @code{wait-condition-variable} procedure can be used. + +@defun condition-variable? obj +Returns @code{#t} if @var{obj} is a condition variable, @code{#f} +otherwise. This is the same procedure as the same-named built-in +procedure +(@pxref{Mutexes and Condition Variables, @code{condition-variable?}}). +@end defun + +@defun make-condition-variable [name] +Returns a new condition variable, optionally assigning it the object +name @var{name}, which may be any Scheme object. This procedure +replaces a procedure of the same name in the core library. +@end defun + +@defun condition-variable-name condition-variable +Returns the name assigned to @var{thread} at the time of its creation, +or @code{#f} if it was not given a name. +@end defun + +@defun condition-variable-specific condition-variable +@defunx condition-variable-specific-set! condition-variable obj +Get or set the ``object-specific'' property of +@var{condition-variable}. In Guile's implementation of SRFI-18, this +value is stored as an object property, and will be @code{#f} if not +set. +@end defun + +@defun condition-variable-signal! condition-variable +@defunx condition-variable-broadcast! condition-variable +Wake up one thread that is waiting for @var{condition-variable}, in +the case of @code{condition-variable-signal!}, or all threads waiting +for it, in the case of @code{condition-variable-broadcast!}. The +behavior of these procedures is equivalent to that of the procedures +@code{signal-condition-variable} and +@code{broadcast-condition-variable} in the core library. +@end defun + + +@node SRFI-18 Time +@subsubsection SRFI-18 Time + +The SRFI-18 time functions manipulate time in two formats: a +``time object'' type that represents an absolute point in time in some +implementation-specific way; and the number of seconds since some +unspecified ``epoch''. In Guile's implementation, the epoch is the +Unix epoch, 00:00:00 UTC, January 1, 1970. + +@defun current-time +Return the current time as a time object. This procedure replaces +the procedure of the same name in the core library, which returns the +current time in seconds since the epoch. +@end defun + +@defun time? obj +Returns @code{#t} if @var{obj} is a time object, @code{#f} otherwise. +@end defun + +@defun time->seconds time +@defunx seconds->time seconds +Convert between time objects and numerical values representing the +number of seconds since the epoch. When converting from a time object +to seconds, the return value is the number of seconds between +@var{time} and the epoch. When converting from seconds to a time +object, the return value is a time object that represents a time +@var{seconds} seconds after the epoch. +@end defun + + +@node SRFI-18 Exceptions +@subsubsection SRFI-18 Exceptions + +SRFI-18 exceptions are identical to the exceptions provided by +Guile's implementation of SRFI-34. The behavior of exception +handlers invoked to handle exceptions thrown from SRFI-18 functions, +however, differs from the conventional behavior of SRFI-34 in that +the continuation of the handler is the same as that of the call to +the function. Handlers are called in a tail-recursive manner; the +exceptions do not ``bubble up''. + +@defun current-exception-handler +Returns the current exception handler. +@end defun + +@defun with-exception-handler handler thunk +Installs @var{handler} as the current exception handler and calls the +procedure @var{thunk} with no arguments, returning its value as the +value of the exception. @var{handler} must be a procedure that accepts +a single argument. The current exception handler at the time this +procedure is called will be restored after the call returns. +@end defun + +@defun raise obj +Raise @var{obj} as an exception. This is the same procedure as the +same-named procedure defined in SRFI 34. +@end defun + +@defun join-timeout-exception? obj +Returns @code{#t} if @var{obj} is an exception raised as the result of +performing a timed join on a thread that does not exit within the +specified timeout, @code{#f} otherwise. +@end defun + +@defun abandoned-mutex-exception? obj +Returns @code{#t} if @var{obj} is an exception raised as the result of +attempting to lock a mutex that has been abandoned by its owner thread, +@code{#f} otherwise. +@end defun + +@defun terminated-thread-exception? obj +Returns @code{#t} if @var{obj} is an exception raised as the result of +joining on a thread that exited as the result of a call to +@code{thread-terminate!}. +@end defun + +@defun uncaught-exception? obj +@defunx uncaught-exception-reason exc +@code{uncaught-exception?} returns @code{#t} if @var{obj} is an +exception thrown as the result of joining a thread that exited by +raising an exception that was handled by the top-level exception +handler installed by @code{make-thread}. When this occurs, the +original exception is preserved as part of the exception thrown by +@code{thread-join!} and can be accessed by calling +@code{uncaught-exception-reason} on that exception. Note that +because this exception-preservation mechanism is a side-effect of +@code{make-thread}, joining on threads that exited as described above +but were created by other means will not raise this +@code{uncaught-exception} error. +@end defun + + @node SRFI-19 @subsection SRFI-19 - Time/Date Library @cindex SRFI-19 @@ -1843,8 +2184,10 @@ Return the current time of the given @var{type}. The default @var{type} is @code{time-utc}. Note that the name @code{current-time} conflicts with the Guile core -@code{current-time} function (@pxref{Time}). Applications wanting to -use both will need to use a different name for one of them. +@code{current-time} function (@pxref{Time}) as well as the SRFI-18 +@code{current-time} function (@pxref{SRFI-18 Time}). Applications +wanting to use more than one of these functions will need to refer to +them by different names. @end defun @defun time-resolution [type] @@ -2470,7 +2813,7 @@ specified by @var{field+value}, a sequence of field names (symbols) and values as in the following example: @lisp -(let* ((&ct (make-condition-type 'foo &condition '(a b c)))) +(let ((&ct (make-condition-type 'foo &condition '(a b c)))) (make-condition &ct 'a 1 'b 2 'c 3)) @end lisp @@ -3027,6 +3370,245 @@ needed to get SRFI-61 itself. Extended @code{cond} is documented in @ref{if cond case,, Simple Conditional Evaluation}. +@node SRFI-69 +@subsection SRFI-69 - Basic hash tables +@cindex SRFI-69 + +This is a portable wrapper around Guile's built-in hash table and weak +table support. @xref{Hash Tables}, for information on that built-in +support. Above that, this hash-table interface provides association +of equality and hash functions with tables at creation time, so +variants of each function are not required, as well as a procedure +that takes care of most uses for Guile hash table handles, which this +SRFI does not provide as such. + +Access it with: + +@lisp +(use-modules (srfi srfi-69)) +@end lisp + +@menu +* SRFI-69 Creating hash tables:: +* SRFI-69 Accessing table items:: +* SRFI-69 Table properties:: +* SRFI-69 Hash table algorithms:: +@end menu + +@node SRFI-69 Creating hash tables +@subsubsection Creating hash tables + +@deffn {Scheme Procedure} make-hash-table [equal-proc hash-proc #:weak weakness start-size] +Create and answer a new hash table with @var{equal-proc} as the +equality function and @var{hash-proc} as the hashing function. + +By default, @var{equal-proc} is @code{equal?}. It can be any +two-argument procedure, and should answer whether two keys are the +same for this table's purposes. + +My default @var{hash-proc} assumes that @code{equal-proc} is no +coarser than @code{equal?} unless it is literally @code{string-ci=?}. +If provided, @var{hash-proc} should be a two-argument procedure that +takes a key and the current table size, and answers a reasonably good +hash integer between 0 (inclusive) and the size (exclusive). + +@var{weakness} should be @code{#f} or a symbol indicating how ``weak'' +the hash table is: + +@table @code +@item #f +An ordinary non-weak hash table. This is the default. + +@item key +When the key has no more non-weak references at GC, remove that entry. + +@item value +When the value has no more non-weak references at GC, remove that +entry. + +@item key-or-value +When either has no more non-weak references at GC, remove the +association. +@end table + +As a legacy of the time when Guile couldn't grow hash tables, +@var{start-size} is an optional integer argument that specifies the +approximate starting size for the hash table, which will be rounded to +an algorithmically-sounder number. +@end deffn + +By @dfn{coarser} than @code{equal?}, we mean that for all @var{x} and +@var{y} values where @code{(@var{equal-proc} @var{x} @var{y})}, +@code{(equal? @var{x} @var{y})} as well. If that does not hold for +your @var{equal-proc}, you must provide a @var{hash-proc}. + +In the case of weak tables, remember that @dfn{references} above +always refers to @code{eq?}-wise references. Just because you have a +reference to some string @code{"foo"} doesn't mean that an association +with key @code{"foo"} in a weak-key table @emph{won't} be collected; +it only counts as a reference if the two @code{"foo"}s are @code{eq?}, +regardless of @var{equal-proc}. As such, it is usually only sensible +to use @code{eq?} and @code{hashq} as the equivalence and hash +functions for a weak table. @xref{Weak References}, for more +information on Guile's built-in weak table support. + +@deffn {Scheme Procedure} alist->hash-table alist [equal-proc hash-proc #:weak weakness start-size] +As with @code{make-hash-table}, but initialize it with the +associations in @var{alist}. Where keys are repeated in @var{alist}, +the leftmost association takes precedence. +@end deffn + +@node SRFI-69 Accessing table items +@subsubsection Accessing table items + +@deffn {Scheme Procedure} hash-table-ref table key [default-thunk] +@deffnx {Scheme Procedure} hash-table-ref/default table key default +Answer the value associated with @var{key} in @var{table}. If +@var{key} is not present, answer the result of invoking the thunk +@var{default-thunk}, which signals an error instead by default. + +@code{hash-table-ref/default} is a variant that requires a third +argument, @var{default}, and answers @var{default} itself instead of +invoking it. +@end deffn + +@deffn {Scheme Procedure} hash-table-set! table key new-value +Set @var{key} to @var{new-value} in @var{table}. +@end deffn + +@deffn {Scheme Procedure} hash-table-delete! table key +Remove the association of @var{key} in @var{table}, if present. If +absent, do nothing. +@end deffn + +@deffn {Scheme Procedure} hash-table-exists? table key +Answer whether @var{key} has an association in @var{table}. +@end deffn + +@deffn {Scheme Procedure} hash-table-update! table key modifier [default-thunk] +@deffnx {Scheme Procedure} hash-table-update!/default table key modifier default +Replace @var{key}'s associated value in @var{table} by invoking +@var{modifier} with one argument, the old value. + +If @var{key} is not present, and @var{default-thunk} is provided, +invoke it with no arguments to get the ``old value'' to be passed to +@var{modifier} as above. If @var{default-thunk} is not provided in +such a case, signal an error. + +@code{hash-table-update!/default} is a variant that requires the +fourth argument, which is used directly as the ``old value'' rather +than as a thunk to be invoked to retrieve the ``old value''. +@end deffn + +@node SRFI-69 Table properties +@subsubsection Table properties + +@deffn {Scheme Procedure} hash-table-size table +Answer the number of associations in @var{table}. This is guaranteed +to run in constant time for non-weak tables. +@end deffn + +@deffn {Scheme Procedure} hash-table-keys table +Answer an unordered list of the keys in @var{table}. +@end deffn + +@deffn {Scheme Procedure} hash-table-values table +Answer an unordered list of the values in @var{table}. +@end deffn + +@deffn {Scheme Procedure} hash-table-walk table proc +Invoke @var{proc} once for each association in @var{table}, passing +the key and value as arguments. +@end deffn + +@deffn {Scheme Procedure} hash-table-fold table proc init +Invoke @code{(@var{proc} @var{key} @var{value} @var{previous})} for +each @var{key} and @var{value} in @var{table}, where @var{previous} is +the result of the previous invocation, using @var{init} as the first +@var{previous} value. Answer the final @var{proc} result. +@end deffn + +@deffn {Scheme Procedure} hash-table->alist table +Answer an alist where each association in @var{table} is an +association in the result. +@end deffn + +@node SRFI-69 Hash table algorithms +@subsubsection Hash table algorithms + +Each hash table carries an @dfn{equivalence function} and a @dfn{hash +function}, used to implement key lookups. Beginning users should +follow the rules for consistency of the default @var{hash-proc} +specified above. Advanced users can use these to implement their own +equivalence and hash functions for specialized lookup semantics. + +@deffn {Scheme Procedure} hash-table-equivalence-function hash-table +@deffnx {Scheme Procedure} hash-table-hash-function hash-table +Answer the equivalence and hash function of @var{hash-table}, respectively. +@end deffn + +@deffn {Scheme Procedure} hash obj [size] +@deffnx {Scheme Procedure} string-hash obj [size] +@deffnx {Scheme Procedure} string-ci-hash obj [size] +@deffnx {Scheme Procedure} hash-by-identity obj [size] +Answer a hash value appropriate for equality predicate @code{equal?}, +@code{string=?}, @code{string-ci=?}, and @code{eq?}, respectively. +@end deffn + +@code{hash} is a backwards-compatible replacement for Guile's built-in +@code{hash}. + +@node SRFI-88 +@subsection SRFI-88 Keyword Objects +@cindex SRFI-88 +@cindex keyword objects + +@uref{http://srfi.schemers.org/srfi-88/srfi-88.html, SRFI-88} provides +@dfn{keyword objects}, which are equivalent to Guile's keywords +(@pxref{Keywords}). SRFI-88 keywords can be entered using the +@dfn{postfix keyword syntax}, which consists of an identifier followed +by @code{:} (@pxref{Reader options, @code{postfix} keyword syntax}). +SRFI-88 can be made available with: + +@example +(use-modules (srfi srfi-88)) +@end example + +Doing so installs the right reader option for keyword syntax, using +@code{(read-set! keywords 'postfix)}. It also provides the procedures +described below. + +@deffn {Scheme Procedure} keyword? obj +Return @code{#t} if @var{obj} is a keyword. This is the same procedure +as the same-named built-in procedure (@pxref{Keyword Procedures, +@code{keyword?}}). + +@example +(keyword? foo:) @result{} #t +(keyword? 'foo:) @result{} #t +(keyword? "foo") @result{} #f +@end example +@end deffn + +@deffn {Scheme Procedure} keyword->string kw +Return the name of @var{kw} as a string, i.e., without the trailing +colon. The returned string may not be modified, e.g., with +@code{string-set!}. + +@example +(keyword->string foo:) @result{} "foo" +@end example +@end deffn + +@deffn {Scheme Procedure} string->keyword str +Return the keyword object whose name is @var{str}. + +@example +(keyword->string (string->keyword "a b c")) @result{} "a b c" +@end example +@end deffn + + @c srfi-modules.texi ends here @c Local Variables: |