Author: ambs Date: Tue Aug 22 10:14:31 2006 New Revision: 14308 Modified: trunk/docs/pdds/clip/pdd06_pasm.pod trunk/docs/pdds/clip/pdd09_gc.pod trunk/docs/pdds/clip/pdd10_embedding.pod trunk/docs/pdds/clip/pdd11_extending.pod trunk/docs/pdds/pdd21_namespaces.pod
Changes in other areas also in this revision: Modified: trunk/README.win32.pod trunk/cage/todo.pod trunk/docs/BROKEN.pod trunk/docs/art/pp002-pmc.pod trunk/docs/compiler_faq.pod trunk/docs/configuration.pod trunk/docs/debug.pod trunk/docs/dev/optimizer.pod trunk/docs/embed.pod trunk/docs/faq.pod trunk/docs/imcc/syntax.pod trunk/docs/intro.pod trunk/docs/optable.pod trunk/docs/stm/atomic.pod trunk/docs/stm/stm_frontend.pod trunk/docs/stm/thread-issues.pod trunk/docs/strings.pod trunk/docs/tests.pod trunk/docs/vtables.pod trunk/languages/LANGUAGES.STATUS.pod trunk/languages/tcl/docs/howto.pod trunk/lib/Pod/Simple/Subclassing.pod trunk/t/distro/linelength.t Log: While discussion continues on p2, pod files should be at most 80 columns, special on verbatim sections, so we the man formatter show it properly. Modified: trunk/docs/pdds/clip/pdd06_pasm.pod ============================================================================== --- trunk/docs/pdds/clip/pdd06_pasm.pod (original) +++ trunk/docs/pdds/clip/pdd06_pasm.pod Tue Aug 22 10:14:31 2006 @@ -58,12 +58,14 @@ in a label a dollar sign can appear) are private to the subroutine they appear in. -Namespaces are noted with the C<.namespace> directive. It takes a single parameter, -the name of the namespace, in the form of a multi-dimensional key. - -Subroutine names are noted with the C<.sub> directive. It takes a single parameter, -the name of the subroutine, which is added to the namespace's symbol table. Sub -names may be any valid Unicode alphanumeric character and the underscore. +Namespaces are noted with the C<.namespace> directive. It takes a +single parameter, the name of the namespace, in the form of a +multi-dimensional key. + +Subroutine names are noted with the C<.sub> directive. It takes a +single parameter, the name of the subroutine, which is added to the +namespace's symbol table. Sub names may be any valid Unicode +alphanumeric character and the underscore. Constants don't need to be named and put in a separate section of the assembly source. The assembler will take care of putting them in the appropriate part of @@ -1010,7 +1012,10 @@ So the signature for, for example, this SDL routine: - int SDL_BlitSurface(SDL_Surface *src, SDL_Rect *srcrect, SDL_Surface *dst, SDL_Rect *dstrect); + int SDL_BlitSurface(SDL_Surface *src, + SDL_Rect *srcrect, + SDL_Surface *dst, + SDL_Rect *dstrect); would be C<ipppp>, since it returns an integer and takes four pointers. Presumably previous calls would have set those pointers up properly. Modified: trunk/docs/pdds/clip/pdd09_gc.pod ============================================================================== --- trunk/docs/pdds/clip/pdd09_gc.pod (original) +++ trunk/docs/pdds/clip/pdd09_gc.pod Tue Aug 22 10:14:31 2006 @@ -227,7 +227,8 @@ This macro is invoked when in aggregate C<agg> the element C<old> is getting overritten by C<new>. Both C<old> and C<new> may be NULL. -=item C<DOD_WRITE_BARRIER_KEY(Interp*, PMC *agg, PMC *old, PObj *old_key, PMC *new, PObj *new_key)> +=item C<DOD_WRITE_BARRIER_KEY(Interp*, PMC *agg, PMC *old, PObj +*old_key, PMC *new, PObj *new_key)> Like above. Invoked when a hash key is inserted, possibly replacing an old key. Modified: trunk/docs/pdds/clip/pdd10_embedding.pod ============================================================================== --- trunk/docs/pdds/clip/pdd10_embedding.pod (original) +++ trunk/docs/pdds/clip/pdd10_embedding.pod Tue Aug 22 10:14:31 2006 @@ -7,7 +7,8 @@ =head1 ABSTRACT -What we believe people will do when embedding and extending Parrot, why they do it, and how. +What we believe people will do when embedding and extending Parrot, why they +do it, and how. {{ NOTE: some of this will later move into pdds 11 & 12, but for now just want to get the stub checked in. }} @@ -19,45 +20,103 @@ =head1 DESCRIPTION Why embed: - - access to special features/libraries/languages Parrot provides - - need an interpreter for a DSL or existing language - - want to run Parrot on another platform or environment (dedicated - hardware, in a web server, et cetera) + +=over 4 + +=item - access to special features/libraries/languages Parrot provides + +=item - need an interpreter for a DSL or existing language + +=item - want to run Parrot on another platform or environment (dedicated +hardware, in a web server, et cetera) + +=back Why extend: - - need something NCI doesn't provide - - writing a custom PMC + +=over 4 + +=item - need something NCI doesn't provide + +=item - writing a custom PMC + +=back Philosophical rules: - - only ever use opaque pointers - - should be able to communicate through PMCs - - minimize conversions to and from C data - - perhaps macros; Ruby does this fairly well and Perl 5 does this - poorly - - minimize the number of necessary functions - - probably can follow core Parrot code to some extent, but beware the - Perl 5 problem - - do not expose Parrot internals that may change - - probably includes vtable methods on PMCs + +=over 4 + +=item - only ever use opaque pointers + +=item - should be able to communicate through PMCs + +=item - minimize conversions to and from C data + +=over 4 + +=item - perhaps macros; Ruby does this fairly well and Perl 5 does this +poorly + +=item - minimize the number of necessary functions + +=item - probably can follow core Parrot code to some extent, but beware the +Perl 5 problem + +=over 4 + +=item - do not expose Parrot internals that may change + +=item - probably includes vtable methods on PMCs + +=back + +=back + +=back Gotchas: - - who handles signals? - - who owns file descriptors and other Unix resources? - - is there an exception boundary? - - namespace issues -- especially key related - - probably a continuation/control flow boundary - - packfiles and compilation units probably too much information for either - - do not let MMD and other implementation details escape - - okay to require some PBC/PIR/PASM for handling round-trip data - - Parrot should not spew errors to STDERR when embedded - - const_string() is a real pain, especially with necessary deallocation - - should be access to Parrot's event loop when embedded - - passing var args to Parrot subs likely painful - - perhaps macros/functions to add parameters to call - - build up a call signature somehow? - - some abstraction for a call frame? - - compiling code from a string should return the PMC Sub entry point (:main) +=over 4 + +=item - who handles signals? + +=item - who owns file descriptors and other Unix resources? + +=item - is there an exception boundary? + +=item - namespace issues -- especially key related + +=item - probably a continuation/control flow boundary + +=item - packfiles and compilation units probably too much information for +either + +=item - do not let MMD and other implementation details escape + +=item - okay to require some PBC/PIR/PASM for handling round-trip data + +=item - Parrot should not spew errors to STDERR when embedded + +=item - const_string() is a real pain, especially with necessary deallocation + +=item - should be access to Parrot's event loop when embedded + +=item - passing var args to Parrot subs likely painful + +=over 4 + +=item - perhaps macros/functions to add parameters to call + +=item - build up a call signature somehow? + +=item - some abstraction for a call frame? + +=back + +=item - compiling code from a string should return the PMC Sub entry point +(:main) + +=back =head1 DEFINITIONS Modified: trunk/docs/pdds/clip/pdd11_extending.pod ============================================================================== --- trunk/docs/pdds/clip/pdd11_extending.pod (original) +++ trunk/docs/pdds/clip/pdd11_extending.pod Tue Aug 22 10:14:31 2006 @@ -144,7 +144,8 @@ Keyed version of C<Parrot_PMC_set_pointer>. Assigns C<value> to the PMC stored at element <key> of the passed-in PMC. -=item C<Parrot_PMC_set_pmc_intkey(interp, pmc, Parrot_PMC value, Parrot_Int key)> +=item C<Parrot_PMC_set_pmc_intkey(interp, pmc, Parrot_PMC value, +Parrot_Int key)> Assigns C<value> to the PMC stored at element <key> of the passed-in PMC. Modified: trunk/docs/pdds/pdd21_namespaces.pod ============================================================================== --- trunk/docs/pdds/pdd21_namespaces.pod (original) +++ trunk/docs/pdds/pdd21_namespaces.pod Tue Aug 22 10:14:31 2006 @@ -275,8 +275,8 @@ This method allows other HLLs to know one name (the HLL) and then work with that HLL's modules without having to know the name it chose for its namespace -tree. (If you really want to know the name, the get_name() method should work on -the returned namespace PMC.) +tree. (If you really want to know the name, the get_name() method should work +on the returned namespace PMC.) Note that this method is basically a convenience and/or performance hack, as it does the equivalent of C<get_root_namespace> followed by