From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Marius Vollmer Newsgroups: gmane.lisp.guile.user Subject: Some new reference docs about initialization Date: Mon, 24 Jan 2005 20:31:00 +0100 Message-ID: References: NNTP-Posting-Host: deer.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: sea.gmane.org 1106596172 1980 80.91.229.6 (24 Jan 2005 19:49:32 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Mon, 24 Jan 2005 19:49:32 +0000 (UTC) Original-X-From: guile-user-bounces+guile-user=m.gmane.org@gnu.org Mon Jan 24 20:49:20 2005 Return-path: Original-Received: from lists.gnu.org ([199.232.76.165]) by deer.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 1CtAD9-00051G-00 for ; Mon, 24 Jan 2005 20:49:19 +0100 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1CtAPN-0003Cd-4u for guile-user@m.gmane.org; Mon, 24 Jan 2005 15:01:57 -0500 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1CtAMM-00020k-CA for guile-user@gnu.org; Mon, 24 Jan 2005 14:58:50 -0500 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1CtAMD-0001vX-7u for guile-user@gnu.org; Mon, 24 Jan 2005 14:58:41 -0500 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1CtAMC-0001qV-Ug for guile-user@gnu.org; Mon, 24 Jan 2005 14:58:41 -0500 Original-Received: from [129.217.163.1] (helo=mail.dt.e-technik.uni-dortmund.de) by monty-python.gnu.org with esmtp (Exim 4.34) id 1Ct9vS-00052r-7D for guile-user@gnu.org; Mon, 24 Jan 2005 14:31:02 -0500 Original-Received: from localhost (localhost [127.0.0.1]) by mail.dt.e-technik.uni-dortmund.de (Postfix) with ESMTP id 9EA4144235 for ; Mon, 24 Jan 2005 20:31:01 +0100 (CET) Original-Received: from mail.dt.e-technik.uni-dortmund.de ([127.0.0.1]) by localhost (krusty [127.0.0.1]) (amavisd-new, port 10024) with LMTP id 01549-01-6 for ; Mon, 24 Jan 2005 20:31:01 +0100 (CET) Original-Received: from troy.dt.e-technik.uni-dortmund.de (troy.dt.e-technik.uni-dortmund.de [129.217.163.17]) by mail.dt.e-technik.uni-dortmund.de (Postfix) with ESMTP id 0027444232 for ; Mon, 24 Jan 2005 20:31:00 +0100 (CET) Original-Received: by troy.dt.e-technik.uni-dortmund.de (Postfix, from userid 520) id AF57FB99F; Mon, 24 Jan 2005 20:31:00 +0100 (CET) Original-To: guile-user@gnu.org In-Reply-To: (Marius Vollmer's message of "Fri, 21 Jan 2005 19:29:35 +0100") User-Agent: Gnus/5.1003 (Gnus v5.10.3) Emacs/21.3 (gnu/linux) X-Virus-Scanned: by amavisd-new at dt.e-technik.uni-dortmund.de X-BeenThere: guile-user@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: General Guile related discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: guile-user-bounces+guile-user=m.gmane.org@gnu.org Errors-To: guile-user-bounces+guile-user=m.gmane.org@gnu.org Xref: main.gmane.org gmane.lisp.guile.user:4152 X-Report-Spam: http://spam.gmane.org/gmane.lisp.guile.user:4152 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. _______________________________________________ Guile-user mailing list Guile-user@gnu.org http://lists.gnu.org/mailman/listinfo/guile-user