Some new reference docs about initialization

[Marius Vollmer]

What do you think?

5.3 Initializing Guile
======================

Each thread that wants to use function from the Guile API needs to put
itself into guile mode with either `scm_with_guile' or
`scm_init_guile'.  The global state of Guile is initialized
automatically when the first thread enters guile mode.

   When a thread wants to block outside of a Guile API function, it
should leave guile mode temporarily with either `scm_without_guile' or
`scm_leave_guile', *Note Threads::.

 -- C Function: void *scm_with_guile (void *(*func)(void *), void *data)
     Call FUNC, passing it DATA and return what FUNC returns.  While
     FUNC is running, the current thread is in guile mode and can thus
     use the Guile API.

     When `scm_with_guile' is called from guile mode, the thread remains
     in guile mode when `scm_with_guile' returns.

     Otherwise, it puts the current thread into guile mode and, if
     needed, gives it a Scheme representation that is contained in the
     list returned by `all-threads', for example.  This Scheme
     representation is not removed when `scm_with_guile' returns so
     that a given thread is always represented by the same Scheme value
     during its lifetime, if at all.

     When this is the first thread that enters guile mode, the global
     state of Guile is initialized before calling `func'.

     When a throw happens while FUNC runs (such as a signalled error)
     that is not caught, a short message is printed to the current
     error port and `scm_with_guile' returns `NULL'.  When a
     continuation is invoked that would make the control flow cross
     this call to `scm_with_guile', an error will be signalled at the
     point of continuation invokation.  Thus, `scm_with_guile'
     guaranteed to return exactly once.

     When `scm_with_guile' returns, the thread is no longer in guile
     mode (except when `scm_with_guile' was called from guile mode, see
     above).  Thus, only `func' can store `SCM' variables on the stack
     and be sure that they are protected from the garbage collector.
     See `scm_init_guile' for another approach at initializing Guile
     that does not have this restriction.

     It is OK to call `scm_with_guile' while a thread has temporarily
     left guile mode via `scm_without_guile' or `scm_leave_guile'.  It
     will then simply temporarily enter guile mode again.

 -- C Function: void scm_init_guile ()
     Arrange things so as if all of the code of the current thread
     would be executed from within a call to `scm_with_guile'.  That
     is, all functions called by the current thread can assume that
     `SCM' values on their stack frames are protected from the garbage
     collector (except when the thread has explicitely left guile mode,
     of course).

     When `scm_init_guile' is called from a thread that already has been
     in guile mode once, nothing happens.  This behavior matters when
     you call `scm_init_guile' while the thread has only temporarily
     left guile mode: in that case the thread will not be in guile mode
     after `scm_init_guile' returns.  Thus, you should not use
     `scm_init_guile' in such a scenario.

     When a uncaught throw happens in a thread that has been put into
     guile mode via `scm_init_guile', a short message is printed to the
     current error port and the thread is exited via `scm_pthread_exit
     (NULL)'.  No restrictions are placed on continuations.

     The function `scm_init_guile' might not be available on all
     platforms since it requires some stack-bounds-finding magic that
     might not have been to all platforms that Guile runs on.  Thus, if
     you can, it is better to use `scm_with_guile' or its variation
     `scm_boot_guile' instead of this function.

 -- C Function: void scm_boot_guile (int ARGC, char **ARGV, void
          (*MAIN_FUNC) (void *DATA, int ARGC, char **ARGV), void *DATA)
     Enter guile mode as with `scm_with_guile' and call MAIN_FUNC,
     passing it DATA, ARGC, and ARGV as indicated.  When MAIN_FUNC
     returns, `scm_boot_guile' calls `exit (0)'; `scm_boot_guile' never
     returns.  If you want some other exit value, have MAIN_FUNC call
     `exit' itself.  If you don't want to exit at all, use
     `scm_with_guile' instead of `scm_boot_guile'.

     The function `scm_boot_guile' arranges for the Scheme
     `command-line' function to return the strings given by ARGC and
     ARGV.  If MAIN_FUNC modifies ARGC or ARGV, it should call
     `scm_set_program_arguments' with the final list, so Scheme code
     will know which arguments have been processed.

 -- C Function: void scm_shell (int ARGC, char **ARGV)
     Process command-line arguments in the manner of the `guile'
     executable.  This includes loading the normal Guile initialization
     files, interacting with the user or running any scripts or
     expressions specified by `-s' or `-e' options, and then exiting.
     *Note Invoking Guile::, for more details.

     Since this function does not return, you must do all
     application-specific initialization before calling this function.