GC Hooks and a proposal (WAS Re: Marking smobs for GC)

[Greg Harvey <Greg.Harvey@thezone.net>]

Mikael Djurfeldt <mdj@nada.kth.se> writes:

> Greg Harvey <Greg.Harvey@thezone.net> writes:
> 
> > I've been meaning to add a before & after-gc-hook to the gc, though
> > (should only take a few minutes).
> 
> Good idea.
> 
> (I hope you will make these real hooks rather than a thunk to call.)
> 
> I think we should keep %gc-thunk in 1.4 but warn that we'll remove it
> in 1.5.

They will be real hooks, or a hook, rather; a before gc hook will take
a lot more fudging about (since there's no memory left to cons, things
would get a bit hairy... a fairly simple way to do it would be to add
a gc-cons that just allocates from a temporary heap, and chucks it
once we get into the gc proper, but that means you can't really
execute arbitrary code there (though I suppose you could some really
funky redefinitions of cons, it would still break c code, since we
can't go through it and redefine SCM_NEWCELL to something that will
get a new 'in gc' cell). 

The after-gc-hooks are easy, though I'm not sure if they should be run
asynchronously like the current gc-thunk; if you have a lot of hooks,
I'm guessing you could end up in another gc while running them, which
likely wouldn't be a good thing. I still need to wrap my mind around
asych, though, so I might be worried about nothing.

(define rant (
On another note, I propose that we add a doc/interm subdirectory to
the guile tree, and add temporary documentation of new features (and
old features, for anyone who's up to it) there. Often this goes into
news, but I don't think that that's the best place to put them (since
few people want to grovel through news to find out what something
does... in any case, that's not where you expect to find it). Also,
that we require the addition of any new features to be
documented this way. There are few reasons for this:

1) It's currently a real pain in the ass to find out anything without
   resorting to the sources... at 3 in the morning, when you're trying
   to get those stupid text buffers to work from scheme, damnit!, the
   lack of documentation puts you in a sort of homicidal mood (ok,
   that could just be me ;).

2) New features are useless if you don't know how to use them

3) No one really wants to write documentation, and won't if you don't
   force them to >;)

4) As it currently stands, the task of documenting guile requires
   first groveling over every source file (that's 106 c source files
   in the libguile directory alone... then you have boot-9, which is
   about the equivalent of 106 files). That in itself would take one
   person quite a while to do; when you add on the amount of time it
   takes to come up with examples of these things in action (that
   actually work), and a description of the concepts involved, you're
   talking about a long time before we have a manual in a useful
   state. Adding the interm documentation will make guile more
   accessable now, and make the job of doing complete documentation a
   great deal easier.

This doesn't have to be a big job for one individual (and should be
particularly easy for whoever wrote the code); basically, just a short
text file that gives a little description of what goes on, and a short
description of each of the features of the code (kind of like the
qdocs that I've started putting up on my website... however, this is a
good example of how much work it takes for one person to write the
documentation for the whole thing... if I'd been able to keep up my
original pace of 2 source files per day, you'd still be talking about
a few months to do libguile... and 2 docs a day is quite a generous
estimate when you have other things that you want or have to do).

The current state (little documentation, and that scattered all over
the place) is terrible; to think about it in more real terms, if you
wanted to add an extension language to your program, and had the
choice between elk (rigorously documented), python (ditto), or guile
(ack!), which would you choose?  The main thing that guile currently
has going for it is that it's an official GNU project, and that there
are a lot of exciting directions that are planned; but the excitement
of the potential is decidedly marked by the frustration of reality.

))

-- 
Greg