>> These PMCs are expected to provide a certain vtable-based API (I >> should document that somewhere) > > Yes, please write up briefly for PDD 17, and pass the patch around the list > for review.
Please find attached a proposed patch for PDD 17.
Index: docs/pdds/pdd17_pmc.pod =================================================================== --- docs/pdds/pdd17_pmc.pod (revision 44885) +++ docs/pdds/pdd17_pmc.pod (working copy) @@ -160,6 +160,8 @@ =item * C<event> can be used with event queue +=item * C<visit> can be used to traverse a datastructure + =back =item hll @@ -510,7 +512,7 @@ PMC* clone(INTERP, PMC *self) -Return a clone of a PMC. +Return a shallow clone of a PMC. =item defined @@ -536,15 +538,15 @@ void freeze(INTERP, PMC *self, visit_info* info) -Freeze the PMC to an archived string format (a bytecode string constant -that can be saved in a packfile). +Push the attributes of a PMC that are guaranteed to be non-cyclic (usually +C<INTVAL>s, C<FLOATVAL>s, and C<STRING>s) onto a visitor. Used to store the PMC +in bytecode. =item thaw void thaw (INTERP, PMC *self, visit_info* info) -Thaw a PMC from an archived string format (a bytecode string constant -that can be saved in a packfile). +Shift the attributes stored by freeze off of a visitor and into this PMC. =item thawfinish @@ -556,7 +558,9 @@ void visit (INTERP, PMC *self, visit_info* info) -Used by C<freeze> and C<thaw> to visit the contents of the PMC. +Push onto or shift off of a visitor attribute values that can be cyclic. +Compliments C<freeze>, C<thaw>, and C<clone> to provide deep-traversing versions +of these. =item share @@ -1809,6 +1813,54 @@ =back +=head4 Visitor Types + +Visitor types are types suitable to passing to C<visit>, C<freeze>, C<thaw>, +and C<thawfinish>. The satisfy the following interface: + +=over 4 + +=item C<get_integer> + +Returns a set of flags describing the visit action to be taken. This includes +an action from C<visit_how_enum_t> and types from C<visit_what_enum_t>. + +=item C<push_integer>, C<push_float>, C<push_string>, C<push_pmc> + +If the visitor is consuming a PMC, the PMC is expected to use these vtables to +serialize itself to the visitor. It is the visitors responsibility to ensure +that PMCs are visited the appropriate number of times and to prevent infinite +recursion on cyclic datastructures. + +=item C<shift_integer>, C<shift_float>, C<shift_string>, C<shift_pmc> + +If the PMC is consuming the visitor, the PMC is expected to use these vtables +to obtain its new attribute values. + +=item C<get_iter> + +This is called from C<Parrot_visit_loop_visit> to obtain an iterator from which +the next PMCs to visit will be obtained. + +=back + +=over 4 + +=item ImageIO + +Used to serialize and deserialize objects to/from bytecode. + +=item ImageIOSize + +Used to find the size in a bytecode image a PMC would consume without +allocating a large buffer and actually serializing it. + +=item DeepClone + +Used to deeply clone a PMC. + +=back + =head2 Attachments None.
_______________________________________________ http://lists.parrot.org/mailman/listinfo/parrot-dev
