This is guile.info, produced by makeinfo version 4.3 from guile.texi.

INFO-DIR-SECTION The Algorithmic Language Scheme
START-INFO-DIR-ENTRY
* Guile Reference: (guile).     The Guile reference manual.
END-INFO-DIR-ENTRY

   Guile Reference Manual Copyright (C) 1996 Free Software Foundation
Copyright (C) 1997 Free Software Foundation
Copyright (C) 2000 Free Software Foundation
Copyright (C) 2001 Free Software Foundation
Copyright (C) 2002 Free Software Foundation

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that this permission notice may be stated in a
translation approved by the Free Software Foundation.


File: guile.info,  Node: Accessing Modules from C,  Prev: Included Guile Modules,  Up: The Guile module system

Accessing Modules from C
------------------------

   The last sections have described how modules are used in Scheme code,
which is the recommended way of creating and accessing modules.  You
can also work with modules from C, but it is more cumbersome.

   The following procedures are available.

 - C Procedure: SCM scm_current_module ()
     Return the module that is the _current module_.

 - C Procedure: SCM scm_set_current_module (SCM MODULE)
     Set the current module to MODULE and return the previous current
     module.

 - C Procedure: SCM scm_c_call_with_current_module (SCM MODULE, SCM
          (*FUNC)(void *), void *DATA)
     Call FUNC and make MODULE the current module during the call.  The
     argument DATA is passed to FUNC.  The return value of
     `scm_c_call_with_current_module' is the return value of FUNC.

 - C Procedure: SCM scm_c_lookup (const char *NAME)
     Return the variable bound to the symbol indicated by NAME in the
     current module.  If there is no such binding or the symbol is not
     bound to a variable, signal an error.

 - C Procedure: SCM scm_lookup (SCM NAME)
     Like `scm_c_lookup', but the symbol is specified directly.

 - C Procedure: SCM scm_c_module_lookup (SCM MODULE, const char *NAME)
 - C Procedure: SCM scm_module_lookup (SCM MODULE, SCM NAME)
     Like `scm_c_lookup' and `scm_lookup', but the specified module is
     used instead of the current one.

 - C Procedure: SCM scm_c_define (const char *NAME, SCM VAL)
     Bind the symbol indicated by NAME to a variable in the current
     module and set that variable to VAL.  When NAME is already bound
     to a variable, use that.  Else create a new variable.

 - C Procedure: SCM scm_define (SCM NAME, SCM VAL)
     Like `scm_c_define', but the symbol is specified directly.

 - C Procedure: SCM scm_c_module_define (SCM MODULE, const char *NAME,
          SCM VAL)
 - C Procedure: SCM scm_module_define (SCM MODULE, SCM NAME, SCM VAL)
     Like `scm_c_define' and `scm_define', but the specified module is
     used instead of the current one.

 - C Procedure: SCM scm_module_reverse_lookup (SCM MODULE, SCM VARIABLE)
     Find the symbol that is bound to VARIABLE in MODULE.  When no such
     binding is found, return #F.

 - C Procedure: SCM scm_c_define_module (const char *NAME, void
          (*INIT)(void *), void *DATA)
     Define a new module named NAME and make it current while INIT is
     called, passing it DATA.  Return the module.

     The parameter NAME is a string with the symbols that make up the
     module name, separated by spaces.  For example, `"foo bar"' names
     the module `(foo bar)'.

     When there already exists a module named NAME, it is used
     unchanged, otherwise, an empty module is created.

 - C Procedure: SCM scm_c_resolve_module (const char *NAME)
     Find the module name NAME and return it.  When it has not already
     been defined, try to auto-load it.  When it can't be found that
     way either, create an empty module.  The name is interpreted as
     for `scm_c_define_module'.

 - C Procedure: SCM scm_resolve_module (SCM NAME)
     Like `scm_c_resolve_module', but the name is given as a real list
     of symbols.

 - C Procedure: SCM scm_c_use_module (const char *NAME)
     Add the module named NAME to the uses list of the current module,
     as with `(use-modules NAME)'.  The name is interpreted as for
     `scm_c_define_module'.

 - C Procedure: SCM scm_c_export (const char *NAME, ...)
     Add the bindings designated by NAME, ... to the public interface
     of the current module.  The list of names is terminated by `NULL'.


File: guile.info,  Node: Dynamic Libraries,  Next: Variables,  Prev: The Guile module system,  Up: Modules

Dynamic Libraries
=================

   Most modern Unices have something called "shared libraries".  This
ordinarily means that they have the capability to share the executable
image of a library between several running programs to save memory and
disk space.  But generally, shared libraries give a lot of additional
flexibility compared to the traditional static libraries.  In fact,
calling them `dynamic' libraries is as correct as calling them `shared'.

   Shared libraries really give you a lot of flexibility in addition to
the memory and disk space savings.  When you link a program against a
shared library, that library is not closely incorporated into the final
executable.  Instead, the executable of your program only contains
enough information to find the needed shared libraries when the program
is actually run.  Only then, when the program is starting, is the final
step of the linking process performed.  This means that you need not
recompile all programs when you install a new, only slightly modified
version of a shared library.  The programs will pick up the changes
automatically the next time they are run.

   Now, when all the necessary machinery is there to perform part of the
linking at run-time, why not take the next step and allow the programmer
to explicitly take advantage of it from within his program?  Of course,
many operating systems that support shared libraries do just that, and
chances are that Guile will allow you to access this feature from within
your Scheme programs.  As you might have guessed already, this feature
is called "dynamic linking".(1)

   As with many aspects of Guile, there is a low-level way to access the
