Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 118 lines (83 sloc) 4.807 kb
6b5b70f @ayardley Added DESCRIPTION
ayardley authored
1 # Copyright (C) 2001-2012, Parrot Foundation.
2
3 =pod
4
5 =head1 NAME
ef34ed9 add pmc.pod
Leopold Toetsch authored
6
7 docs/pmc.pod - PMC (PMC Makers Compendium)
8
6b5b70f @ayardley Added DESCRIPTION
ayardley authored
9 =head1 DESCRIPTION
10
11 This document covers some of the important internals of Parrot's PMCs.
12
13 =head1 PMC STRUCTURE ITEMS ACCESS
ef34ed9 add pmc.pod
Leopold Toetsch authored
14
353d0c6 @cotto [docs] rewrite pmc.pod now that the UnionVal is history
cotto authored
15 Ideally, there should be minimal direct access to a PMC's internals. In order
16 to enforce encapsulation, most interaction with a PMC should be performed
17 through VTABLE function calls, which allow code to remain robust as PMC
18 internals are changed.
19
20 When it is not possible or practical to use VTABLE functions (for instance when
21 implementing PMC internals), ATTRs should be used. ATTRs are declared after
22 the C<pmclass> line in a .pmc file. For a given pmc ("Foo"), an ATTR ("bar")
23 can be accessed either directly: C<< PARROT_FOO(pmc)->bar >> or via a
24 SETATTR/GETATTR accessor macro: C<GETATTR_Foo_bar(INTERP, x)>. Note that
25 inside a PMC's source file, these can be shortened to C<GET_ATTR_bar(INTERP, x)>.
ef34ed9 add pmc.pod
Leopold Toetsch authored
26
6b5b70f @ayardley Added DESCRIPTION
ayardley authored
27 =head1 PMC STORAGE
ef34ed9 add pmc.pod
Leopold Toetsch authored
28
353d0c6 @cotto [docs] rewrite pmc.pod now that the UnionVal is history
cotto authored
29 PMCs can store data in two places. 8 bits can be stored in the PMC's flags.
30 These are accessed via PObj_private0_FLAG, PObj_private1_FLAG, etc, although
31 these flags should be #define'd on a per-PMC basis to have more meaningful
32 names. If a PMC needs more than 8 bits of storage, it should declare ATTRs of
33 the appropriate type. Storage for ATTRs hangs off of C<PMC_data()>. See
34 src/pmc/exporter.pmc for example code that does this.
ef34ed9 add pmc.pod
Leopold Toetsch authored
35
353d0c6 @cotto [docs] rewrite pmc.pod now that the UnionVal is history
cotto authored
36 The PMC UnionVal is an obsolete storage area which was previously used to
37 provide a limited amount of storage. The use of this storage encouraged poor
38 encapsulation and hidden dependencies between PMCs. Any new code should not
39 use the UnionVal, which will eventually be removed from Parrot.
ef34ed9 add pmc.pod
Leopold Toetsch authored
40
353d0c6 @cotto [docs] rewrite pmc.pod now that the UnionVal is history
cotto authored
41 =head2 ATTRs and C<PMC_data()>
ef34ed9 add pmc.pod
Leopold Toetsch authored
42
353d0c6 @cotto [docs] rewrite pmc.pod now that the UnionVal is history
cotto authored
43 If your PMC needs to store more data than will fit into the 8 bits of the PMC
44 flags, it should declare ATTRs of the appropriate type. The pmc2c code will
45 generate a struct containing all ATTRs, including those inherited via
46 C<extends> declarations. This struct will be named in the form
47 C<Parrot_x_attributes>, where C<x> is the name of your PMC, e.g.
ce1dec8 @NotFound [doc] mention auto/manual_attrs in pmc.doc, by suggestion from cotto++
NotFound authored
48 C<Parrot_FixedIntegerArray_attributes>.
49
50 When creating a PMC that has one or more ATTRs, the C<Parrot_x_attributes>
51 struct must be allocated and assigned to C<PMC_data>, and freed on PMC
52 destruction. This can be done automatically by using the auto_attrs flag in
53 the PMC declaration, or manually by using the manual_attrs flag. You must set
54 one of those flags, a warning is emitted otherwise. In future releases
55 auto_attrs will be the default.
56
57 If manual_attrs is specified or assumed the struct must be manually allocated
58 in the PMC's C<init()> and C<init_pmc()> VTABLE functions (if used)
59 and it must be destroyed in the C<destroy()> VTABLE function, the PMC must
60 also indicate that they need active destruction by calling
4591dbb @chromatic [HLL] Fixed two compilation-breaking typos accidentally committed in r40...
chromatic authored
61 C<PObj_custom_destroy_SET()> or C<PObj_custom_mark_destroy_SETALL()>.
ef34ed9 add pmc.pod
Leopold Toetsch authored
62
6b5b70f @ayardley Added DESCRIPTION
ayardley authored
63 If your PMC only needs to store a single pointer, it can use C<PMC_data>
64 directly. Note that this may make maintaining your PMC difficult, should more
65 data ever need to be stored.
ef34ed9 add pmc.pod
Leopold Toetsch authored
66
6b5b70f @ayardley Added DESCRIPTION
ayardley authored
67 =head1 PMC FLAGS
ef34ed9 add pmc.pod
Leopold Toetsch authored
68
353d0c6 @cotto [docs] rewrite pmc.pod now that the UnionVal is history
cotto authored
69 Each PMC has 8 private flags named B<PObj_private0_FLAG> through
70 B<PObj_private7_FLAG>. These may be used for storing 8 bits of PMC-specific
71 information. See C<include/parrot/key.h> and C<src/pmc/key.pmc> for examples.
ef34ed9 add pmc.pod
Leopold Toetsch authored
72
6b5b70f @ayardley Added DESCRIPTION
ayardley authored
73 =head1 PMCs AND GC
ef34ed9 add pmc.pod
Leopold Toetsch authored
74
353d0c6 @cotto [docs] rewrite pmc.pod now that the UnionVal is history
cotto authored
75 The GC system doesn't make any assumptions about your PMC's layout. Whenever a
6b5b70f @ayardley Added DESCRIPTION
ayardley authored
76 PMC is found in the root set, B<Parrot_gc_mark_PObj_alive()> is called with
77 that PMC. The PMC is responsible to mark all contained or referenced active
78 Parrot objects (Buffers, STRINGs or other PMCs) when its C<mark()> VTABLE
79 function is called.
ef34ed9 add pmc.pod
Leopold Toetsch authored
80
353d0c6 @cotto [docs] rewrite pmc.pod now that the UnionVal is history
cotto authored
81 =head2 PMCs and System Resources
ef34ed9 add pmc.pod
Leopold Toetsch authored
82
353d0c6 @cotto [docs] rewrite pmc.pod now that the UnionVal is history
cotto authored
83 Whenever a PMC B<malloc()>s memory or opens a file or a database connection, it
84 has to take care of freeing or closing these resources. This is done by
85 implementing the appropriate VTABLE functions (C<mark()> and C<destroy()>) and
86 setting the appropriate PObj flags. The commonly used flags are described
87 below.
ef34ed9 add pmc.pod
Leopold Toetsch authored
88
353d0c6 @cotto [docs] rewrite pmc.pod now that the UnionVal is history
cotto authored
89 =head2 GC related flags
ef34ed9 add pmc.pod
Leopold Toetsch authored
90
91 =over 4
92
353d0c6 @cotto [docs] rewrite pmc.pod now that the UnionVal is history
cotto authored
93 =item PObj_custom_mark_FLAG
94
95 If your PMC contains any other B<PObj>s (STRINGs, PMCs, etc), your PMC must
96 implement the B<mark()> VTABLE function and set this flag. The B<mark()>
6b5b70f @ayardley Added DESCRIPTION
ayardley authored
97 VTABLE function must call B<Parrot_gc_mark_PObj_alive()> on all B<PObj>s which
98 your PMC contains.
353d0c6 @cotto [docs] rewrite pmc.pod now that the UnionVal is history
cotto authored
99
4591dbb @chromatic [HLL] Fixed two compilation-breaking typos accidentally committed in r40...
chromatic authored
100 =item PObj_custom_destroy_FLAG
ef34ed9 add pmc.pod
Leopold Toetsch authored
101
353d0c6 @cotto [docs] rewrite pmc.pod now that the UnionVal is history
cotto authored
102 If your PMC allocates any memory or opens any resources during its lifetime, it
4591dbb @chromatic [HLL] Fixed two compilation-breaking typos accidentally committed in r40...
chromatic authored
103 must set B<PObj_custom_destroy> and implement the B<destroy()> VTABLE function to
353d0c6 @cotto [docs] rewrite pmc.pod now that the UnionVal is history
cotto authored
104 free those resources.
ef34ed9 add pmc.pod
Leopold Toetsch authored
105
a52823f @cotto [gc] change all occurances of "early_DOD" to "early_gc"
cotto authored
106 =item PObj_needs_early_gc_FLAG
ef34ed9 add pmc.pod
Leopold Toetsch authored
107
353d0c6 @cotto [docs] rewrite pmc.pod now that the UnionVal is history
cotto authored
108 Set this flag if your PMC needs timely destruction, e.g. to close a file handle
109 at the end of a block scope if the PMC isn't alive any more.
ef34ed9 add pmc.pod
Leopold Toetsch authored
110
111 =back
112
6b5b70f @ayardley Added DESCRIPTION
ayardley authored
113 =head1 SEE ALSO
ef34ed9 add pmc.pod
Leopold Toetsch authored
114
bfb5829 @allisonrandal [pdd09gc] Merging the pdd09gc_part2 branch into trunk for r34686 to r353...
allisonrandal authored
115 F<include/parrot/pobj.h>, F<src/gc/api.c>, F<docs/pdds/pdd02_vtables.pod>
ef34ed9 add pmc.pod
Leopold Toetsch authored
116
6b5b70f @ayardley Added DESCRIPTION
ayardley authored
117 =cut
Something went wrong with that request. Please try again.