=head1 Title docs/pmc.pod - PMC (PMC Makers Compendium) =head1 PMC Structure Items Access Ideally, there should be minimal direct access to a PMC's internals. In order to enforce encapsulation, most interaction with a PMC should be performed through VTABLE function calls, which allow code to remain robust as PMC internals are changed. When it is not possible or practical to use VTABLE functions (for instance when implementing PMC internals), ATTRs should be used. ATTRs are declared after the C<pmclass> line in a .pmc file. For a given pmc ("Foo"), an ATTR ("bar") can be accessed either directly: C<< PARROT_FOO(pmc)->bar >> or via a SETATTR/GETATTR accessor macro: C<GETATTR_Foo_bar(INTERP, x)>. Note that inside a PMC's source file, these can be shortened to C<GET_ATTR_bar(INTERP, x)>. =head1 PMC Storage PMCs can store data in two places. 8 bits can be stored in the PMC's flags. These are accessed via PObj_private0_FLAG, PObj_private1_FLAG, etc, although these flags should be #define'd on a per-PMC basis to have more meaningful names. If a PMC needs more than 8 bits of storage, it should declare ATTRs of the appropriate type. Storage for ATTRs hangs off of C<PMC_data()>. See src/pmc/exporter.pmc for example code that does this. The PMC UnionVal is an obsolete storage area which was previously used to provide a limited amount of storage. The use of this storage encouraged poor encapsulation and hidden dependencies between PMCs. Any new code should not use the UnionVal, which will eventually be removed from Parrot. =head2 ATTRs and C<PMC_data()> If your PMC needs to store more data than will fit into the 8 bits of the PMC flags, it should declare ATTRs of the appropriate type. The pmc2c code will generate a struct containing all ATTRs, including those inherited via C<extends> declarations. This struct will be named in the form C<Parrot_x_attributes>, where C<x> is the name of your PMC, e.g. C<Parrot_FixedIntegerArray_attributes>. When creating a PMC that has one or more ATTRs, the C<Parrot_x_attributes> struct must be allocated and assigned to C<PMC_data> in the PMC's C<init()> and C<init_pmc()> VTABLE functions (if used) and it must be destroyed in the C<destroy()> VTABLE function. PMCs with ATTRs also need to indicate that they need active destruction by calling C<PObj_custom_destroy_SET()> or C<PObj_custom_mark_destroy_SETALL()>. If your PMC only needs to store a single pointer, it can use C<PMC_data> directly. Note that this may make maintaining your PMC difficult, should more data ever need to be stored. =head1 PMC flags Each PMC has 8 private flags named B<PObj_private0_FLAG> through B<PObj_private7_FLAG>. These may be used for storing 8 bits of PMC-specific information. See C<include/parrot/key.h> and C<src/pmc/key.pmc> for examples. =head1 PMCs and GC The GC system doesn't make any assumptions about your PMC's layout. Whenever a PMC is found in the root set, B<Parrot_gc_mark_PObj_alive()> is called with that PMC. The PMC is responsible to mark all contained or referenced active Parrot objects (Buffers, STRINGs or other PMCs) when its C<mark()> VTABLE function is called. =head2 PMCs and System Resources Whenever a PMC B<malloc()>s memory or opens a file or a database connection, it has to take care of freeing or closing these resources. This is done by implementing the appropriate VTABLE functions (C<mark()> and C<destroy()>) and setting the appropriate PObj flags. The commonly used flags are described below. =head2 GC related flags =over 4 =item PObj_custom_mark_FLAG If your PMC contains any other B<PObj>s (STRINGs, PMCs, etc), your PMC must implement the B<mark()> VTABLE function and set this flag. The B<mark()> VTABLE function must call B<Parrot_gc_mark_PObj_alive()> on all B<PObj>s which your PMC contains. =item PObj_custom_destroy_FLAG If your PMC allocates any memory or opens any resources during its lifetime, it must set B<PObj_custom_destroy> and implement the B<destroy()> VTABLE function to free those resources. =item PObj_needs_early_gc_FLAG Set this flag if your 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. =back =head1 See also F<include/parrot/pobj.h>, F<src/gc/api.c>, F<docs/pdds/pdd02_vtables.pod>