dynamic linking apparatus, and a more high-level interface that
integrates dynamically linked libraries into the module system.

* Menu:

* Low level dynamic linking::
* Extensions::

   ---------- Footnotes ----------

   (1) Some people also refer to the final linking stage at program
startup as `dynamic linking', so if you want to make yourself perfectly
clear, it is probably best to use the more technical term "dlopening",
as suggested by Gordon Matzigkeit in his libtool documentation.


File: guile.info,  Node: Low level dynamic linking,  Next: Extensions,  Up: Dynamic Libraries

Low level dynamic linking
-------------------------

   When using the low level procedures to do your dynamic linking, you
have complete control over which library is loaded when and what gets
done with it.

 - Scheme Procedure: dynamic-link library
 - C Function: scm_dynamic_link (library)
     Find the shared library denoted by LIBRARY (a string) and link it
     into the running Guile application.  When everything works out,
     return a Scheme object suitable for representing the linked object
     file.  Otherwise an error is thrown.  How object files are
     searched is system dependent.

     Normally, LIBRARY is just the name of some shared library file
     that will be searched for in the places where shared libraries
     usually reside, such as in `/usr/lib' and `/usr/local/lib'.

 - Scheme Procedure: dynamic-object? obj
 - C Function: scm_dynamic_object_p (obj)
     Return `#t' if OBJ is a dynamic library handle, or `#f' otherwise.

 - Scheme Procedure: dynamic-unlink dobj
 - C Function: scm_dynamic_unlink (dobj)
     Unlink the indicated object file from the application.  The
     argument DOBJ must have been obtained by a call to `dynamic-link'.
     After `dynamic-unlink' has been called on DOBJ, its content is no
     longer accessible.

 - Scheme Procedure: dynamic-func name dobj
 - C Function: scm_dynamic_func (name, dobj)
     Search the dynamic object DOBJ for the C function indicated by the
     string NAME and return some Scheme handle that can later be used
     with `dynamic-call' to actually call the function.

     Regardless whether your C compiler prepends an underscore `_' to
     the global names in a program, you should *not* include this
     underscore in FUNCTION.  Guile knows whether the underscore is
     needed or not and will add it when necessary.

 - Scheme Procedure: dynamic-call func dobj
 - C Function: scm_dynamic_call (func, dobj)
     Call the C function indicated by FUNC and DOBJ.  The function is
     passed no arguments and its return value is ignored.  When
     FUNCTION is something returned by `dynamic-func', call that
     function and ignore DOBJ.  When FUNC is a string , look it up in
     DYNOBJ; this is equivalent to
          (dynamic-call (dynamic-func FUNC DOBJ) #f)

     Interrupts are deferred while the C function is executing (with
     `SCM_DEFER_INTS'/`SCM_ALLOW_INTS').

 - Scheme Procedure: dynamic-args-call func dobj args
 - C Function: scm_dynamic_args_call (func, dobj, args)
     Call the C function indicated by FUNC and DOBJ, just like
     `dynamic-call', but pass it some arguments and return its return
     value.  The C function is expected to take two arguments and
     return an `int', just like `main':
          int c_func (int argc, char **argv);

     The parameter ARGS must be a list of strings and is converted into
     an array of `char *'.  The array is passed in ARGV and its size in
     ARGC.  The return value is converted to a Scheme number and
     returned from the call to `dynamic-args-call'.

   When dynamic linking is disabled or not supported on your system,
the above functions throw errors, but they are still available.

   Here is a small example that works on GNU/Linux:

     (define libc-obj (dynamic-link "libc.so"))
     libc-obj
     => #<dynamic-object "libc.so">
     (dynamic-args-call 'rand libc-obj '())
     => 269167349
     (dynamic-unlink libc-obj)
     libc-obj
     => #<dynamic-object "libc.so" (unlinked)>

   As you can see, after calling `dynamic-unlink' on a dynamically
linked library, it is marked as `(unlinked)' and you are no longer able
to use it with `dynamic-call', etc.  Whether the library is really
removed from you program is system-dependent and will generally not
happen when some other parts of your program still use it.  In the
example above, `libc' is almost certainly not removed from your program
because it is badly needed by almost everything.

   The functions to call a function from a dynamically linked library,
`dynamic-call' and `dynamic-args-call', are not very powerful.  They
are mostly intended to be used for calling specially written
initialization functions that will then add new primitives to Guile.
For example, we do not expect that you will dynamically link `libX11'
with `dynamic-link' and then construct a beautiful graphical user
interface just by using `dynamic-call' and `dynamic-args-call'.
Instead, the usual way would be to write a special Guile<->X11 glue
library that has intimate knowledge about both Guile and X11 and does
whatever is necessary to make them inter-operate smoothly.  This glue
library could then be dynamically linked into a vanilla Guile
interpreter and activated by calling its initialization function.  That
function would add all the new types and primitives to the Guile
interpreter that it has to offer.

   From this setup the next logical step is to integrate these glue
libraries into the module system of Guile so that you can load new
primitives into a running system just as you can load new Scheme code.

   There is, however, another possibility to get a more thorough access
to the functions contained in a dynamically linked library.  Anthony
Green has written `libffi', a library that implements a "foreign
function interface" for a number of different platforms.  With it, you
can extend the Spartan functionality of `dynamic-call' and
`dynamic-args-call' considerably.  There is glue code available in the
Guile contrib archive to make `libffi' accessible from Guile.


