Author: allison
Date: Mon May 21 19:22:33 2007
New Revision: 18616
Modified:
trunk/docs/pdds/draft/pdd17_pmc.pod
Log:
[pdd]: Adding comments to PMC PDD on subclassing low-level PMCs from high-level
classes.
Modified: trunk/docs/pdds/draft/pdd17_pmc.pod
==============================================================================
--- trunk/docs/pdds/draft/pdd17_pmc.pod (original)
+++ trunk/docs/pdds/draft/pdd17_pmc.pod Mon May 21 19:22:33 2007
@@ -83,14 +83,11 @@
struct PMC_EXT *pmc_ext;
};
-where C<obj> is a pointer to an C<pobj_t> structure:
+where C<obj> is a pointer to a C<pobj_t> structure:
typedef struct pobj_t {
UnionVal u;
Parrot_UInt flags;
- #if ! DISABLE_GC_DEBUG
- UINTVAL _pobj_version;
- #endif
} pobj_t;
and where:
@@ -109,8 +106,8 @@
struct parrot_string_t * _string_val;
} UnionVal;
-C<u> holds data associated with the PMC. This can be in the form of an integer
-value, a floating-point value, a string value, or a pointer to other data.
+C<u> holds data associated with the PMC. This can be in the form of an integer
+value, a floating-point value, a string value, or a pointer to other data.
C<u> may be empty, since the PMC structure also provides a more general data
pointer, but is useful for PMCs which hold only a single piece of data (e.g.
C<PerlInts>).
@@ -119,12 +116,9 @@
F<include/parrot/pobj.h>, and are generally only used within the Parrot
internals.
-C<_pobj_version> is only used for debugging Parrot's garbage collector. It is
-documented elsewhere (well, it will be once we get around to doing that...).
-
C<vtable> holds a pointer to the B<vtable> associated with the PMC. This points
to a set of functions, with interfaces described in
-F<docs/pdds/pdd02_vtables.pod> that implement the basic behaviour of the PMC
+L<Vtable Functions> that implement the basic behaviour of the PMC
(i.e. how it behaves under addition, subtraction, cloning etc.)
C<data> (if present) holds a pointer to any additional data associated with
@@ -136,8 +130,8 @@
#if PMC_DATA_IN_EXT
DPOINTER *data;
#endif
- PMC *_metadata;
- struct _Sync *_synchronize;
+ PMC *_metadata; # [Note: replaced by roles]
+ struct _Sync *_synchronize; # [Note: may be deprecated, see STM]
PMC *_next_for_GC;
};
@@ -1005,6 +999,10 @@
=item add_attribute
+=item get_attr
+
+=item set_attr
+
=item add_parent
=item add_role
@@ -1026,6 +1024,20 @@
{{ Address the problem of high-level objects inheriting from low-level PMCs,
and any structural changes to low-level PMCs that might require. }}
+If a low-level PMC expects to be overridden by high-level classes (which means
+all the core low-level PMC types), it must respect a standard interface. It
+must implement the C<get_attr> and C<set_attr> vtable entries for any core
+attributes it expects to be accessible to subclasses.
+
+Subclassing a low-level class from a high-level class makes an entry in the
+high-level class's list of parents. This entry is a proxy class object for the
+low-level PMC class that provides access to the low-level PMC's vtable
+(including the implementations of get_attr and set_attr), and defines the
+storage that the low-level object will need within the high-level object (this
+could be as simple as a single PMC attribute that is an instance of the
+low-level class).
+
+
=head2 Core PMCs
Parrot has a number of core PMC types that all programs can guarantee will be
