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