Re: Doc organization (Re: Around again, and docs lead role)

[Neil Jerram]

>>>>> "tomas" == tomas  <address@hidden> 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