As part of the DOD/GC rework, we need to have a clean, well-documented API for the garbage collector. Things were clean, though not documented, for the original DOD and things have gotten significantly messier since.
First is of course one of the goals of these changes. Second "clean" but undocumented interfaces are useless :)
Part of the point of the GC/DOD rework is to allow alternate GC implementations (which is why things like write barrier macros are going in) but this can't be done without knowing what's going on, so...
1)
$ perldoc -F src/gc_ims.c | wc -l # [1] [2] 594
$ wc -l < src/gc_ims.c 882
Please dont't tell me something about "not knowing what's going on" - sorry.
2) I just can't document a not-yet existent API, when I don't know beforehand, how it should look like.
Did you know, that some of the {get,add}_free_object stuff spread in headers.c and smallobjctes.c is part of the garbage collector subsystem API? And of course more of that ... That *will* be documented RSN.
I think getting the API designed and documented *first* is in order,
Well, the API was undefined. Having now two garbage collectors for objects in place allows easily to define the minimal API for GC subsystems. Implementing it did clearly expose the shortcomes of the existing approach.
And: a lot of the API is in place in that file already. And it was there at the very beginning. Documented.
before any actual work's done on the engine. Otherwise we're going to end up with a mess, I'll end up reverting to prior CVS versions, and there'll be mass grumbling. And we just don't want that. :)
Dan, in private mail I said, that the API documentation will be the outcome of this implementation. Actually I've already started with writing the docs: by tossing unneeded (and misleading) implementation details from pdd09_gc :)
leo
[1] wc -l is line count for pure/poor Windows users ;) [2] omitting that wc stuff helps reading the docs - SCNR