File: guile.info,  Node: Extensions,  Prev: Low level dynamic linking,  Up: Dynamic Libraries

Writing Dynamically Loadable Extensions
---------------------------------------

   XXX - document `load-extension', `scm_register_extension'


File: guile.info,  Node: Variables,  Prev: Dynamic Libraries,  Up: Modules

Variables
=========

   Each module has its own hash table, sometimes known as an "obarray",
that maps the names defined in that module to their corresponding
variable objects.

   A variable is a box-like object that can hold any Scheme value.  It
is said to be "undefined" if its box holds a special Scheme value that
denotes undefined-ness (which is different from all other Scheme values,
including for example `#f'); otherwise the variable is "defined".

   On its own, a variable object is anonymous.  A variable is said to be
"bound" when it is associated with a name in some way, usually a symbol
in a module obarray.  When this happens, the relationship is mutual:
the variable is bound to the name (in that module), and the name (in
that module) is bound to the variable.

   (That's the theory, anyway.  In practice, defined-ness and bound-ness
sometimes get confused, because Lisp and Scheme implementations have
often conflated -- or deliberately drawn no distinction between -- a
name that is unbound and a name that is bound to a variable whose value
is undefined.  We will try to be clear about the difference and explain
any confusion where it is unavoidable.)

   Variables do not have a read syntax.  Most commonly they are created
and bound implicitly by `define' expressions: a top-level `define'
expression of the form

     (define NAME VALUE)

creates a variable with initial value VALUE and binds it to the name
NAME in the current module.  But they can also be created dynamically
by calling one of the constructor procedures `make-variable' and
`make-undefined-variable'.

   First-class variables are especially useful for interacting with the
current module system (*note The Guile module system::).

 - Scheme Procedure: make-undefined-variable
 - C Function: scm_make_undefined_variable ()
     Return a variable that is initially unbound.

 - Scheme Procedure: make-variable init
 - C Function: scm_make_variable (init)
     Return a variable initialized to value INIT.

 - Scheme Procedure: variable-bound? var
 - C Function: scm_variable_bound_p (var)
     Return `#t' iff VAR is bound to a value.  Throws an error if VAR
     is not a variable object.

 - Scheme Procedure: variable-ref var
 - C Function: scm_variable_ref (var)
     Dereference VAR and return its value.  VAR must be a variable
     object; see `make-variable' and `make-undefined-variable'.

 - Scheme Procedure: variable-set! var val
 - C Function: scm_variable_set_x (var, val)
     Set the value of the variable VAR to VAL.  VAR must be a variable
     object, VAL can be any value. Return an unspecified value.

 - Scheme Procedure: variable? obj
 - C Function: scm_variable_p (obj)
     Return `#t' iff OBJ is a variable object, else return `#f'.


File: guile.info,  Node: Scheduling,  Next: Options and Config,  Prev: Modules,  Up: Top

Threads, Mutexes, Asyncs and Dynamic Roots
******************************************

   [FIXME: This is pasted in from Tom Lord's original guile.texi chapter
plus the Cygnus programmer's manual; it should be *very* carefully
reviewed and largely reorganized.]

* Menu:

* Arbiters::            Synchronization primitives.
* Asyncs::              Asynchronous procedure invocation.
* Dynamic Roots::       Root frames of execution.
* Threads::             Multiple threads of execution.
* Fluids::              Dynamically scoped variables.


File: guile.info,  Node: Arbiters,  Next: Asyncs,  Up: Scheduling

Arbiters
========

   Arbiters are synchronization objects.  They are created with
`make-arbiter'.  Two or more threads can synchronize on an arbiter by
trying to lock it using `try-arbiter'.  This call will succeed if no
other thread has called `try-arbiter' on the arbiter yet, otherwise it
will fail and return `#f'.  Once an arbiter is successfully locked, it
cannot be locked by another thread until the thread holding the arbiter
calls `release-arbiter' to unlock it.

 - Scheme Procedure: make-arbiter name
 - C Function: scm_make_arbiter (name)
     Return an object of type arbiter and name NAME. Its state is
     initially unlocked.  Arbiters are a way to achieve process
     synchronization.

 - Scheme Procedure: try-arbiter arb
 - C Function: scm_try_arbiter (arb)
     Return `#t' and lock the arbiter ARB if the arbiter was unlocked.
     Otherwise, return `#f'.

 - Scheme Procedure: release-arbiter arb
 - C Function: scm_release_arbiter (arb)
     Return `#t' and unlock the arbiter ARB if the arbiter was locked.
     Otherwise, return `#f'.


File: guile.info,  Node: Asyncs,  Next: Dynamic Roots,  Prev: Arbiters,  Up: Scheduling

Asyncs
======

   An async is a pair of one thunk (a parameterless procedure) and a
mark.  Setting the mark on an async guarantees that the thunk will be
executed somewhen in the future ("asynchronously").  Setting the mark
more than once is satisfied by one execution of the thunk.

   Guile supports two types of asyncs: Normal asyncs and system asyncs.
They differ in that marked system asyncs are executed implicitly as soon
as possible, whereas normal asyncs have to be invoked explicitly.
System asyncs are held in an internal data structure and are maintained
by Guile.

   Normal asyncs are created with `async', system asyncs with
`system-async'.  They are marked with `async-mark' or
`system-async-mark', respectively.

 - Scheme Procedure: async thunk
 - C Function: scm_async (thunk)
     Create a new async for the procedure THUNK.

 - Scheme Procedure: system-async thunk
 - C Function: scm_system_async (thunk)
     Create a new async for the procedure THUNK.  Also add it to the
     system's list of active async objects.

 - Scheme Procedure: async-mark a
 - C Function: scm_async_mark (a)
     Mark the async A for future execution.

 - Scheme Procedure: system-async-mark a
 - C Function: scm_system_async_mark (a)
     Mark the async A for future execution.

   As already mentioned above, system asyncs are executed automatically.
Normal asyncs have to be explicitly invoked by storing one or more of
them into a list and passing them to `run-asyncs'.

 - Scheme Procedure: run-asyncs list_of_a
 - C Function: scm_run_asyncs (list_of_a)
     Execute all thunks from the asyncs of the list LIST_OF_A.

   Automatic invocation of system asyncs can be temporarily disabled by
calling `mask-signals' and `unmask-signals'.  Setting the mark while
async execution is disabled will nevertheless cause the async to run
once execution is enabled again.  Please note that calls to these
procedures should always be paired, and they must not be nested, e.g. no
`mask-signals' is allowed if another one is still active.

 - Scheme Procedure: mask-signals
 - C Function: scm_mask_signals ()
     Mask signals. The returned value is not specified.

 - Scheme Procedure: unmask-signals
 - C Function: scm_unmask_signals ()
     Unmask signals. The returned value is not specified.

 - Scheme Procedure: noop . args
 - C Function: scm_noop (args)
     Do nothing.  When called without arguments, return `#f', otherwise
     return the first argument.


File: guile.info,  Node: Dynamic Roots,  Next: Threads,  Prev: Asyncs,  Up: Scheduling

Dynamic Roots
=============

   A "dynamic root" is a root frame of Scheme evaluation.  The
top-level repl, for example, is an instance of a dynamic root.

   Each dynamic root has its own chain of dynamic-wind information.
Each has its own set of continuations, jump-buffers, and pending CATCH
statements which are inaccessible from the dynamic scope of any other
dynamic root.

   In a thread-based system, each thread has its own dynamic root.
Therefore, continuations created by one thread may not be invoked by
another.

   Even in a single-threaded system, it is sometimes useful to create a
new dynamic root.  For example, if you want to apply a procedure, but to
not allow that procedure to capture the current continuation, calling
the procedure under a new dynamic root will do the job.

 - Scheme Procedure: call-with-dynamic-root thunk handler
 - C Function: scm_call_with_dynamic_root (thunk, handler)
     Evaluate `(thunk)' in a new dynamic context, returning its value.

     If an error occurs during evaluation, apply HANDLER to the
     arguments to the throw, just as `throw' would.  If this happens,
     HANDLER is called outside the scope of the new root - it is called
     in the same dynamic context in which `call-with-dynamic-root' was
     evaluated.

     If THUNK captures a continuation, the continuation is rooted at
     the call to THUNK.  In particular, the call to
     `call-with-dynamic-root' is not captured.  Therefore,
     `call-with-dynamic-root' always returns at most one time.

     Before calling THUNK, the dynamic-wind chain is un-wound back to
     the root and a new chain started for THUNK.  Therefore, this call
     may not do what you expect:

          ;; Almost certainly a bug:
          (with-output-to-port
           some-port
          
           (lambda ()
             (call-with-dynamic-root
              (lambda ()
                (display 'fnord)
                (newline))
              (lambda (errcode) errcode))))

     The problem is, on what port will `fnord' be displayed?  You might
     expect that because of the `with-output-to-port' that it will be
     displayed on the port bound to `some-port'.  But it probably won't
     - before evaluating the thunk, dynamic winds are unwound,
     including those created by `with-output-to-port'.  So, the
     standard output port will have been re-set to its default value
     before `display' is evaluated.

     (This function was added to Guile mostly to help calls to
     functions in C libraries that can not tolerate non-local exits or
     calls that return multiple times.  If such functions call back to
     the interpreter, it should be under a new dynamic root.)

 - Scheme Procedure: dynamic-root
 - C Function: scm_dynamic_root ()
     Return an object representing the current dynamic root.

     These objects are only useful for comparison using `eq?'.  They
     are currently represented as numbers, but your code should in no
     way depend on this.

 - Scheme Procedure: quit [exit_val]
     Throw back to the error handler of the current dynamic root.

     If integer EXIT_VAL is specified and if Guile is being used
     stand-alone and if quit is called from the initial dynamic-root,
     EXIT_VAL becomes the exit status of the Guile process and the
     process exits.

   When Guile is run interactively, errors are caught from within the
read-eval-print loop.  An error message will be printed and `abort'
called.  A default set of signal handlers is installed, e.g., to allow
user interrupt of the interpreter.

   It is possible to switch to a "batch mode", in which the interpreter
will terminate after an error and in which all signals cause their
default actions.  Switching to batch mode causes any handlers installed
from Scheme code to be removed.  An example of where this is useful is
after forking a new process intended to run non-interactively.

 - Scheme Procedure: batch-mode?
     Returns a boolean indicating whether the interpreter is in batch
     mode.

 - Scheme Procedure: set-batch-mode?! arg
     If ARG is true, switches the interpreter to batch mode.  The `#f'
     case has not been implemented.


File: guile.info,  Node: Threads,  Next: Fluids,  Prev: Dynamic Roots,  Up: Scheduling

Threads
=======

   *[NOTE: this chapter was written for Cygnus Guile and has not yet
been updated for the Guile 1.x release.]*

   Here is a the reference for Guile's threads.  In this chapter I
simply quote verbatim Tom Lord's description of the low-level primitives
written in C (basically an interface to the POSIX threads library) and
Anthony Green's description of the higher-level thread procedures
written in scheme.

   When using Guile threads, keep in mind that each guile thread is
executed in a new dynamic root.

* Menu:

* Low level thread primitives::
* Higher level thread procedures::


File: guile.info,  Node: Low level thread primitives,  Next: Higher level thread procedures,  Up: Threads

Low level thread primitives
---------------------------

 - Scheme Procedure: call-with-new-thread thunk error-handler
     Evaluate `(thunk)' in a new thread, and new dynamic context,
     returning a new thread object representing the thread.

     If an error occurs during evaluation, call error-handler, passing
     it an error code describing the condition.  [Error codes are
     currently meaningless integers.  In the future, real values will
     be specified.]  If this happens, the error-handler is called
     outside the scope of the new root - it is called in the same
     dynamic context in which with-new-thread was evaluated, but not in
     the caller's thread.

     All the evaluation rules for dynamic roots apply to threads.

 - Scheme Procedure: join-thread thread
     Suspend execution of the calling thread until the target THREAD
     terminates, unless the target THREAD has already terminated.

 - Scheme Procedure: yield
     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.

 - Scheme Procedure: make-mutex
     Create a new mutex object.

 - Scheme Procedure: lock-mutex mutex
     Lock MUTEX. If the mutex is already locked, the calling thread
     blocks until the mutex becomes available. The function returns when
     the calling thread owns the lock on MUTEX.

 - Scheme Procedure: unlock-mutex mutex
     Unlocks MUTEX if the calling thread owns the lock on MUTEX.
     Calling unlock-mutex on a mutex not owned by the current thread
     results in undefined behaviour. Once a mutex has been unlocked,
     one thread blocked on MUTEX is awakened and grabs the mutex lock.

 - Scheme Procedure: make-condition-variable

 - Scheme Procedure: wait-condition-variable cond-var mutex

 - Scheme Procedure: signal-condition-variable cond-var


File: guile.info,  Node: Higher level thread procedures,  Prev: Low level thread primitives,  Up: Threads

Higher level thread procedures
------------------------------

   Higher level thread procedures are available by loading the `(ice-9
threads)' module.  These provide standardized thread creation and mutex
interaction.

 - Scheme Procedure: %thread-handler tag args...
     This procedure is specified as the standard error-handler for
     `make-thread' and `begin-thread'.  If the number of ARGS is three
     or more, use `display-error', otherwise display a message
     "uncaught throw to TAG".  All output is sent to the port specified
     by `current-error-port'.

     Before display, global var `the-last-stack' is set to `#f' and
     signals are unmasked with `unmask-signals'.

     [FIXME: Why distinguish based on number of args?!  Cue voodoo
     music here.]

 - macro: make-thread proc [args...]
     Apply PROC to ARGS in a new thread formed by
     `call-with-new-thread' using `%thread-handler' as the error
     handler.

 - macro: begin-thread first [rest...]
     Evaluate forms FIRST and REST in a new thread formed by
     `call-with-new-thread' using `%thread-handler' as the error
     handler.

 - macro: with-mutex m [body...]
     Lock mutex M, evaluate BODY, and then unlock M.  These
     sub-operations form the branches of a `dynamic-wind'.

 - macro: monitor first [rest...]
     Evaluate forms FIRST and REST under a newly created anonymous
     mutex, using `with-mutex'.

     [FIXME: Is there any way to access the mutex?]


File: guile.info,  Node: Fluids,  Prev: Threads,  Up: Scheduling

Fluids
======

   Fluids are objects to store values in.  They have a few properties
which make them useful in certain situations: Fluids can have one value
per dynamic root (*note Dynamic Roots::), so that changes to the value
in a fluid are only visible in the same dynamic root.  Since threads are
executed in separate dynamic roots, fluids can be used for thread local
storage (*note Threads::).

   Fluids can be used to simulate dynamically scoped variables.  These
are used in several (especially in older) dialects of lisp, such as in
Emacs Lisp, and they work a bit like global variables in that they can
be modified by the caller of a procedure, and the called procedure will
see the changes.  With lexically scoped variables--which are normally
used in Scheme--this cannot happen.  See the description of
`with-fluids*' below for details.

   New fluids are created with `make-fluid' and `fluid?' is used for
testing whether an object is actually a fluid.

 - Scheme Procedure: make-fluid
 - C Function: scm_make_fluid ()
     Return a newly created fluid.  Fluids are objects of a certain
     type (a smob) that can hold one SCM value per dynamic root.  That
     is, modifications to this value are only visible to code that
     executes within the same dynamic root as the modifying code.  When
     a new dynamic root is constructed, it inherits the values from its
     parent.  Because each thread executes in its own dynamic root, you
     can use fluids for thread local storage.

 - Scheme Procedure: fluid? obj
 - C Function: scm_fluid_p (obj)
     Return `#t' iff OBJ is a fluid; otherwise, return `#f'.

   The values stored in a fluid can be accessed with `fluid-ref' and
`fluid-set!'.

 - Scheme Procedure: fluid-ref fluid
 - C Function: scm_fluid_ref (fluid)
     Return the value associated with FLUID in the current dynamic
     root.  If FLUID has not been set, then return `#f'.

 - Scheme Procedure: fluid-set! fluid value
 - C Function: scm_fluid_set_x (fluid, value)
     Set the value associated with FLUID in the current dynamic root.

   `with-fluids*' temporarily changes the values of one or more fluids,
so that the given procedure and each procedure called by it access the
given values.  After the procedure returns, the old values are restored.

 - Scheme Procedure: with-fluids* fluids values thunk
 - C Function: scm_with_fluids (fluids, values, thunk)
     Set FLUIDS to VALUES temporary, and call THUNK.  FLUIDS must be a
     list of fluids and VALUES must be the same number of their values
     to be applied.  Each substitution is done one after another.
     THUNK must be a procedure with no argument.


File: guile.info,  Node: Options and Config,  Next: Translation,  Prev: Scheduling,  Up: Top

Configuration, Features and Runtime Options
*******************************************

   Why is my Guile different from your Guile?  There are three kinds of
possible variation:

   * build differences -- different versions of the Guile source code,
     installation directories, configuration flags that control pieces
     of functionality being included or left out, etc.

   * differences in dynamically loaded code -- behaviour and features
     provided by modules that can be dynamically loaded into a running
     Guile

   * different runtime options -- some of the options that are provided
     for controlling Guile's behaviour may be set differently.

   Guile provides "introspective" variables and procedures to query all
of these possible variations at runtime.  For runtime options, it also
provides procedures to change the settings of options and to obtain
documentation on what the options mean.

* Menu:

* Build Config::                Build and installation configuration.
* Feature Tracking::            Available features in the Guile process.
* Runtime Options::             Controlling Guile's runtime behaviour.


File: guile.info,  Node: Build Config,  Next: Feature Tracking,  Up: Options and Config

Configuration, Build and Installation
=====================================

   The following procedures and variables provide information about how
Guile was configured, built and installed on your system.

 - Scheme Procedure: version
 - Scheme Procedure: effective-version
 - Scheme Procedure: major-version
 - Scheme Procedure: minor-version
 - Scheme Procedure: micro-version
 - C Function: scm_version ()
 - C Function: scm_effective_version ()
 - C Function: scm_major_version ()
 - C Function: scm_minor_version ()
 - C Function: scm_micro_version ()
     Return a string describing Guile's full version number, effective
     version number, major, minor or micro version number, respectively.
     The `effective-version' function returns the version name that
     should remain unchanged during a stable series.  Currently that
     means that it omits the micro version.  The effective version
     should be used for items like the versioned share directory name
     i.e. `/usr/share/guile/1.6/'

          (version) => "1.6.0"
          (effective-version) => "1.6"
          (major-version) => "1"
          (minor-version) => "6"
          (micro-version) => "0"

 - Scheme Procedure: %package-data-dir
 - C Function: scm_sys_package_data_dir ()
     Return the name of the directory under which Guile Scheme files in
     general are stored.  On Unix-like systems, this is usually
     `/usr/local/share/guile' or `/usr/share/guile'.

 - Scheme Procedure: %library-dir
 - C Function: scm_sys_library_dir ()
     Return the name of the directory where the Guile Scheme files that
     belong to the core Guile installation (as opposed to files from a
     3rd party package) are installed.  On Unix-like systems, this is
     usually `/usr/local/share/guile/<GUILE_EFFECTIVE_VERSION>' or
     `/usr/share/guile/<GUILE_EFFECTIVE_VERSION>', for example:
     `/usr/local/share/guile/1.6'.

 - Scheme Procedure: %site-dir
 - C Function: scm_sys_site_dir ()
     Return the name of the directory where Guile Scheme files specific
     to your site should be installed.  On Unix-like systems, this is
     usually `/usr/local/share/guile/site' or `/usr/share/guile/site'.

 - Variable: %load-path
     List of directories which should be searched for Scheme modules and
     libraries.  `%load-path' is initialized when Guile starts up to
     `(list (%site-dir) (%library-dir) (%package-data-dir) ".")',
     prepended with the contents of the GUILE_LOAD_PATH environment
     variable, if it is set.

 - Scheme Procedure: parse-path path [tail]
 - C Function: scm_parse_path (path, tail)
     Parse PATH, which is expected to be a colon-separated string, into
     a list and return the resulting list with TAIL appended. If PATH
     is `#f', TAIL is returned.

 - Scheme Procedure: search-path path filename [extensions]
 - C Function: scm_search_path (path, filename, extensions)
     Search PATH for a directory containing a file named FILENAME. The
     file must be readable, and not a directory.  If we find one,
     return its full filename; otherwise, return `#f'.  If FILENAME is
     absolute, return it unchanged.  If given, EXTENSIONS is a list of
     strings; for each directory in PATH, we search for FILENAME
     concatenated with each EXTENSION.

 - Variable: %guile-build-info
     Alist of information collected during the building of a particular
     Guile.  Entries can be grouped into one of several categories:
     directories, env vars, and versioning info.

     Briefly, here are the keys in `%guile-build-info', by group:

    directories
          srcdir, top_srcdir, prefix, exec_prefix, bindir, sbindir,
          libexecdir, datadir, sysconfdir, sharedstatedir,
          localstatedir, libdir, infodir, mandir, includedir,
          pkgdatadir, pkglibdir, pkgincludedir

    env vars
          LIBS

    versioning info
          guileversion, libguileinterface, buildstamp

     Values are all strings.  The value for `LIBS' is typically found
     also as a part of "guile-config link" output.  The value for
     `guileversion' has form X.Y.Z, and should be the same as returned
     by `(version)'.  The value for `libguileinterface' is libtool
     compatible and has form CURRENT:REVISION:AGE.  The value for
     `buildstamp' is the output of the date(1) command.

     In the source, `%guile-build-info' is initialized from
     libguile/libpath.h, which is completely generated, so deleting
     this file before a build guarantees up-to-date values for that
     build.


File: guile.info,  Node: Feature Tracking,  Next: Runtime Options,  Prev: Build Config,  Up: Options and Config

Feature Tracking
================

   Guile has a Scheme level variable `*features*' that keeps track to
some extent of the features that are available in a running Guile.
`*features*' is a list of symbols, for example `threads', each of which
describes a feature of the running Guile process.

 - Variable: *features*
     A list of symbols describing available features of the Guile
     process.

   You shouldn't modify the `*features*' variable directly using
`set!'.  Instead, see the procedures that are provided for this purpose
in the following subsection.

* Menu:

* Feature Manipulation::        Checking for and advertising features.
* Common Feature Symbols::      Commonly available features.


File: guile.info,  Node: Feature Manipulation,  Next: Common Feature Symbols,  Up: Feature Tracking

Feature Manipulation
--------------------

   To check whether a particular feature is available, use the
`provided?' procedure:

 - Scheme Procedure: provided? feature
 - Deprecated Scheme Procedure: feature? feature
     Return `#t' if the specified FEATURE is available, otherwise `#f'.

   To advertise a feature from your own Scheme code, you can use the
`provide' procedure:

 - Scheme Procedure: provide feature
     Add FEATURE to the list of available features in this Guile
     process.

   For C code, the equivalent function takes its feature name as a
`char *' argument for convenience:

 - C Function: void scm_add_feature (const char *str)
     Add a symbol with name STR to the list of available features in
     this Guile process.


File: guile.info,  Node: Common Feature Symbols,  Prev: Feature Manipulation,  Up: Feature Tracking

Common Feature Symbols
----------------------

   In general, a particular feature may be available for one of two
reasons.  Either because the Guile library was configured and compiled
with that feature enabled -- i.e. the feature is built into the library
on your system.  Or because some C or Scheme code that was dynamically
loaded by Guile has added that feature to the list.

   In the first category, here are the features that the current
version of Guile may define (depending on how it is built), and what
they mean.

`array'
     Indicates support for arrays (*note Arrays::).

`array-for-each'
     Indicates availability of `array-for-each' and other array mapping
     procedures (*note Array Mapping::).

`char-ready?'
     Indicates that the `char-ready?' function is available (*note
     Reading::).

`complex'
     Indicates support for complex numbers.

`current-time'
     Indicates availability of time-related functions: `times',
     `get-internal-run-time' and so on (*note Time::).

`debug-extensions'
     Indicates that the debugging evaluator is available, together with
     the options for controlling it.

`delay'
     Indicates support for promises (*note Delayed Evaluation::).

`EIDs'
     Indicates that the `geteuid' and `getegid' really return effective
     user and group IDs (*note Processes::).

`inexact'
     Indicates support for inexact numbers.

`i/o-extensions'
     Indicates availability of the following extended I/O procedures:
     `ftell', `redirect-port', `dup->fdes', `dup2', `fileno',
     `isatty?', `fdopen', `primitive-move->fdes' and `fdes->ports'
     (*note Ports and File Descriptors::).

`net-db'
     Indicates availability of network database functions:
     `scm_gethost', `scm_getnet', `scm_getproto', `scm_getserv',
     `scm_sethost', `scm_setnet', `scm_setproto', `scm_setserv', and
     their `byXXX' variants (*note Network Databases::).

`posix'
     Indicates support for POSIX functions: `pipe', `getgroups',
     `kill', `execl' and so on (*note POSIX::).

`random'
     Indicates availability of random number generation functions:
     `random', `copy-random-state', `random-uniform' and so on (*note
     Random::).

`reckless'
     Indicates that Guile was built with important checks omitted -- you
     should never see this!

`regex'
     Indicates support for POSIX regular expressions using
     `make-regexp', `regexp-exec' and friends (*note Regexp
     Functions::).

`socket'
     Indicates availability of socket-related functions: `socket',
     `bind', `connect' and so on (*note Network Sockets and
     Communication::).

