writing PMCs (documentation)
Nicholas Clark
PMCs in the source tree, but I can't seem to find documentation on how to
go about writing them, or what the various fields and flags do.
For example, the string PMC_data occurs in many source files, but as far
as I can tell nowhere in any documentation files, and there aren't many
comments about it in include/parrot/pobj.h
I don't find any documentation saying "if you do this you'll need to do that
in a destructor else you'll leak".
Am I missing something obvious?
Nicholas Clark
Simon Glover
No. The closest we have to something like this is probably the stuff
written by Mike Scott for the Wiki:
http://www.vendian.org/parrot/wiki/bin/view.cgi/Main/ParrotDiagramsPMC
(Well, that plus the comments in pobj.h, which are somewhat opaque.)
If no-one else volunteers, I'll try to put together something like this,
as we do need it, but I'm unlikely to have sufficient tuits until the
end of May :-(
Simon
Simon Glover
Sorry to follow-up to myself, but I've thought of a few other things
that are probably worth loooking at. First, PDD04 (datatypes) has
some info on PMC internals, although this is incomplete, and possibly
out of date...
Second, when you come to implement the various vtable methods, you should
probably look at PDD02, which is the closest thing to a comprehensive
overview that we have, although I don't think it includes anything about
the recent MMD-related changes that Dan has announced.
Simon
Leopold Toetsch
> I'm trying to find documentation on how to write PMCs. I can find lots of
> PMCs in the source tree, but I can't seem to find documentation on how to
> go about writing them, or what the various fields and flags do.
Well, there isn't too much documentation around. The flags are
documented in pobj.h. Existing PMCs should give you some hints.
WRT the fields: there are 2 rules of thumb:
- if the data fit into the UnionVal put it there
(use appropriate members of the union)
else you need the PMC_data allocated anyway.
- but if a PMC may point to other PMCs so that possibly deeply nested
structures may result, it needs the C<pmc_ext> structure (denoted by
need_ext) in the pmc file.
> I don't find any documentation saying "if you do this you'll need to do that
> in a destructor else you'll leak".
If your PMCs contains other managed objects like Buffers or PMCs, you
have to make sure, that they get marked properly. If you
mem_sys_allocate something during object creation, you need to set the
active_destroy flag and fill the destroy vtable.
> Am I missing something obvious?
No, not AFAIK. I always start writing a new PMC by copying a similar
one.
> Nicholas Clark
leo
Michael Scott
had time recently for Parrot documentation. Indeed there is plenty to
be done. I should be back on the case in a week or two.
Mike