Dan Sugalski wrote: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 :)
Yes, I'm well aware of the undocumented nature of the initial API--I wrote the damn thing, and checked in some of the changes that badly mutated it. I do *not* want that to happen again. The design of the public API should come first, then the code to implement it.
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.
Swell, and hopefully we'll keep it that way. This *hasn't* been the pattern in the past for us in general. But the docs here aren't what I'm talking about. (explained down a bit)
2) I just can't document a not-yet existent API, when I don't know beforehand, how it should look like.
If you don't know what the public API should look like then you should sit down and think about it. The API design shouldn't come out of the code--the code should come out of the API design. Otherwise you end up with quirks of implementation welded into the API for no good reason.
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.
Yes, I'm aware of that. I want it documented first, though.
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.
Not even close. What you've got in there is details of the internal implementation. That's all fine and we definitely need that, but it's not what I'm talking about and it's not what needs to be done first.
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 :)
I know. What I expected is that you'd do the docs first, then write the code to the documented API. We apparently misunderstood each other.
So, being clear here (I hope, though recent history suggests otherwise) what I want is the API that the GC/DOD system presents to the rest of the engine. This includes the functions you call to trigger a DOD or GC sweep, any functions or macros that need to wrap pointer fetches or stores (if any), what stats are kept, the functions it exposes to the allocation system, or what parts of the allocation system it peeks at.
Basically, and simply, I want the docs for the API that you'd use if you were writing code to use the GC/DOD system, or were going to replace the GC/DOD system with an alternate.
--
Dan
--------------------------------------it's like this-------------------
Dan Sugalski even samurai
[EMAIL PROTECTED] have teddy bears and even
teddy bears get drunk
