Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Added DESCRIPTION

  • Loading branch information...
commit 6b5b70f478ce03a8df6be8184f1d6cc9de03883a 1 parent 9c51bd0
@ayardley ayardley authored
Showing with 24 additions and 15 deletions.
  1. +24 −15 docs/pmc.pod
View
39 docs/pmc.pod
@@ -1,8 +1,16 @@
-=head1 Title
+# Copyright (C) 2001-2012, Parrot Foundation.
+
+=pod
+
+=head1 NAME
docs/pmc.pod - PMC (PMC Makers Compendium)
-=head1 PMC Structure Items Access
+=head1 DESCRIPTION
+
+This document covers some of the important internals of Parrot's PMCs.
+
+=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
@@ -16,7 +24,7 @@ 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
+=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
@@ -52,22 +60,23 @@ and it must be destroyed in the C<destroy()> VTABLE function, the PMC must
also 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.
+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
+=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
+=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.
+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
@@ -85,8 +94,8 @@ below.
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.
+VTABLE function must call B<Parrot_gc_mark_PObj_alive()> on all B<PObj>s which
+your PMC contains.
=item PObj_custom_destroy_FLAG
@@ -101,8 +110,8 @@ at the end of a block scope if the PMC isn't alive any more.
=back
-=head1 See also
+=head1 SEE ALSO
F<include/parrot/pobj.h>, F<src/gc/api.c>, F<docs/pdds/pdd02_vtables.pod>
-
+=cut
Please sign in to comment.
Something went wrong with that request. Please try again.