guile18/doc/ref/api-init.texi

   1 @c -*-texinfo-*-
   2 @c This is part of the GNU Guile Reference Manual.
   3 @c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007
   4 @c   Free Software Foundation, Inc.
   5 @c See the file guile.texi for copying conditions.
   6
   7
   8 @node Initialization
   9 @section Initializing Guile
  10 @cindex Initializing Guile
  11
  12 Each thread that wants to use functions from the Guile API needs to
  13 put itself into guile mode with either @code{scm_with_guile} or
  14 @code{scm_init_guile}.  The global state of Guile is initialized
  15 automatically when the first thread enters guile mode.
  16
  17 When a thread wants to block outside of a Guile API function, it
  18 should leave guile mode temporarily with @code{scm_without_guile},
  19 @xref{Blocking}.
  20
  21 Threads that are created by @code{call-with-new-thread} or
  22 @code{scm_spawn_thread} start out in guile mode so you don't need to
  23 initialize them.
  24
  25 @deftypefn {C Function} {void *} scm_with_guile (void *(*func)(void *), void *data)
  26 Call @var{func}, passing it @var{data} and return what @var{func}
  27 returns.  While @var{func} is running, the current thread is in guile
  28 mode and can thus use the Guile API.
  29
  30 When @code{scm_with_guile} is called from guile mode, the thread remains
  31 in guile mode when @code{scm_with_guile} returns.
  32
  33 Otherwise, it puts the current thread into guile mode and, if needed,
  34 gives it a Scheme representation that is contained in the list returned
  35 by @code{all-threads}, for example.  This Scheme representation is not
  36 removed when @code{scm_with_guile} returns so that a given thread is
  37 always represented by the same Scheme value during its lifetime, if at
  38 all.
  39
  40 When this is the first thread that enters guile mode, the global state
  41 of Guile is initialized before calling @code{func}.
  42
  43 The function @var{func} is called via
  44 @code{scm_with_continuation_barrier}; thus, @code{scm_with_guile}
  45 returns exactly once.
  46
  47 When @code{scm_with_guile} returns, the thread is no longer in guile
  48 mode (except when @code{scm_with_guile} was called from guile mode, see
  49 above).  Thus, only @code{func} can store @code{SCM} variables on the
  50 stack and be sure that they are protected from the garbage collector.
  51 See @code{scm_init_guile} for another approach at initializing Guile
  52 that does not have this restriction.
  53
  54 It is OK to call @code{scm_with_guile} while a thread has temporarily
  55 left guile mode via @code{scm_without_guile}.  It will then simply
  56 temporarily enter guile mode again.
  57 @end deftypefn
  58
  59 @deftypefn {C Function} void scm_init_guile ()
  60 Arrange things so that all of the code in the current thread executes as
  61 if from within a call to @code{scm_with_guile}.  That is, all functions
  62 called by the current thread can assume that @code{SCM} values on their
  63 stack frames are protected from the garbage collector (except when the
  64 thread has explicitly left guile mode, of course).
  65
  66 When @code{scm_init_guile} is called from a thread that already has been
  67 in guile mode once, nothing happens.  This behavior matters when you
  68 call @code{scm_init_guile} while the thread has only temporarily left
  69 guile mode: in that case the thread will not be in guile mode after
  70 @code{scm_init_guile} returns.  Thus, you should not use
  71 @code{scm_init_guile} in such a scenario.
  72
  73 When a uncaught throw happens in a thread that has been put into guile
  74 mode via @code{scm_init_guile}, a short message is printed to the
  75 current error port and the thread is exited via @code{scm_pthread_exit
  76 (NULL)}.  No restrictions are placed on continuations.
  77
  78 The function @code{scm_init_guile} might not be available on all
  79 platforms since it requires some stack-bounds-finding magic that might
  80 not have been ported to all platforms that Guile runs on.  Thus, if you
  81 can, it is better to use @code{scm_with_guile} or its variation
  82 @code{scm_boot_guile} instead of this function.
  83 @end deftypefn
  84
  85 @deftypefn {C Function} void scm_boot_guile (int @var{argc}, char **@var{argv}, void (*@var{main_func}) (void *@var{data}, int @var{argc}, char **@var{argv}), void *@var{data})
  86 Enter guile mode as with @code{scm_with_guile} and call @var{main_func},
  87 passing it @var{data}, @var{argc}, and @var{argv} as indicated.  When
  88 @var{main_func} returns, @code{scm_boot_guile} calls @code{exit (0)};
  89 @code{scm_boot_guile} never returns.  If you want some other exit value,
  90 have @var{main_func} call @code{exit} itself.  If you don't want to exit
  91 at all, use @code{scm_with_guile} instead of @code{scm_boot_guile}.
  92
  93 The function @code{scm_boot_guile} arranges for the Scheme
  94 @code{command-line} function to return the strings given by @var{argc}
  95 and @var{argv}.  If @var{main_func} modifies @var{argc} or @var{argv},
  96 it should call @code{scm_set_program_arguments} with the final list, so
  97 Scheme code will know which arguments have been processed
  98 (@pxref{Runtime Environment}).
  99 @end deftypefn
 100
 101 @deftypefn {C Function} void scm_shell (int @var{argc}, char **@var{argv})
 102 Process command-line arguments in the manner of the @code{guile}
 103 executable.  This includes loading the normal Guile initialization
 104 files, interacting with the user or running any scripts or expressions
 105 specified by @code{-s} or @code{-e} options, and then exiting.
 106 @xref{Invoking Guile}, for more details.
 107
 108 Since this function does not return, you must do all
 109 application-specific initialization before calling this function.
 110 @end deftypefn