From: Mark-Jason Dominus Date: Sun, 25 Aug 2002 22:31:54 +0000 (-0400) Subject: Re: [perl #16677] B::SV::FLAGS dumps core X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=85cf7f2e6c0eee352cdc28bfa7e316574993c2ba;p=p5sagit%2Fp5-mst-13.2.git Re: [perl #16677] B::SV::FLAGS dumps core Message-ID: <20020826023154.22986.qmail@plover.com> p4raw-id: //depot/perl@17797 --- diff --git a/ext/B/B.pm b/ext/B/B.pm index feca2e5..ed7cf73 100644 --- a/ext/B/B.pm +++ b/ext/B/B.pm @@ -236,7 +236,7 @@ sub walksymtable { package B::Section; my $output_fh; my %sections; - + sub new { my ($class, $section, $symtable, $default) = @_; $output_fh ||= FileHandle->new_tmpfile; @@ -244,7 +244,7 @@ sub walksymtable { $sections{$section} = $obj; return $obj; } - + sub get { my ($class, $section) = @_; return $sections{$section}; @@ -272,12 +272,12 @@ sub walksymtable { my $section = shift; return $section->[2]; } - + sub default { my $section = shift; return $section->[3]; } - + sub output { my ($section, $fh, $format) = @_; my $name = $section->name; @@ -324,6 +324,186 @@ reader knows a fair amount about perl's internals including such things as SVs, OPs and the internal symbol table and syntax tree of a program. +=head1 OVERVIEW + +The C module contains a set of utility functions for querying the +current state of the Perl interpreter; typically these functions +return objects from the B::SV and B::OP classes, or their derived +classes. These classes in turn define methods for querying the +resulting objects about their own internal state. + +=head1 Utility Functions + +The C module exports a variety of functions: some are simple +utility functions, others provide a Perl program with a way to +get an initial "handle" on an internal object. + +=head2 Functions Returning C, C, C, and C objects + +For descriptions of the class hierachy of these objects and the +methods that can be called on them, see below, L<"OVERVIEW OF +CLASSES"> and L<"SV-RELATED CLASSES">. + +=over 4 + +=item sv_undef + +Returns the SV object corresponding to the C variable C. + +=item sv_yes + +Returns the SV object corresponding to the C variable C. + +=item sv_no + +Returns the SV object corresponding to the C variable C. + +=item svref_2object(SVREF) + +Takes a reference to any Perl value, and turns the referred-to value +into an object in the appropriate B::OP-derived or B::SV-derived +class. Apart from functions such as C, this is the primary +way to get an initial "handle" on an internal perl data structure +which can then be followed with the other access methods. + +=item amagic_generation + +Returns the SV object corresponding to the C variable C. + +=item C + +Returns the AV object (i.e. in class B::AV) representing INIT blocks. + +=item begin_av + +Returns the AV object (i.e. in class B::AV) representing BEGIN blocks. + +=item end_av + +Returns the AV object (i.e. in class B::AV) representing END blocks. + +=item comppadlist + +Returns the AV object (i.e. in class B::AV) of the global comppadlist. + +=item regex_padav + +Only when perl was compiled with ithreads. + +=item C + +Return the (faked) CV corresponding to the main part of the Perl +program. + +=back + +=head2 Functions for Examining the Symbol Table + +=over 4 + +=item walksymtable(SYMREF, METHOD, RECURSE, PREFIX) + +Walk the symbol table starting at SYMREF and call METHOD on each +symbol (a B::GV object) visited. When the walk reaches package +symbols (such as "Foo::") it invokes RECURSE, passing in the symbol +name, and only recurses into the package if that sub returns true. + +PREFIX is the name of the SYMREF you're walking. + +For example: + + # Walk CGI's symbol table calling print_subs on each symbol. + # Recurse only into CGI::Util:: + walksymtable(\%CGI::, 'print_subs', sub { $_[0] eq 'CGI::Util::' }, + 'CGI::'); + +print_subs() is a B::GV method you have declared. Also see L<"B::GV +Methods">, below. + +=back + +=head2 Functions Returning C objects or for walking op trees + +For descriptions of the class hierachy of these objects and the +methods that can be called on them, see below, L<"OVERVIEW OF +CLASSES"> and L<"OP-RELATED CLASSES">. + +=over 4 + +=item main_root + +Returns the root op (i.e. an object in the appropriate B::OP-derived +class) of the main part of the Perl program. + +=item main_start + +Returns the starting op of the main part of the Perl program. + +=item walkoptree(OP, METHOD) + +Does a tree-walk of the syntax tree based at OP and calls METHOD on +each op it visits. Each node is visited before its children. If +C (see below) has been called to turn debugging on then +the method C is called on each op before METHOD is +called. + +=item walkoptree_debug(DEBUG) + +Returns the current debugging flag for C. If the optional +DEBUG argument is non-zero, it sets the debugging flag to that. See +the description of C above for what the debugging flag +does. + +=back + +=head2 Miscellaneous Utility Functions + +=over 4 + +=item ppname(OPNUM) + +Return the PP function name (e.g. "pp_add") of op number OPNUM. + +=item hash(STR) + +Returns a string in the form "0x..." representing the value of the +internal hash function used by perl on string STR. + +=item cast_I32(I) + +Casts I to the internal I32 type used by that perl. + +=item minus_c + +Does the equivalent of the C<-c> command-line option. Obviously, this +is only useful in a BEGIN block or else the flag is set too late. + +=item cstring(STR) + +Returns a double-quote-surrounded escaped version of STR which can +be used as a string in C source code. + +=item perlstring(STR) + +Returns a double-quote-surrounded escaped version of STR which can +be used as a string in Perl source code. + +=item class(OBJ) + +Returns the class of an object without the part of the classname +preceding the first C<"::">. This is used to turn C<"B::UNOP"> into +C<"UNOP"> for example. + +=item threadsv_names + +In a perl compiled for threads, this returns a list of the special +per-thread threadsv variables. + +=back + + + + =head1 OVERVIEW OF CLASSES The C structures used by Perl's internals to hold SV and OP @@ -331,9 +511,12 @@ information (PVIV, AV, HV, ..., OP, SVOP, UNOP, ...) are modelled on a class hierarchy and the C module gives access to them via a true object hierarchy. Structure fields which point to other objects (whether types of SV or types of OP) are represented by the C -module as Perl objects of the appropriate class. The bulk of the C -module is the methods for accessing fields of these structures. Note -that all access is read-only: you cannot modify the internals by +module as Perl objects of the appropriate class. + +The bulk of the C module is the methods for accessing fields of +these structures. + +Note that all access is read-only. You cannot modify the internals by using this module. =head2 SV-RELATED CLASSES @@ -341,15 +524,40 @@ using this module. B::IV, B::NV, B::RV, B::PV, B::PVIV, B::PVNV, B::PVMG, B::BM, B::PVLV, B::AV, B::HV, B::CV, B::GV, B::FM, B::IO. These classes correspond in the obvious way to the underlying C structures of similar names. The -inheritance hierarchy mimics the underlying C "inheritance". Access -methods correspond to the underlying C macros for field access, +inheritance hierarchy mimics the underlying C "inheritance": + + B::SV + | + +--------------+----------------------+ + | | | + B::PV B::IV B::RV + | \ / \ + | \ / \ + | B::PVIV B::NV + \ / + \____ __/ + \ / + B::PVNV + | + | + B::PVMG + | + +------+-----+----+------+-----+-----+ + | | | | | | | + B::PVLV B::BM B::AV B::GV B::HV B::CV B::IO + | + | + B::FM + + +Access methods correspond to the underlying C macros for field access, usually with the leading "class indication" prefix removed (Sv, Av, Hv, ...). The leading prefix is only left in cases where its removal would cause a clash in method name. For example, C stays as-is since its abbreviation would clash with the "superclass" method C (corresponding to the C function C). -=head2 B::SV METHODS +=head2 B::SV Methods =over 4 @@ -359,7 +567,7 @@ C (corresponding to the C function C). =back -=head2 B::IV METHODS +=head2 B::IV Methods =over 4 @@ -387,7 +595,7 @@ unsigned. =back -=head2 B::NV METHODS +=head2 B::NV Methods =over 4 @@ -397,7 +605,7 @@ unsigned. =back -=head2 B::RV METHODS +=head2 B::RV Methods =over 4 @@ -405,7 +613,7 @@ unsigned. =back -=head2 B::PV METHODS +=head2 B::PV Methods =over 4 @@ -434,7 +642,7 @@ are always stored with a null terminator, and the length field =back -=head2 B::PVMG METHODS +=head2 B::PVMG Methods =over 4 @@ -444,7 +652,7 @@ are always stored with a null terminator, and the length field =back -=head2 B::MAGIC METHODS +=head2 B::MAGIC Methods =over 4 @@ -473,7 +681,7 @@ in the MAGIC. =back -=head2 B::PVLV METHODS +=head2 B::PVLV Methods =over 4 @@ -487,7 +695,7 @@ in the MAGIC. =back -=head2 B::BM METHODS +=head2 B::BM Methods =over 4 @@ -501,7 +709,7 @@ in the MAGIC. =back -=head2 B::GV METHODS +=head2 B::GV Methods =over 4 @@ -556,7 +764,7 @@ If you're working with globs at runtime, and need to disambiguate =back -=head2 B::IO METHODS +=head2 B::IO Methods =over 4 @@ -595,7 +803,7 @@ IoIFP($io) == PerlIO_stdin() ). =back -=head2 B::AV METHODS +=head2 B::AV Methods =over 4 @@ -611,7 +819,7 @@ IoIFP($io) == PerlIO_stdin() ). =back -=head2 B::CV METHODS +=head2 B::CV Methods =over 4 @@ -643,7 +851,7 @@ For constant subroutines, returns the constant SV returned by the subroutine. =back -=head2 B::HV METHODS +=head2 B::HV Methods =over 4 @@ -665,15 +873,32 @@ For constant subroutines, returns the constant SV returned by the subroutine. =head2 OP-RELATED CLASSES -B::OP, B::UNOP, B::BINOP, B::LOGOP, B::LISTOP, B::PMOP, -B::SVOP, B::PADOP, B::PVOP, B::CVOP, B::LOOP, B::COP. -These classes correspond in -the obvious way to the underlying C structures of similar names. The -inheritance hierarchy mimics the underlying C "inheritance". Access -methods correspond to the underlying C structre field names, with the -leading "class indication" prefix removed (op_). - -=head2 B::OP METHODS +C, C, C, C, C, C, +C, C, C, C, C, C. + +These classes correspond in the obvious way to the underlying C +structures of similar names. The inheritance hierarchy mimics the +underlying C "inheritance": + + B::OP + | + +---------------+--------+--------+------+ + | | | | | + B::UNOP B::SVOP B::PADOP B::CVOP B::COP + ,' `-. + / `--. + B::BINOP B::LOGOP + | + | + B::LISTOP + ,' `. + / \ + B::LOOP B::PMOP + +Access methods correspond to the underlying C structre field names, +with the leading "class indication" prefix (C<"op_">) removed. + +=head2 B::OP Methods =over 4 @@ -739,7 +964,7 @@ This returns the op description from the global C PL_op_desc array =back -=head2 B::PMOP METHODS +=head2 B::PMOP Methods =over 4 @@ -791,7 +1016,7 @@ Only when perl was compiled with ithreads. =back -=head2 B::LOOP METHODS +=head2 B::LOOP Methods =over 4 @@ -803,7 +1028,7 @@ Only when perl was compiled with ithreads. =back -=head2 B::COP METHODS +=head2 B::COP Methods =over 4 @@ -821,148 +1046,6 @@ Only when perl was compiled with ithreads. =back -=head1 FUNCTIONS EXPORTED BY C - -The C module exports a variety of functions: some are simple -utility functions, others provide a Perl program with a way to -get an initial "handle" on an internal object. - -=over 4 - -=item main_cv - -Return the (faked) CV corresponding to the main part of the Perl -program. - -=item init_av - -Returns the AV object (i.e. in class B::AV) representing INIT blocks. - -=item begin_av - -Returns the AV object (i.e. in class B::AV) representing BEGIN blocks. - -=item end_av - -Returns the AV object (i.e. in class B::AV) representing END blocks. - -=item main_root - -Returns the root op (i.e. an object in the appropriate B::OP-derived -class) of the main part of the Perl program. - -=item main_start - -Returns the starting op of the main part of the Perl program. - -=item comppadlist - -Returns the AV object (i.e. in class B::AV) of the global comppadlist. - -=item regex_padav - -Only when perl was compiled with ithreads. - -=item sv_undef - -Returns the SV object corresponding to the C variable C. - -=item sv_yes - -Returns the SV object corresponding to the C variable C. - -=item sv_no - -Returns the SV object corresponding to the C variable C. - -=item amagic_generation - -Returns the SV object corresponding to the C variable C. - -=item walkoptree(OP, METHOD) - -Does a tree-walk of the syntax tree based at OP and calls METHOD on -each op it visits. Each node is visited before its children. If -C (q.v.) has been called to turn debugging on then -the method C is called on each op before METHOD is -called. - -=item walkoptree_debug(DEBUG) - -Returns the current debugging flag for C. If the optional -DEBUG argument is non-zero, it sets the debugging flag to that. See -the description of C above for what the debugging flag -does. - -=item walksymtable(SYMREF, METHOD, RECURSE, PREFIX) - -Walk the symbol table starting at SYMREF and call METHOD on each -symbol (a B::GV object) visited. When the walk reaches package -symbols (such as "Foo::") it invokes RECURSE, passing in the symbol -name, and only recurses into the package if that sub returns true. - -PREFIX is the name of the SYMREF you're walking. - -For example... - - # Walk CGI's symbol table calling print_subs on each symbol. - # Only recurse into CGI::Util:: - walksymtable(\%CGI::, 'print_subs', sub { $_[0] eq 'CGI::Util::' }, - 'CGI::'); - -print_subs() is a B::GV method you have declared. - - -=item svref_2object(SV) - -Takes any Perl variable and turns it into an object in the -appropriate B::OP-derived or B::SV-derived class. Apart from functions -such as C, this is the primary way to get an initial -"handle" on an internal perl data structure which can then be followed -with the other access methods. - -=item ppname(OPNUM) - -Return the PP function name (e.g. "pp_add") of op number OPNUM. - -=item hash(STR) - -Returns a string in the form "0x..." representing the value of the -internal hash function used by perl on string STR. - -=item cast_I32(I) - -Casts I to the internal I32 type used by that perl. - - -=item minus_c - -Does the equivalent of the C<-c> command-line option. Obviously, this -is only useful in a BEGIN block or else the flag is set too late. - - -=item cstring(STR) - -Returns a double-quote-surrounded escaped version of STR which can -be used as a string in C source code. - -=item perlstring(STR) - -Returns a double-quote-surrounded escaped version of STR which can -be used as a string in Perl source code. - -=item class(OBJ) - -Returns the class of an object without the part of the classname -preceding the first "::". This is used to turn "B::UNOP" into -"UNOP" for example. - -=item threadsv_names - -In a perl compiled for threads, this returns a list of the special -per-thread threadsv variables. - -=back =head1 AUTHOR