`sort'
     Indicates availability of sorting and merging functions (*note
     Sorting::).

`system'
     Indicates that the `system' function is available (*note
     Processes::).

`threads'
     Indicates support for multithreading (*note Threads::).

`values'
     Indicates support for multiple return values using `values' and
     `call-with-values' (*note Multiple Values::).

   Available features in the second category depend, by definition, on
what additional code your Guile process has loaded in.  The following
table lists features that you might encounter for this reason.

`defmacro'
     Indicates that the `defmacro' macro is available (*note Macros::).

`describe'
     Indicates that the `(oop goops describe)' module has been loaded,
     which provides a procedure for describing the contents of GOOPS
     instances.

`readline'
     Indicates that Guile has loaded in Readline support, for command
     line editing (*note Readline Support::).

`record'
     Indicates support for record definition using `make-record-type'
     and friends (*note Records::).

   Although these tables may seem exhaustive, it is probably unwise in
practice to rely on them, as the correspondences between feature symbols
and available procedures/behaviour are not strictly defined.  If you are
writing code that needs to check for the existence of some procedure, it
is probably safer to do so directly using the `defined?' procedure than
to test for the corresponding feature using `feature?'.


File: guile.info,  Node: Runtime Options,  Prev: Feature Tracking,  Up: Options and Config

