From mboxrd@z Thu Jan 1 00:00:00 1970 Path: main.gmane.org!not-for-mail From: Neil Jerram Newsgroups: gmane.lisp.guile.devel,gmane.lisp.guile.user Subject: Re: Doc organization (Re: Around again, and docs lead role) Date: 10 May 2003 13:01:44 +0100 Sender: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Message-ID: References: <3E92E1B4002B0632@pop3.tiscalinet.es> <3EAFE4EC000D9733@pop1.tiscalinet.es> <20030509081556.GB5437@www> NNTP-Posting-Host: main.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=us-ascii X-Trace: main.gmane.org 1052568421 17939 80.91.224.249 (10 May 2003 12:07:01 GMT) X-Complaints-To: usenet@main.gmane.org NNTP-Posting-Date: Sat, 10 May 2003 12:07:01 +0000 (UTC) Cc: guile-user@gnu.org Original-X-From: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Sat May 10 14:06:58 2003 Return-path: Original-Received: from monty-python.gnu.org ([199.232.76.173]) by main.gmane.org with esmtp (Exim 3.35 #1 (Debian)) id 19ET7x-0004ew-00 for ; Sat, 10 May 2003 14:06:57 +0200 Original-Received: from localhost ([127.0.0.1] helo=monty-python.gnu.org) by monty-python.gnu.org with esmtp (Exim 4.10.13) id 19ET6Y-0005Ir-00 for guile-devel@m.gmane.org; Sat, 10 May 2003 08:05:30 -0400 Original-Received: from list by monty-python.gnu.org with tmda-scanned (Exim 4.10.13) id 19ET5w-0005DU-00 for guile-devel@gnu.org; Sat, 10 May 2003 08:04:52 -0400 Original-Received: from mail by monty-python.gnu.org with spam-scanned (Exim 4.10.13) id 19ET5d-00054H-00 for guile-devel@gnu.org; Sat, 10 May 2003 08:04:34 -0400 Original-Received: from mail.uklinux.net ([80.84.72.21] helo=s1.uklinux.net) by monty-python.gnu.org with esmtp (Exim 4.10.13) id 19ET5G-0004vg-00; Sat, 10 May 2003 08:04:10 -0400 Original-Received: from laruns.ossau.uklinux.net (bts-0988.dialup.zetnet.co.uk [194.247.51.220]) by s1.uklinux.net (8.11.6p2/8.11.6) with ESMTP id h4AC3xw15732; Sat, 10 May 2003 13:03:59 +0100 Original-Received: from laruns.ossau.uklinux.net.ossau.uklinux.net (localhost [127.0.0.1])ESMTP id 18A90DC4D5; Sat, 10 May 2003 13:01:44 +0100 (BST) Original-To: tomas@fabula.de In-Reply-To: <20030509081556.GB5437@www> Original-Lines: 93 User-Agent: Gnus/5.0808 (Gnus v5.8.8) Emacs/20.7 Original-cc: guile-devel@gnu.org X-BeenThere: guile-devel@gnu.org X-Mailman-Version: 2.1b5 Precedence: list List-Id: Developers list for Guile, the GNU extensibility library List-Help: List-Post: List-Subscribe: , List-Archive: List-Unsubscribe: , Errors-To: guile-devel-bounces+guile-devel=m.gmane.org@gnu.org Xref: main.gmane.org gmane.lisp.guile.devel:2322 gmane.lisp.guile.user:1932 X-Report-Spam: http://spam.gmane.org/gmane.lisp.guile.devel:2322 >>>>> "tomas" == tomas writes: >> Interesting. It was my idea to document the whole Guile API in the >> current unified way, covering both C and Scheme together, but I have >> been wondering about whether that was a good decision. In many cases >> it seems to result in adding a subsection saying "And there are also >> these related C functions and macros ...", which feels unsatisfactory. tomas> There have been good answers to this elsewhere. As long as tomas> there is a (not necessarily exhaustive) good correspondence tomas> between C functions and Guile (with a way to know when to tomas> expect what), I'm fine. Not sure I understand. Are you saying that the relationship between how one codes a primitive in C, and how one calls it in Scheme, should be clearly described? If so, I agree. >> That's what I'm thinking now, anyway. I think (**) may be quite >> controversial, so that at least needs a lot more discussion first. tomas> To take the other side of the controverse ;-) tomas> There have been comments on this elsewhere already, mentioning tomas> mod-guile. I won't repeat those. What seemed missing to me (or tomas> I was asleep while reading, actually this happens .-) tomas> Embedding Guile in applications like Apache or PostgreSQL[1] poses tomas> some constraints: Guile won't be the only embedded language. Those tomas> applications bring along services for error handling, which you tomas> better use (e.g. aborting a transaction/erroring out in an HTTP tomas> request/response cycle), for consistency. So it might be most tomas> natural to catch errors at the C level. If that is not desirable tomas> from a Guile POV, then there should be at least a ``recommended tomas> canonical way'' (say: a C function calling a Guile wrapper tomas> calling...). And this might be provided as convenience library. tomas> But then, it could be provided in the first place :-) With ``recommended canonical way'' you've hit the nail on the head as far as I'm concerned. The main point of my whole argument is that there are currently no recommended ways of using Guile, and that makes it (i) jolly difficult to document - especially for more inexperienced developers (ii) difficult to clearly define the API and so manage API changes between releases. To consider your example ... Although it might be most immediately natural to catch and dispatch errors at the C level, I would recommend a ``canonical'' organization like this: (I'm assuming here that the basic operation of mod_guile is to translate a mod_guile HTML page into vanilla HTML) - Define primitives that wrap the applications' mechanisms for reporting errors. Now you can signal those errors from Scheme. - Define a Scheme procedure that does the whole translation operation: (translate-page INPUT) -> OUTPUT This procedure can signal application errors as/when it needs to. - From C, just call out to translate-page, and return its result to Apache. This may be a bit harder to begin with than writing everything in C. But once this structure is in place, your scope for rapidly adding further enhancements is much greater, because all the interesting code is in Scheme, not C. tomas> I'd even go a step further: for the embedded scripting language tomas> to play really nicely in those two cases, it'd be desirable to tomas> be able to adapt the garbage collector to the transaction-based tomas> memory model: much of the memory used just lives for a transaction, tomas> and that's why they allocate memory in `pools', which just disappear tomas> after the transaction is done. But this might be just wishful tomas> thinking... Sounds interesting, and maybe not too hard. Is the following possible? (let ((temp-heap (switch-to-new-heap))) ; This tell Guile's memory allocator to allocate a new heap ; and to make all memory allocations until further notice ; from this heap. (do-transaction-processing) ; During which all memory allocations come from the new heap. (gc-and-destroy-heap temp-heap) ; Perform a GC, assert that temp-heap now has nothing in use, ; destroy temp-heap and switch back to previous heap. ) Regards, Neil _______________________________________________ Guile-devel mailing list Guile-devel@gnu.org http://mail.gnu.org/mailman/listinfo/guile-devel