[Openmcl-devel] Interest in documentation reorganization?

[Alan Ruttenberg]

Another great source of documentation is the mailing list. If there is 
interest, I could go through the archives and pull together a selection 
of postings that have concentrated technical information (mostly 
written by Gary).

Not sure what the format would be, maybe a list of references from 
sections of the existing documentation to relevant postings.
As an example the most recent posting from Gary has useful information 
about the streams implementation. Here's one way we could edit it and 
package it up:

***

Keywords: Streams, Performance, Locks, Without-interrupts, 
Unwind-protect

Most writes to a file stream involve copying some bytes into a buffer
and adjusting some related pointers.  (A few such calls also involve
doing I/O to the file system)

In OpenMCL, all (well, most ...) streams are assumed to be globally
accessible, so all transactions on potentially shared streams involve
locking.  In cases where there's no contention involved (i.e., most or
all of the time), locking isn't incredibly expensive in and of itself,
but the locking/unlocking has to be UNWIND-PROTECTed, and
UNWIND-PROTECT's fairly expensive in OpenMCL (for threading-related
reasons.)  The actual "store some bytes in a buffer and adjust some
pointers" operation isn't reentrant, so it's also within a
WITHOUT-INTERRUPTS (which involves another UNWIND-PROTECT.)

It's generally the case that something like WRITE-STRING or
WRITE-SEQUENCE is likely to be faster than an equivalant sequence
of WRITE-CHARS; this is probably more pronounced in OpenMCL than
in other implementations because of this locking/WITHOUT-INTERRUPTS/
UNWIND-PROTECT overhead.

I would guess that most streams are thread-private and the reentrancy 
issue's a lot
more pronounced for things like *TERMINAL-IO* than for things created 
with WITH-OPEN-FILE

[Extracted from "Faster Formatting for fun (the OpenMCL version)" <link 
to thread view>]

***

Then include a link to this in FAQ, Doc on streams, performance, 
Sempahores etc.

-Alan