Runtime Options
===============

   Guile's runtime behaviour can be modified by setting options.  For
example, is the language that Guile accepts case sensitive, or should
the debugger automatically show a backtrace on error?

   Guile has two levels of interface for managing options: a low-level
control interface, and a user-level interface which allows the enabling
or disabling of options.

   Moreover, the options are classified in groups according to whether
they configure _reading_, _printing_, _debugging_ or _evaluating_.

* Menu:

* Low level options interfaces::
* User level options interfaces::
* Reader options::
* Printing options::
* Debugger options::
* Evaluator options::
* Evaluator trap options::
* Examples of option use::


File: guile.info,  Node: Low level options interfaces,  Next: User level options interfaces,  Up: Runtime Options

Low Level Options Interfaces
----------------------------

 - Scheme Procedure: read-options-interface [setting]
 - Scheme Procedure: eval-options-interface [setting]
 - Scheme Procedure: print-options-interface [setting]
 - Scheme Procedure: debug-options-interface [setting]
 - Scheme Procedure: evaluator-traps-interface [setting]
 - C Function: scm_read_options (setting)
 - C Function: scm_eval_options_interface (setting)
 - C Function: scm_print_options (setting)
 - C Function: scm_debug_options (setting)
 - C Function: scm_evaluator_traps (setting)
     If one of these procedures is called with no arguments (or with
     `setting == SCM_UNDEFINED' in C code), it returns a list describing
     the current setting of the read, eval, print, debug or evaluator
     traps options respectively.  The setting of a boolean option is
     indicated simply by the presence or absence of the option symbol
     in the list.  The setting of a non-boolean option is indicated by
     the presence of the option symbol immediately followed by the
     option's current value.

     If called with a list argument, these procedures interpret the
     list as an option setting and modify the relevant options
     accordingly.  [FIXME -- this glosses over a lot of details!]

     If called with any other argument, such as `'help', these
     procedures return a list of entries like `(OPTION-SYMBOL
     DEFAULT-VALUE DOC-STRING)', with each entry giving the default
     value and documentation for each option symbol in the relevant set
     of options.


File: guile.info,  Node: User level options interfaces,  Next: Reader options,  Prev: Low level options interfaces,  Up: Runtime Options

User Level Options Interfaces
-----------------------------

 - Scheme Procedure: <group>-options [arg]
 - Scheme Procedure: read-options [arg]
 - Scheme Procedure: print-options [arg]
 - Scheme Procedure: debug-options [arg]
 - Scheme Procedure: traps [arg]
     These functions list the options in their group.  The optional
     argument ARG is a symbol which modifies the form in which the
     options are presented.

     With no arguments, `<group>-options' returns the values of the
     options in that particular group.  If ARG is `'help', a
     description of each option is given.  If ARG is `'full',
     programmers' options are also shown.

     ARG can also be a list representing the state of all options.  In
     this case, the list contains single symbols (for enabled boolean
     options) and symbols followed by values.
   [FIXME: I don't think 'full is ever any different from 'help.  What's
up?]

 - Scheme Procedure: <group>-enable option-symbol
 - Scheme Procedure: read-enable option-symbol
 - Scheme Procedure: print-enable option-symbol
 - Scheme Procedure: debug-enable option-symbol
 - Scheme Procedure: trap-enable option-symbol
     These functions set the specified OPTION-SYMBOL in their options
     group.  They only work if the option is boolean, and throw an error
     otherwise.

 - Scheme Procedure: <group>-disable option-symbol
 - Scheme Procedure: read-disable option-symbol
 - Scheme Procedure: print-disable option-symbol
 - Scheme Procedure: debug-disable option-symbol
 - Scheme Procedure: trap-disable option-symbol
     These functions turn off the specified OPTION-SYMBOL in their
     options group.  They only work if the option is boolean, and throw
     an error otherwise.

 - syntax: <group>-set! option-symbol value
 - syntax: read-set! option-symbol value
 - syntax: print-set! option-symbol value
 - syntax: debug-set! option-symbol value
 - syntax: trap-set! option-symbol value
     These functions set a non-boolean OPTION-SYMBOL to the specified
     VALUE.


File: guile.info,  Node: Reader options,  Next: Printing options,  Prev: User level options interfaces,  Up: Runtime Options

Reader options
--------------

   Here is the list of reader options generated by typing
`(read-options 'full)' in Guile.  You can also see the default values.

     keywords         #f      Style of keyword recognition: #f or 'prefix
     case-insensitive no      Convert symbols to lower case.
     positions        yes     Record positions of source code expressions.
     copy             no      Copy source code expressions.

   Notice that while Standard Scheme is case insensitive, to ease
translation of other Lisp dialects, notably Emacs Lisp, into Guile,
Guile is case-sensitive by default.

   To make Guile case insensitive, you can type

     (read-enable 'case-insensitive)


File: guile.info,  Node: Printing options,  Next: Debugger options,  Prev: Reader options,  Up: Runtime Options

Printing options
----------------

   Here is the list of print options generated by typing
`(print-options 'full)' in Guile.  You can also see the default values.

     source          no      Print closures with source.
     closure-hook    #f      Hook for printing closures.


File: guile.info,  Node: Evaluator options,  Next: Evaluator trap options,  Prev: Debugger options,  Up: Runtime Options

Evaluator options
-----------------

   These are the evaluator options with their default values, as they
are printed by typing `(eval-options 'full)' in Guile.

     stack           22000   Size of thread stacks (in machine words).

