On Jun 25, 2013, at 06:50 , Marvin Humphrey <[email protected]> wrote:
> On Sat, Jun 22, 2013 at 6:57 AM, <[email protected]> wrote: >> +=head1 NAME >> + >> +Clownfish - Short description. >> + > > I suggest... > > Clownfish - Symbiotic object system. +1 >> +Clownfish is an object system for C designed to easily create bindings for >> +dynamic languages, so-called host languages. Classes are declared in >> Clownfish >> +header files with a C<.cfh> extension. The Clownfish headers are used by the >> +Clownfish compiler to generate C header files and host language bindings. >> +Class methods, functions and variables are defined in normal C source files. > > Nit: "Class methods" should probably be either "Instance methods", "Object > methods" or "Dynamic methods". Yes, I really wanted to say "A class's methods, functions…" > I suggest a change in the first sentence, as well: > > Clownfish is a "symbiotic" object system for C which is designed to pair > with a "host" dynamic language environment, facilitating the development > of high performance host language extensions. Clownfish classes are > declared in header files with a C<.cfh> extension. The Clownfish headers > are used by the Clownfish compiler to generate C header files and host > language bindings. Instance methods, functions and variables are defined > in normal C source files. +1 >> +=item * >> + >> +Guaranteed ABI stability when adding or reordering methods or instance >> +variables. > > Interesting wording. I agree that it probably isn't worthwhile to distinguish > between methods and instance variables, even though we only continue to have > fragile ABI problems with instance variables. But hopefully this will change > soon anyway. Actually, I didn't finish the ABI stability changes for methods yet. But the infrastructure is all there. All that's missing is initializing the methods offsets during VTable bootstrap. >> +=head1 USING CLOWNFISH CLASSES >> + >> +TODO: Simple introduction > > This is using them from Perl? No, I want to put an intro there on how to use Clownfish from C. It's the thing that I had planned for users of the C library. Since we don't have a language-independent documentation format yet, I would simply put it in the POD and refer C users there. >> +=head3 Abstract classes >> + >> +Only abstract classes may contain abstract methods. They must not be >> +instantiated directly. > > Haha, is that true? That limitation never occurred to me before, so if I > programmed it into CFC, it was by accident. I didn't check if that matches current CFC behaviour. That's one of the places where I documented what I think CFC should do without looking at the source. > I suppose that such a restriction allows us to error out at compile-time > rather than runtime when some method is not implemented in a compiled > extension. Fine, that works. Better to be more strict now because we'll have > the option of relaxing the rule later. Now that I had a look at the code, I realize that CFC simply ignores the abstract modifier on classes. That makes sense and we should remove that section. But CFC should throw an error when it encounters an invalid modifier. Currently, those are silently ignored in many cases. For example, we also allow "final inert", "abstract inert", and "inline" non-inert functions which should all be errors. I'm trying to make the documentation as strict as possible. Then we can make sure that CFC really checks all those "musts" and "must-nots". Unfortunately, we still can't test CFC exceptions from C, only from Perl. >> +This will generate: >> + >> + /* Wrapper for dynamic dispatch */ >> + void >> + Pfind_VisGraph_Add_Node(pfind_VisibilityGraph *self, pfind_Node *node); > > Technically this will be a static inline function. Eventually somebody might > get confused by this when they can't find the symbol. Yes, it's probably better to document exactly what is generated. > Before we refer to this product with the "Apache" prefix, i.e. as "Apache > Clownfish", I think we should check in with VP Brand Management. > > There are two possible tracks for Clownfish. If people end up using it to > build non-Lucy-related products, it will almost certainly split off from Lucy > and enter the Incubator on a path to becoming an independent top-level Apache > project. The other possibility is that Clownfish will remain a utility for > creating compiled Lucy extensions for the indefinite future. > > We are completely justified releasing Clownfish as a public API based on what > it offers to Lucy users -- and because of that, we don't have to go through > the Incubator yet. I'm just not clear on what the deal is with regards to a > TLP launching a secondary product. I can see arguments for "Apache > Clownfish", "Apache Lucy Clownfish" (blech), and just "Clownfish". Let's ask. +1 Nick
