This is a little document to describe some of the details of the write
barrier for the gengc. 

The Mechanism:

Chances are, the write barrier will be implemented in guile itself,
rather than through the system's memory protection. The motivation for
this is:

1) More portable: it's a bit of a chore to get mem protection working
   on many platforms, and the quality of information supplied by a
   page fault is somewhat lacking. Additionally, page faults are
   generally not a highly optimized operation in many operating
   systems; the cost of each individual fault is often in the region
   of a few thousand instructions.

2) No real loss to efficiency. Any extra work done by the guile write
   barrier will likely be made up by the fact that we can keep very
   precise information about the roots for any particular generation,
   and we don't require a heap scan to find roots. Given that the
   write barrier is only invoked on writes to the heap, or on
   protected memory outside the heap, we shouldn't have a big problem.

Playing with the gc from c:

Basic scheme in c shouldn't see a great deal of difference. In places
where they might currently be fudging with low level memory (like the
actual c array of a scheme vector), they should be encouraged to use
an abstracted interface. The responsibility for the write barrier
falls completely on the system and extensions to the system
(i.e. smobs). This may require additions to the gh_ interface.

For some of the more low level features (like futzing with memory that
can contain scheme objects), we will provide a number of
scm_xxx_protected functions (malloc, realloc, free, memmove, memcopy,
etc...) that will let the write barrier know that pointers in those
places need to be calculated. Also, in smobs, when assigning to a
scheme pointer, it needs to let the gc know that it's being done. This
is probably the most easily accomplished by providing a function or
macro like scm_assign(location, value); this isn't required for
general code, or for assignments to stack values, but only in places
where a single value is assigned to an object in a protected area.

To allow us to figure out where we need to be looking, we will require
explicit registration of the cell of an smob with it's chunks of
memory. This is to let the gc know what generation to consider
pointers in that chunk of memory. This can easily be provided by
having an smob_create function, that returns the SCM value of the heap
cell, and calls a scm_gc_register_smob(type, cell) function.

The largest requirement this places on smob authors is abstraction of
the objects. Essentially, we want to be able to use smobs as we do
now, and not worry about the gc. This requires smobs to possibly
provide a more setter functions, rather than requiring modifications
on a low level to get things to work. This isn't a hard restriction to
meet: most smobs already provide these operations accessable from
scheme, so there's no reason we can't require that either these
operations be used from c, or that the programmer learns what they
have to do to make things work with the gc if they want to get down to
the metal.

Greg Harvey <Greg.Harvey@thezone.net>