TITLE
docs/pmc.pod - PMC (PMC Makers Compendium)
PMC Structure Items Access
Don't use PMC structure items directly, always use the macros, which are defined in include/parrot/pobj.h.
PMC Storage
The PMC structure contains two places of data storage: the union UnionVal and the PMC_data pointer.
Storage memory washing
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.
UnionVal usage
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().
PMC_data()
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.
PMC flags
Each PMC has 8 private flags PObj_private0_FLAG - PObj_private7_FLAG, which can be used for storing 8 bits.
PMCs and DOD
Overview
The DOD 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).
DOD related flags
- PObj_is_buffer_ptr_FLAG
-
PMC_data points to a PObj object. This PMC gets marked automatically.
- PObj_is_buffer_of_PMCs_ptr_FLAG
-
PMC_data points to a buffer holding an array of PObj*s.
- PObj_custom_mark_FLAG
-
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.
PMCs and System Resources
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.
Flags for PMC destruction
- PObj_active_destroy_FLAG
-
The PMC's destroy vtable is called, when this PMC is found to be dead during DOD.
- PObj_needs_early_DOD_FLAG
-
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.
SEE ALSO
include/parrot/pobj.h, src/dod.c, docs/pdds/pdd02_vtables.pod
AUTHOR
Leopold Toetsch lt@toetsch.at