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).

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

VERSION

0.1

2004.06.14 - Initial