docs/pmc.pod - PMC (PMC Makers Compendium)
Don't use PMC structure items directly, always use the macros, which are defined in include/parrot/pobj.h.
The PMC structure contains two places of data storage: the union UnionVal and the PMC_data pointer.
During PMC recycling the UnionVal data members are not cleared. PMC_data or pmc_ext is set to NULL. The flags are set to their default value, especially the private flags are 0.
There are no special rules, where to store what: use whatever fits best. If your PMC points to a STRING *, hang it off the PMC_str_val(), if it's an INTVAL, place it in PMC_int_val(). If you need to store two items, try to use union members that have distinct storage like PObj_bustart() / PObj_buf_len() or PMC_struct_val() / PMC_pmc_val() in parallel with PMC_num_val().
If your PMC contains other PMCs that possibly would allow the creation of self-referential or arbitrary deeply nested containers, you have to allocate the PMC_EXT structure by specifying the need_ext flag on the pmclass definition line. The PMC_data() pointer is currently located in the PMC_EXT structure too. Using PMC_data() therefore adds one more indirection to access these data.
Each PMC has 8 private flags PObj_private0_FLAG - PObj_private7_FLAG, which can be used for storing 8 bits.
The GC system doesn't make any assumptions about your PMC's layout. Whenever a PMC is found in the root set, pobject_lives() is called with that PMC. The PMC is responsible to mark all contained or referenced active Parrot objects (Buffers or other PMCs).
PMC_data points to a PObj object. This PMC gets marked automatically.
PMC_data points to a buffer holding an array of PObj*s.
If your PMC refers to any Parrot objects and above standard flags don't cover this usage, a custom mark vtable has to be implemented, which has to call pobject_lives() for all contained PObjs.
Whenever a PMC malloc()s system memory or opens a file or a database connection, it has to take care of freeing or closing these system resources.
The PMC's destroy vtable is called, when this PMC is found to be dead during GC.
Set this flag too, if the PMC needs timely destruction, e.g. to close a file handle at the end of a block scope, if the PMC isn't alive any more.
include/parrot/pobj.h, src/gc/api.c, docs/pdds/pdd02_vtables.pod
Leopold Toetsch lt@toetsch.at
lt@toetsch.at
2004.06.14 - Initial
To install Parrot::PMC, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Parrot::PMC
CPAN shell
perl -MCPAN -e shell install Parrot::PMC
For more information on module installation, please visit the detailed CPAN module installation guide.