* Changes to the C interface
\f
-Changes since the stable branch:
+Changes since the 1.6.x series:
* Changes to the distribution
** Guile is now licensed with the GNU Lesser General Public License.
+** The manual is now licensed with the GNU Free Documentation License.
+
** Guile now requires GNU MP (http://swox.com/gmp).
Guile now uses the GNU MP library for arbitrary precision arithmetic.
-At the moment it is being used to handle Guile's bignums.
** Guile now has separate private and public configuration headers.
-Guile now has config.h and libguile/scmconfig.h. The former is not
-installed and is private. The latter is installed and used by Guile's
-public headers. config.h is generated by configure and autoheader,
-and scmconfig.h is generated by a small C program, gen-scmconfig at
-build time based in part on the contents of config.h.
-
-Seen libguile/__scm.h and gen-scmconfig.c for more information.
-
-Note too that nearly all public defines are now set to either 1 or 0
-rather than being set to 1 or left undefined. See gen-scmconfig.c and
-the GNU Coding Guidelines for the rationale. However, pre-existing
-defines that were not renamed were not changed. i.e. GUILE_DEBUG is
-still either 1 or undefined.
-
-** The INSTALL file is now the generic automake installed one.
-
-Guile specific instructions can be found in the README.
+That is, things like HAVE_STRING_H no longer leak from Guile's
+headers.
** Guile now provides and uses an "effective" version number.
Guile now provides scm_effective_version and effective-version
functions which return the "effective" version number. This is just
the normal full version string without the final micro-version number,
-so the current effective-version is "1.6". The effective version
+so the current effective-version is "1.7". The effective version
should remain unchanged during a stable series, and should be used for
items like the versioned share directory name
-i.e. /usr/share/guile/1.6.
+i.e. /usr/share/guile/1.7.
Providing an unchanging version number during a stable release for
things like the versioned share directory can be particularly
where you have some section(s) of code which you consider can run
in parallel to other sections.
+### move rest to manual
+
They "flag" (with dynamic extent) sections of code to be of
"serial" or "parallel" nature and have the single effect of
preventing a serial section from being run in parallel with any
C code primitive), enabling the computations to run in parallel
while the scripting code runs single-threadedly.
-** Guile now includes its own version of libltdl.
+** New module (srfi srfi-26)
+
+This is an implementation of SRFI-26.
+
+** New module (srfi srfi-31)
+
+This is an implementation of SRFI-31 which provides a special form
+`rec' for recursive evaluation.
+
+** The modules (srfi srfi-13), (srfi srfi-14) and (srfi srfi-4) have
+ been merged with the core, making their functionality always
+ available.
+
+The modules are still available, tho, and you could use them together
+with a renaming import, for example.
+
+** Guile no longer includes its own version of libltdl.
+
+The official version is good enough now.
+
+** The --enable-htmldoc option has been removed from 'configure'.
+
+Support for translating the documentation into HTML is now always
+provided. Use 'make html'.
-We now use a modified version of libltdl that allows us to make
-improvements to it without having to rely on libtool releases.
+** The configure option '--disable-arrays' has been removed.
+
+Support for arrays and uniform numeric arrays is now always included
+in Guile.
* Changes to the stand-alone interpreter
+** New command line option `-L'.
+
+This option adds a directory to the front of the load path.
+
** New command line option `--no-debug'.
Specifying `--no-debug' on the command line will keep the debugging
* Changes to Scheme functions and syntax
+** The default load path no longer includes "." at the end.
+
+Automatically loading modules from the current directory should not
+happen by default. If you want to allow it in a more controlled
+manner, set the environment variable GUILE_LOAD_PATH or the Scheme
+variable %load-path.
+
+** The uniform vector and array support has been overhauled.
+
+It now complies with SRFI-4 and the weird prototype based uniform
+array creation has been deprecated. See the manual for more details.
+
+Some non-compatible changes have been made:
+ - characters can no longer be stored into byte arrays.
+ - strings and bit vectors are no longer considered to be uniform vectors.
+ - array-rank throws an error for non-arrays instead of returning zero.
+ - array-ref does no longer accept non-arrays when no indices are given.
+
+There is the new notion of 'generalized vectors' and corresponding
+procedures like 'generalized-vector-ref'. Generalized vectors include
+strings, bitvectors, ordinary vectors, and uniform numeric vectors.
+
+Arrays use generalized vectors their storage, so that you still have
+arrays of characters, bits, etc. However, uniform-array-read! and
+uniform-array-write can no longer read/write strings and bitvectors.
+
+** There is now support for copy-on-write substrings, mutation-sharing
+ substrings and read-only strings.
+
+Three new procedures are related to this: substring/shared,
+substring/copy, and substring/read-only. See the manual for more
+information.
+
+** Backtraces will now highlight the value that caused the error.
+
+By default, these values are enclosed in "{...}", such as in this
+example:
+
+ guile> (car 'a)
+
+ Backtrace:
+ In current input:
+ 1: 0* [car {a}]
+
+ <unnamed port>:1:1: In procedure car in expression (car (quote a)):
+ <unnamed port>:1:1: Wrong type (expecting pair): a
+ ABORT: (wrong-type-arg)
+
+The prefix and suffix used for highlighting can be set via the two new
+printer options 'highlight-prefix' and 'highlight-suffix'. For
+example, putting this into ~/.guile will output the bad value in bold
+on an ANSI terminal:
+
+ (print-set! highlight-prefix "\x1b[1m")
+ (print-set! highlight-suffix "\x1b[22m")
+
+
+** 'gettext' support for internationalization has been added.
+
+See the manual for details.
+
** New syntax '@' and '@@':
You can now directly refer to variables exported from a module by
For example (@ (ice-9 pretty-print) pretty-print) will directly access
the pretty-print variable exported from the (ice-9 pretty-print)
module. You don't need to 'use' that module first. You can also use
-'@' with 'set!'.
+'@' as a target of 'set!', as in (set! (@ mod var) val).
The related syntax (@@ MODULE-NAME VARIABLE-NAME) works just like '@',
but it can also access variables that have not been exported. It is
intended only for kluges and temporary fixes and for debugging, not
for ordinary code.
+** Keyword syntax has been made more disciplined.
+
+Previously, the name of a keyword was read as a 'token' but printed as
+a symbol. Now, it is read as a general Scheme datum which must be a
+symbol.
+
+Previously:
+
+ guile> #:12
+ #:#{12}#
+ guile> #:#{12}#
+ #:#{\#{12}\#}#
+ guile> #:(a b c)
+ #:#{}#
+ ERROR: In expression (a b c):
+ Unbound variable: a
+ guile> #: foo
+ #:#{}#
+ ERROR: Unbound variable: foo
+
+Now:
+
+ guile> #:12
+ ERROR: Wrong type (expecting symbol): 12
+ guile> #:#{12}#
+ #:#{12}#
+ guile> #:(a b c)
+ ERROR: Wrong type (expecting symbol): (a b c)
+ guile> #: foo
+ #:foo
+
** 'while' now provides 'break' and 'continue'
break and continue were previously bound in a while loop, but not
** 'call-with-current-continuation' is now also available under the name
'call/cc'.
-** Checking for duplicate bindings in module system
+** The module system now checks for duplicate bindings.
The module system now can check for name conflicts among imported
bindings.
-The behavior can be controlled by specifying one or more duplicates
+The behavior can be controlled by specifying one or more 'duplicates'
handlers. For example, to make Guile return an error for every name
collision, write:
to your .guile init file.
+### move rest to manual
+
The syntax for the :duplicates option is:
:duplicates HANDLER-NAME | (HANDLER1-NAME HANDLER2-NAME ...)
will import all bindings exported from bar, but rename them by adding
the prefix `bar:'.
-** Merging generic functions
+** Conflicting generic functions can be automatically merged.
+
+When two imported bindings conflict and they are both generic
+functions, the two functions can now be merged automatically. This is
+activated with the 'duplicates' handler 'merge-generics'.
+
+### move the rest to the manual
It is sometimes tempting to use GOOPS accessors with short names.
For example, it is tempting to use the name `x' for the x-coordinate
version string without the final micro-version number. See "Changes
to the distribution" above.
-** Futures: future, make-future, future-ref
+** New feature, 'futures': future, make-future, future-ref
-Futures are like promises, but begun immediately in a new thread. See
-the "Futures" section in the reference manual.
+Futures are like promises, but begin execution immediately in a new
+thread. See the "Futures" section in the reference manual.
** New threading functions: parallel, letpar, par-map, and friends
just as a standard condition variable must be used together with a
standard mutex.
-** New functions: make-fair-mutex, make-fair-condition-variable'
+*** New functions: make-fair-mutex, make-fair-condition-variable'
Make a new fair mutex and a new fair condition variable respectively.
were recognized as integers. Now (odd? 1.0) returns #t, (odd? 2.0)
returns #f and (odd? 1.5) signals an error.
-** We now have uninterned symbols.
+** Guile now has uninterned symbols.
-The new function 'make-symbol' will return a uninterned symbol. This
+The new function 'make-symbol' will return an uninterned symbol. This
is a symbol that is unique and is guaranteed to remain unique.
However, uninterned symbols can not yet be read back in.
The function pretty-print from the (ice-9 pretty-print) module can now
also be invoked with keyword arguments that control things like
-maximum output width. See its online documentation.
+maximum output width. See the manual for details.
** Variables have no longer a special behavior for `equal?'.
** Deprecated: procedure->macro
-Change your code to use either procedure->memoizing-macro or, probably better,
-to use r5rs macros. Also, be aware that macro expansion will not be done
-during evaluation, but prior to evaluation.
+Change your code to use 'define-macro' or r5rs macros. Also, be aware
+that macro expansion will not be done during evaluation, but prior to
+evaluation.
** Soft ports now allow a `char-ready?' procedure
There is no replacement for undefine.
-** call-with-output-string doesn't segv on closed port
+* The functions make-keyword-from-dash-symbol and keyword-dash-symbol
+ have been discouraged.
-Previously call-with-output-string would give a segmentation fault if
-the string port was closed by the called function. An exception is
-raised now.
+They are relics from a time where a keyword like #:foo was used
+directly as a Tcl option "-foo" and thus keywords were internally
+stored as a symbol with a starting dash. We now store a symbol
+without the dash.
-** (ice-9 popen) duplicate pipe fd fix
+Use symbol->keyword and keyword->symbol instead.
-open-pipe, open-input-pipe and open-output-pipe left an extra copy of
-their pipe file descriptor in the child, which was normally harmless,
-but it can prevent the parent seeing eof or a broken pipe immediately
-and has now been fixed.
-** source-properties and set-source-properties! fix
-
-Properties set with set-source-properties! can now be read back
-correctly with source-properties.
+* Changes to the C interface
-** SRFI-1 fixes
+** There is the new notion of 'discouraged' features.
-delete and delete! now call the "=" procedure with arguments in the
-order described by the SRFI-1 specification
+This is a milder form of deprecation.
-list-copy now accepts improper lists, per the specification.
+Things that are discouraged should not be used in new code, but it is
+OK to leave them in old code for now. When a discouraged feature is
+used, no warning message is printed like there is for 'deprecated'
+features. Also, things that are merely discouraged are nevertheless
+implemented efficiently, while deprecated features can be very slow.
-** SRFI-19 fixes
+You can omit discouraged features from libguile by configuring it with
+the '--disable-discouraged' option.
-date-week-number now correctly respects the requested day of week
-starting the week.
+** A new family of functions for converting between C values and
+ Scheme values has been added.
-* Changes to the C interface
+These functions follow a common naming scheme and are designed to be
+easier to use, thread-safe and more future-proof than the older
+alternatives.
-** New way to deal with non-local exits and reentries.
+ - int scm_is_* (...)
+
+ These are predicates that return a C boolean: 1 or 0. Instead of
+ SCM_NFALSEP, you can now use scm_is_true, for example.
-There is a new set of functions that essentially do what
-scm_internal_dynamic_wind does, but in a more convenient way. Here is
-a quick example of how to prevent a potential memory leak:
+ - <type> scm_to_<type> (SCM val, ...)
- void
- foo ()
- {
- char *mem;
+ These are functions that convert a Scheme value into an appropriate
+ C value. For example, you can use scm_to_int to safely convert from
+ a SCM to an int.
- scm_begin_frame (0);
+ - SCM scm_from_<type> (<type> val, ...)
- mem = scm_malloc (100);
- scm_on_unwind (free, mem, SCM_F_WIND_EXPLICITELY);
+ These functions convert from a C type to a SCM value; for example,
+ scm_from_int for ints.
- /* MEM would leak if BAR throws an error. SCM_ON_UNWIND frees it
- nevertheless.
- */
- bar ();
-
- scm_end_frame ();
+There is a huge number of these functions, for numbers, strings,
+symbols, vectors, etc. They are documented in the reference manual in
+the API section together with the types that they apply to.
- /* Because of SCM_F_WIND_EXPLICITELY, MEM will be freed by
- SCM_END_FRAME as well.
- */
- }
+** New functions for dealing with complex numbers in C have been added.
-For full documentation, see the node "Frames" in the manual.
+The new functions are scm_c_make_rectangular, scm_c_make_polar,
+scm_c_real_part, scm_c_imag_part, scm_c_magnitude and scm_c_angle.
+They work like scm_make_rectangular etc but take or return doubles
+directly.
-** New way to block and unblock asyncs
+** The function scm_make_complex has been discouraged.
-In addition to scm_c_call_with_blocked_asyncs you can now also use
-scm_with_blocked_asyncs in a 'frame' (see above). Likewise for
-scm_c_call_with_unblocked_asyncs and scm_with_unblocked_asyncs.
+Use scm_c_make_rectangular instead.
-** New way to temporarily set the current input, output or error ports
+** The INUM macros have been deprecated.
-C code can now use scm_with_current_<foo>_port in a 'frame' (see
-above). <foo> is one of "input", "output" or "error".
+A lot of code uses these macros to do general integer conversions,
+although the macros only work correctly with fixnums. Use the
+following alternatives.
-** New types scm_t_intmax and scm_t_uintmax.
+ SCM_INUMP -> scm_is_integer or similar
+ SCM_NINUMP -> !scm_is_integer or similar
+ SCM_MAKINUM -> scm_from_int or similar
+ SCM_INUM -> scm_to_int or similar
-On platforms that have them, these types are identical to intmax_t and
-uintmax_t, respectively. On other platforms, they are identical to
-the largest integer types that Guile knows about.
+ SCM_VALIDATE_INUM_* -> Do not use these; scm_to_int, etc. will
+ do the validating for you.
-** Many public #defines with generic names have been made private.
+** The scm_num2<type> and scm_<type>2num functions and scm_make_real
+ have been discouraged.
-#defines with generic names like HAVE_FOO or SIZEOF_FOO have been made
-private or renamed with a more suitable public name. See below for
-the ones which have been renamed.
+Use the newer scm_to_<type> and scm_from_<type> functions instead for
+new code. The functions have been discouraged since they don't fit
+the naming scheme.
-** HAVE_STDINT_H and HAVE_INTTYPES_H have been removed from public use.
+** The 'boolean' macros SCM_FALSEP etc have been discouraged.
-HAVE_STDINT_H and HAVE_INTTYPES_H removed from public use. These are
-no longer needed since the older uses of stdint.h and inttypes.h are
-now handled by configure.in and gen-scmconfig.c.
+They have strange names, especially SCM_NFALSEP, and SCM_BOOLP
+evaluates its argument twice. Use scm_is_true, etc. instead for new
+code.
-** USE_DLL_IMPORT is no longer defined publically.
+** The macro SCM_EQ_P has been discouraged.
-gen-scmconfig now uses it to decide what contents to place in the
-public scmconfig.h header without adding the USE_DLL_IMPORT itself.
+Use scm_is_eq for new code, which fits better into the naming
+conventions.
-** HAVE_LIMITS_H has been removed from public use.
+** The macros SCM_CONSP, SCM_NCONSP, SCM_NULLP, and SCM_NNULLP have
+ been discouraged.
-gen-scmconfig now just uses HAVE_LIMITS_H to decide whether or not to
-add a limits.h include in scmconfig.h.
+Use the function scm_is_pair or scm_is_null instead.
-** time.h, sys/time.h, etc. #ifdefery has been removed from public headers.
+** The functions scm_round and scm_truncate have been deprecated and
+ are now available as scm_c_round and scm_c_truncate, respectively.
-gen-scmconfig now just uses the same logic to decide what time related
-#includes to add to scmconfig.h.
+These functions occupy the names that scm_round_number and
+scm_truncate_number should have.
-** HAVE_STRUCT_TIMESPEC has been removed from public use.
+** The functions scm_c_string2str, scm_c_substring2str, and
+ scm_c_symbol2str have been deprecated.
-scmconfig.h now just defines scm_t_timespec.
+Use scm_to_locale_stringbuf or similar instead, maybe together with
+scm_substring.
-** HAVE_PTRDIFF has been removed from public use and Guile doesn't
- define ptrdiff_t.
+** New functions scm_c_make_string, scm_c_string_length,
+ scm_c_string_ref, scm_c_string_set_x, scm_c_substring,
+ scm_c_substring_shared, scm_c_substring_copy.
-Guile now publically defines scm_t_ptrdiff and
-SCM_SIZEOF_SCM_T_PTRDIFF in scmconfig.h, and all occurrences of
-ptrdiff_t have been replaced with scm_t_ptrdiff.
+These are like scm_make_string, scm_length, etc. but are slightly
+easier to use from C.
-Guile defines its own type this rather than just relying on ptrdiff_t
-and SCM_SIZEOF_PTRDIFF_T because Guile actually typedefs long to
-scm_t_ptrdiff when ptrdiff_t isn't available. A public "typedef long
-ptrdiff_t" could conflict with other headers.
+** The macros SCM_STRINGP, SCM_STRING_CHARS, SCM_STRING_LENGTH,
+ SCM_SYMBOL_CHARS, and SCM_SYMBOL_LENGTH have been deprecated.
-** HAVE_UINTPTR_T and HAVE_UINTPTR_T have been removed from public use.
+They export too many assumptions about the implementation of strings
+and symbols that are no longer true in the presence of
+mutation-sharing substrings and when Guile switches to some form of
+Unicode.
-They are replaced by public definitions of SCM_SIZEOF_UINTPTR_T and
-SCM_SIZEOF_INTPTR_T. These are defined to 0 if the corresponding type
-is not available.
+When working with strings, it is often best to use the normal string
+functions provided by Guile, such as scm_c_string_ref,
+scm_c_string_set_x, scm_string_append, etc. Be sure to look in the
+manual since many more such functions are now provided than
+previously.
-** The public #define STDC_HEADERS has been renamed to SCM_HAVE_STDC_HEADERS.
+When you want to convert a SCM string to a C string, use the
+scm_to_locale_string function or similar instead. For symbols, use
+scm_symbol_to_string and then work with that string. Because of the
+new string representation, scm_symbol_to_string does not need to copy
+and is thus quite efficient.
-The previous name was too generic for the global public namespace.
+** Some string, symbol and keyword functions have been discouraged.
-** The public #define HAVE_SYS_SELECT has been renamed to
- SCM_HAVE_SYS_SELECT_H.
+They don't fit into the uniform naming scheme and are not explicit
+about the character encoding.
-The previous name was too generic for the global public namespace.
+Replace according to the following table:
-** The public #define HAVE_FLOATINGPOINT_H has been renamed to
- SCM_HAVE_FLOATINGPOINT_H.
+ scm_allocate_string -> scm_c_make_string
+ scm_take_str -> scm_take_locale_stringn
+ scm_take0str -> scm_take_locale_string
+ scm_mem2string -> scm_from_locale_stringn
+ scm_str2string -> scm_from_locale_string
+ scm_makfrom0str -> scm_from_locale_string
+ scm_mem2symbol -> scm_from_locale_symboln
+ scm_mem2uninterned_symbol -> scm_from_locale_stringn + scm_make_symbol
+ scm_str2symbol -> scm_from_locale_symbol
-The previous name was too generic for the global public namespace.
+ SCM_SYMBOL_HASH -> scm_hashq
+ SCM_SYMBOL_INTERNED_P -> scm_symbol_interned_p
-** The public #define HAVE_IEEEFP_H has been renamed to SCM_HAVE_IEEEFP_H.
+ scm_c_make_keyword -> scm_from_locale_keyword
-The previous name was too generic for the global public namespace.
+** The functions scm_keyword_to_symbol and sym_symbol_to_keyword are
+ now also available to C code.
-** The public #define HAVE_NAN_H has been renamed to SCM_HAVE_NAN_H.
+** SCM_KEYWORDP and SCM_KEYWORDSYM have been deprecated.
-The previous name was too generic for the global public namespace.
+Use scm_is_keyword and scm_keyword_to_symbol instead, but note that
+the latter returns the true name of the keyword, not the 'dash name',
+as SCM_KEYWORDSYM used to do.
-** The public #define HAVE_WINSOCK2_H has been renamed to SCM_HAVE_WINSOCK2_H.
+** The old uniform vector and bitvector implementations have been
+ unceremoniously removed.
-The previous name was too generic for the global public namespace.
+This implementation exposed the detailes of the tagging system of
+Guile. Use the new C API explained in the manual in node "Uniform
+Numeric Vectors" and "Bit Vectors", respectively.
-** The public #define HAVE_ARRAYS has been renamed to SCM_HAVE_ARRAYS.
+The following macros are gone: SCM_UVECTOR_BASE, SCM_SET_UVECTOR_BASE,
+SCM_UVECTOR_MAXLENGTH, SCM_UVECTOR_LENGTH, SCM_MAKE_UVECTOR_TAG,
+SCM_SET_UVECTOR_LENGTH, SCM_BITVECTOR_P, SCM_BITVECTOR_BASE,
+SCM_SET_BITVECTOR_BASE, SCM_BITVECTOR_MAX_LENGTH,
+SCM_BITVECTOR_LENGTH, SCM_MAKE_BITVECTOR_TAG,
+SCM_SET_BITVECTOR_LENGTH.
-The previous name was too generic for the global public namespace.
+** The macros dealing with vectors have been deprecated.
-** The public #define STACK_GROWS_UP has been renamed to SCM_STACK_GROWS_UP.
+Use the new functions scm_is_vector, scm_vector_elements,
+scm_vector_writable_elements, etc instead. See the manual for more
+details.
-The previous name was too generic for the global public namespace.
+Deprecated are SCM_VECTORP, SCM_VELTS, SCM_VECTOR_MAX_LENGTH,
+SCM_VECTOR_LENGTH, SCM_VECTOR_REF, SCM_VECTOR_SET, SCM_WRITABLE_VELTS.
-** The public #define USE_PTHREAD_THREADS has been renamed to
- SCM_USE_PTHREAD_THREADS.
+The following macros have been removed: SCM_VECTOR_BASE,
+SCM_SET_VECTOR_BASE, SCM_MAKE_VECTOR_TAG, SCM_SET_VECTOR_LENGTH,
+SCM_VELTS_AS_STACKITEMS, SCM_SETVELTS, SCM_GC_WRITABLE_VELTS.
-The previous name was too generic for the global public namespace.
+** SCM_CELL_WORD_LOC has been deprecated.
-** The public #define USE_NULL_THREADS has been renamed to
- SCM_USE_NULL_THREADS.
+Use the new macro SCM_CELL_OBJECT_LOC instead, which returns a pointer
+to a SCM, as opposed to a pointer to a scm_t_bits.
-The previous name was too generic for the global public namespace.
+This was done to allow the correct use of pointers into the Scheme
+heap. Previously, the heap words were of type scm_t_bits and local
+variables and function arguments were of type SCM, making it
+non-standards-conformant to have a pointer that can point to both.
-** The public #define USE_COOP_THREADS has been renamed to
- SCM_USE_COOP_THREADS.
+** New macros SCM_SMOB_DATA_2, SCM_SMOB_DATA_3, etc.
-The previous name was too generic for the global public namespace.
+These macros should be used instead of SCM_CELL_WORD_2/3 to access the
+second and third words of double smobs. Likewise for
+SCM_SET_SMOB_DATA_2 and SCM_SET_SMOB_DATA_3.
-** SCM_C_INLINE is publically defined if possible.
+Also, there is SCM_SMOB_FLAGS and SCM_SET_SMOB_FLAGS that should be
+used to get and set the 16 exra bits in the zeroth word of a smob.
-If the platform has a way to define inline functions, SCM_C_INLINE
-will be defined to that text. Otherwise it will be undefined. This
-is a little bit different than autoconf's normal handling of the
-inline define via AC_C_INLINE.
+And finally, there is SCM_SMOB_OBJECT and SCM_SMOB_SET_OBJECT for
+accesing the first immediate word of a smob as a SCM value, and there
+is SCM_SMOB_OBJECT_LOC for getting a pointer to the first immediate
+smob word. Like wise for SCM_SMOB_OBJECT_2, etc.
-** Guile now publically defines some basic type infrastructure.
+** New way to deal with non-local exits and re-entries.
-Guile always defines
+There is a new set of functions that essentially do what
+scm_internal_dynamic_wind does, but in a way that is more convenient
+for C code in some situations. Here is a quick example of how to
+prevent a potential memory leak:
- SCM_SIZEOF_CHAR
- SCM_SIZEOF_UNSIGNED_CHAR
- SCM_SIZEOF_SHORT
- SCM_SIZEOF_UNSIGNED_SHORT
- SCM_SIZEOF_LONG
- SCM_SIZEOF_UNSIGNED_LONG
- SCM_SIZEOF_INT
- SCM_SIZEOF_UNSIGNED_INT
- SCM_SIZEOF_LONG_LONG /* defined to 0 if type not available */
- SCM_SIZEOF_UNSIGNED_LONG_LONG /* defined to 0 if type not available */
+ void
+ foo ()
+ {
+ char *mem;
- scm_t_int8
- scm_t_uint8
- scm_t_int16
- scm_t_uint16
- scm_t_int32
- scm_t_uint32
+ scm_frame_begin (0);
-Guile always defines these to 0 or 1
+ mem = scm_malloc (100);
+ scm_frame_unwind_handler (free, mem, SCM_F_WIND_EXPLICITELY);
- SCM_HAVE_T_INT64
- SCM_HAVE_T_UINT64
+ /* MEM would leak if BAR throws an error.
+ SCM_FRAME_UNWIND_HANDLER frees it nevertheless.
+ */
-and when either of these are defined to 1, also defines
+ bar ();
+
+ scm_frame_end ();
- scm_t_int64
- scm_t_uint64
+ /* Because of SCM_F_WIND_EXPLICITELY, MEM will be freed by
+ SCM_FRAME_END as well.
+ */
+ }
-respectively.
+For full documentation, see the node "Frames" in the manual.
-Guile always defines
+** New function scm_frame_free
- scm_t_timespec
+This function calls 'free' on a given pointer when a frame is left.
+Thus the call to scm_frame_unwind_handler above could be replaced with
+simply scm_frame_free (mem).
-** The macro SCM_IFLAGP now only returns true for flags
+** New way to block and unblock asyncs
-User code should never have used this macro anyway. And, you should not use
-it in the future either. Thus, the following explanation is just for the
-impropable case that your code actually made use of this macro, and that you
-are willing to depend on internals which will probably change in the near
-future.
+In addition to scm_c_call_with_blocked_asyncs you can now also use
+scm_frame_block_asyncs in a 'frame' (see above). Likewise for
+scm_c_call_with_unblocked_asyncs and scm_frame_unblock_asyncs.
-Formerly, SCM_IFLAGP also returned true for evaluator bytecodes created with
-SCM_MAKSPCSYM (short instructions) and evaluator bytecodes created with
-SCM_MAKISYM (short instructions). Now, SCM_IFLAG only returns true for
-Guile's special constants created with SCM_MAKIFLAG. To achieve the old
-behaviour, instead of
+** New way to temporarily set the current input, output or error ports
- SCM_IFLAGP(x)
+C code can now use scm_frame_current_<foo>_port in a 'frame' (see
+above). <foo> is one of "input", "output" or "error".
-you would have to write
+** New way to temporarily set fluids
- (SCM_ISYMP(x) || SCM_IFLAGP(x))
+C code can now use scm_frame_fluid in a 'frame' (see
+above) to temporarily set the value of a fluid.
-** The macro SCM_TYP16S has been deprecated.
+** New types scm_t_intmax and scm_t_uintmax.
-This macro is not intended for public use. However, if you allocated types
-with tc16 type codes in a way that you would have needed this macro, you are
-expected to have a deep knowledge of Guile's type system. Thus, you should
-know how to replace this macro.
+On platforms that have them, these types are identical to intmax_t and
+uintmax_t, respectively. On other platforms, they are identical to
+the largest integer types that Guile knows about.
-** The macro SCM_SLOPPY_INEXACTP has been deprecated.
+** The functions scm_unmemocopy and scm_unmemoize have been removed.
-Use SCM_INEXACTP instead.
+You should not have used them.
-** The macro SCM_SLOPPY_REALP has been deprecated.
+** Many public #defines with generic names have been made private.
-Use SCM_REALP instead.
+#defines with generic names like HAVE_FOO or SIZEOF_FOO have been made
+private or renamed with a more suitable public name.
-** The macro SCM_SLOPPY_COMPLEXP has been deprecated.
+** The macro SCM_TYP16S has been deprecated.
-Use SCM_COMPLEXP instead.
+This macro is not intended for public use.
-** The preprocessor define USE_THREADS has been deprecated.
+** The macro SCM_SLOPPY_INEXACTP has been deprecated.
-Going forward, assume that the thread API is always present.
+Use scm_is_true (scm_inexact_p (...)) instead.
-** The preprocessor define GUILE_ISELECT has been deprecated.
+** The macro SCM_SLOPPY_REALP has been deprecated.
-Going forward, assume that scm_internal_select is always present.
+Use scm_is_real instead.
-** The preprocessor define READER_EXTENSIONS has been deprecated.
+** The macro SCM_SLOPPY_COMPLEXP has been deprecated.
-Going forward, assume that the features represented by
-READER_EXTENSIONS are always present.
+Use scm_is_complex instead.
-** The preprocessor define DEBUG_EXTENSIONS has been deprecated.
+** Some preprocessor defines have been deprecated.
-Going forward, assume that the features represented by
-DEBUG_EXTENSIONS are always present.
+These defines indicated whether a certain feature was present in Guile
+or not. Going forward, assume that the features are always present.
-** The preprocessor define DYNAMIC_LINKING has been deprecated.
+The macros are: USE_THREADS, GUILE_ISELECT, READER_EXTENSIONS,
+DEBUG_EXTENSIONS, DYNAMIC_LINKING.
-Going forward, assume that the features represented by
-DYNAMIC_LINKING are always present.
+The following macros have been removed completely: MEMOIZE_LOCALS,
+SCM_RECKLESS, SCM_CAUTIOUS.
** The preprocessor define STACK_DIRECTION has been deprecated.
There should be no need to know about the stack direction for ordinary
-programs. (Do not use.)
+programs.
** New function: scm_effective_version
The name scm_definedp is deprecated.
-** The struct scm_cell has been renamed to scm_t_cell
+** The struct scm_cell type has been renamed to scm_t_cell
This is in accordance to Guile's naming scheme for types. Note that
the name scm_cell is now used for a function that allocates and
are: scm_must_malloc, scm_must_realloc, scm_must_free,
scm_must_strdup, scm_must_strndup, scm_done_malloc, scm_done_free.
-** New function: scm_str2string
-
-This function creates a scheme string from a 0-terminated C string. The input
-string is copied.
-
** Declarations of exported features are marked with SCM_API.
Every declaration of a feature that belongs to the exported Guile API
will expand into "__declspec (dllimport) extern", which is needed for
linking to the Guile DLL in Windows.
-There are also SCM_RL_IMPORT, QT_IMPORT, SCM_SRFI1314_IMPORT, and
+There are also SCM_RL_IMPORT, SCM_SRFI1314_IMPORT, and
SCM_SRFI4_IMPORT, for the corresponding libraries.
** SCM_NEWCELL and SCM_NEWCELL2 have been deprecated.
-Use the new functions scm_cell and scm_double_cell instead. The old macros
-had problems because with them allocation and initialization was separated and
-the GC could sometimes observe half initialized cells. Only careful coding by
-the user of SCM_NEWCELL and SCM_NEWCELL2 could make this safe and efficient.
+Use the new functions scm_cell and scm_double_cell instead. The old
+macros had problems because with them allocation and initialization
+was separated and the GC could sometimes observe half initialized
+cells. Only careful coding by the user of SCM_NEWCELL and
+SCM_NEWCELL2 could make this safe and efficient.
** CHECK_ENTRY, CHECK_APPLY and CHECK_EXIT have been deprecated.
** Deprecated: scm_makmacro
-Change your code to use either scm_makmmacro or, probably better, to use r5rs
-macros. Also, be aware that macro expansion will not be done during
-evaluation, but prior to evaluation.
-
-** Removed from scm_root_state: def_inp, def_outp, def_errp, together
-with corresponding macros scm_def_inp, scm_def_outp and scm_def_errp.
-These were undocumented and unused copies of the standard ports at the
-time that Guile was initialised. Normally the current ports should be
-used instead, obtained from scm_current_input_port () etc. If an
-application needs to retain earlier ports, it should save them in a
-gc-protected location.
-
-** Removed compile time option MEMOIZE_LOCALS
-
-Now, caching of local variable positions during memoization is mandatory.
-However, the option to disable the caching has most probably not been used
-anyway.
-
-** Removed compile time option SCM_RECKLESS
-
-Full number of arguments checking of closures is mandatory now. However, the
-option to disable the checking has most probably not been used anyway.
-
-** Removed compile time option SCM_CAUTIOUS
-
-Full number of arguments checking of closures is mandatory now. However, the
-option to disable the checking has most probably not been used anyway.
-
-** Deprecated configure flags USE_THREADS and GUILE_ISELECT
-
-Previously, when the C preprocessor macro USE_THREADS was defined,
-libguile included a thread API. This API is now always included, even
-when threads are not really supported. Thus, you don't need to test
-for USE_THREADS.
-
-Analogously, GUILE_ISELECT was defined when the function
-scm_internal_select was provided by Guile. This function is now
-always defined, and GUILE_ISELECT with it.
+Change your code to use either scm_makmmacro or to define macros in
+Scheme, using 'define-macro'.
** New function scm_c_port_for_each.
This function is like scm_port_for_each but takes a pointer to a C
function as the callback instead of a SCM value.
-** Deprecated definitions of error strings: scm_s_expression, scm_s_test,
-scm_s_body, scm_s_bindings, scm_s_variable, scm_s_clauses, scm_s_formals
-
-These error message strings were used to issue syntax error messages by
-guile's evaluator. It's unlikely that they have been used by user code.
-
-** Deprecated helper macros for evaluation and application: SCM_EVALIM2,
-SCM_EVALIM, SCM_XEVAL, SCM_XEVALCAR
-
-These macros were used in the implementation of the evaluator. It's unlikely
-that they have been used by user code.
-
-** Deprecated helper functions for evaluation and application:
-scm_m_expand_body, scm_macroexp
-
-These functions were used in the implementation of the evaluator. It's
-unlikely that they have been used by user code.
-
-** Deprecated functions for unmemoization: scm_unmemocar
-
-** Deprecated macros for iloc handling: SCM_ILOC00, SCM_IDINC, SCM_IDSTMSK
-
-These macros were used in the implementation of the evaluator. It's unlikely
-that they have been used by user code.
-
-** Removed definitions: scm_lisp_nil, scm_lisp_t, s_nil_ify,
-scm_m_nil_ify, s_t_ify, scm_m_t_ify, s_0_cond, scm_m_0_cond, s_0_ify,
-scm_m_0_ify, s_1_ify, scm_m_1_ify, scm_debug_newcell,
-scm_debug_newcell2, scm_tc16_allocated, SCM_SET_SYMBOL_HASH,
-SCM_IM_NIL_IFY, SCM_IM_T_IFY, SCM_IM_0_COND, SCM_IM_0_IFY,
-SCM_IM_1_IFY, SCM_GC_SET_ALLOCATED, scm_debug_newcell,
-scm_debug_newcell2, SCM_HUP_SIGNAL, SCM_INT_SIGNAL, SCM_FPE_SIGNAL,
-SCM_BUS_SIGNAL, SCM_SEGV_SIGNAL, SCM_ALRM_SIGNAL, SCM_GC_SIGNAL,
-SCM_TICK_SIGNAL, SCM_SIG_ORD, SCM_ORD_SIG, SCM_NUM_SIGS,
-scm_top_level_lookup_closure_var, *top-level-lookup-closure*,
-scm_system_transformer, scm_eval_3, scm_eval2,
-root_module_lookup_closure, SCM_SLOPPY_STRINGP, SCM_RWSTRINGP,
-scm_read_only_string_p, scm_make_shared_substring, scm_tc7_substring,
-sym_huh, SCM_VARVCELL, SCM_UDVARIABLEP, SCM_DEFVARIABLEP, scm_mkbig,
-scm_big2inum, scm_adjbig, scm_normbig, scm_copybig, scm_2ulong2big,
-scm_dbl2big, scm_big2dbl, SCM_FIXNUM_BIT, SCM_SETCHARS,
-SCM_SLOPPY_SUBSTRP, SCM_SUBSTR_STR, SCM_SUBSTR_OFFSET, SCM_LENGTH_MAX,
-SCM_SETLENGTH, SCM_ROSTRINGP, SCM_ROLENGTH, SCM_ROCHARS, SCM_ROUCHARS,
-SCM_SUBSTRP, SCM_COERCE_SUBSTR, scm_sym2vcell, scm_intern,
-scm_intern0, scm_sysintern, scm_sysintern0,
+** Many definitions have been removed that were previously deprecated.
+
+scm_lisp_nil, scm_lisp_t, s_nil_ify, scm_m_nil_ify, s_t_ify,
+scm_m_t_ify, s_0_cond, scm_m_0_cond, s_0_ify, scm_m_0_ify, s_1_ify,
+scm_m_1_ify, scm_debug_newcell, scm_debug_newcell2,
+scm_tc16_allocated, SCM_SET_SYMBOL_HASH, SCM_IM_NIL_IFY, SCM_IM_T_IFY,
+SCM_IM_0_COND, SCM_IM_0_IFY, SCM_IM_1_IFY, SCM_GC_SET_ALLOCATED,
+scm_debug_newcell, scm_debug_newcell2, SCM_HUP_SIGNAL, SCM_INT_SIGNAL,
+SCM_FPE_SIGNAL, SCM_BUS_SIGNAL, SCM_SEGV_SIGNAL, SCM_ALRM_SIGNAL,
+SCM_GC_SIGNAL, SCM_TICK_SIGNAL, SCM_SIG_ORD, SCM_ORD_SIG,
+SCM_NUM_SIGS, scm_top_level_lookup_closure_var,
+*top-level-lookup-closure*, scm_system_transformer, scm_eval_3,
+scm_eval2, root_module_lookup_closure, SCM_SLOPPY_STRINGP,
+SCM_RWSTRINGP, scm_read_only_string_p, scm_make_shared_substring,
+scm_tc7_substring, sym_huh, SCM_VARVCELL, SCM_UDVARIABLEP,
+SCM_DEFVARIABLEP, scm_mkbig, scm_big2inum, scm_adjbig, scm_normbig,
+scm_copybig, scm_2ulong2big, scm_dbl2big, scm_big2dbl, SCM_FIXNUM_BIT,
+SCM_SETCHARS, SCM_SLOPPY_SUBSTRP, SCM_SUBSTR_STR, SCM_SUBSTR_OFFSET,
+SCM_LENGTH_MAX, SCM_SETLENGTH, SCM_ROSTRINGP, SCM_ROLENGTH,
+SCM_ROCHARS, SCM_ROUCHARS, SCM_SUBSTRP, SCM_COERCE_SUBSTR,
+scm_sym2vcell, scm_intern, scm_intern0, scm_sysintern, scm_sysintern0,
scm_sysintern0_no_module_lookup, scm_init_symbols_deprecated,
scm_vector_set_length_x, scm_contregs, scm_debug_info,
scm_debug_frame, SCM_DSIDEVAL, SCM_CONST_LONG, SCM_VCELL,
scm_istr2flo, scm_istring2number, scm_istr2int, scm_istr2flo,
scm_istring2number, scm_vtable_index_vcell, scm_si_vcell, SCM_ECONSP,
SCM_NECONSP, SCM_GLOC_VAR, SCM_GLOC_VAL, SCM_GLOC_SET_VAL,
-SCM_GLOC_VAL_LOC, scm_make_gloc, scm_gloc_p, scm_tc16_variable
+SCM_GLOC_VAL_LOC, scm_make_gloc, scm_gloc_p, scm_tc16_variable,
+SCM_CHARS, SCM_LENGTH, SCM_SET_STRING_CHARS, SCM_SET_STRING_LENGTH.
\f
Changes since Guile 1.4: