Provided by: libdevel-mat-perl_0.52-1build2_amd64 
NAME
"Devel::MAT::SV" - represent a single SV from a heap dump
DESCRIPTION
Objects in this class represent individual SV variables found in the arena during a heap
dump. Actual types of SV are represented by subclasses, which are documented below.
COMMON METHODS
type
$type = $sv->type
Returns the major type of the SV. This is the class name minus the "Devel::MAT::SV::"
prefix.
basetype
$type = $sv->basetype
Returns the inner perl API type of the SV. This is one of
SV AV HV CV GV LV PVIO PVFM REGEXP INVLIST OBJ
desc
$desc = $sv->desc
Returns a string describing the type of the SV and giving a short detail of its contents.
The exact details depends on the SV type.
desc_addr
$desc = $sv->desc_addr
Returns a string describing the SV as with "desc" and giving its address in hex. A useful
way to uniquely identify the SV when printing.
addr
$addr = $sv->addr
Returns the address of the SV
refcnt
$count = $sv->refcnt
Returns the "SvREFCNT" reference count of the SV
refcount_adjusted
$count = $sv->refcount_adjusted
Returns the reference count of the SV, adjusted to take account of the fact that the
"SvREFCNT" value of the backrefs list of a hash or weakly-referenced object is
artificially high.
blessed
$stash = $sv->blessed
If the SV represents a blessed object, returns the stash SV. Otherwise returns "undef".
symname
$name = $sv->symname
Called on an SV which is a member of the symbol table, this method returns the perl
representation of the full symbol name, including sigil. Otherwise, returns "undef".
A leading "main::" prefix is removed for symbols in packages other than "main".
size
$size = $sv->size
Returns the (approximate) size in bytes of the SV
magic
@magics = $sv->magic
Returns a list of magic applied to the SV; each giving the type and target SVs as struct
fields:
$type = $magic->type
$sv = $magic->obj
$sv = $magic->ptr
$ptr = $magic->vtbl
magic_svs
@svs = $sv->magic_svs
A more efficient way to retrieve just the SVs associated with the applied magic.
backrefs
$av_or_rv = $sv->backrefs
Returns backrefs SV, which may be an AV containing the back references, or if there is
only one, the REF SV itself referring to this.
rootname
$rootname = $sv->rootname
If the SV is a well-known root, this method returns its name. Otherwise returns "undef".
outrefs
@refs = $sv->outrefs
Returns a list of Reference objects for each of the SVs that this one refers to, either
directly by strong or weak reference, indirectly via RV, or inferred by "Devel::MAT"
itself.
Each object is a structure of three fields:
name => STRING
A human-readable string for identification purposes.
strength => "strong"|"weak"|"indirect"|"inferred"
Identifies what kind of reference it is. "strong" references contribute to the
"refcount" of the referrant, others do not. "strong" and "weak" references are SV
addresses found directly within the referring SV structure; "indirect" and "inferred"
references are extra return values added here for convenience by examining the
surrounding structure.
sv => SV
The referrant SV itself.
outrefs_strong
@refs = $sv->outrefs_strong
Returns the subset of "outrefs" that are direct strong references.
outrefs_weak
@refs = $sv->outrefs_weak
Returns the subset of "outrefs" that are direct weak references.
outrefs_direct
@refs = $sv->outrefs_direct
Returns the subset of "outrefs" that are direct strong or weak references.
outrefs_indirect
@refs = $sv->outrefs_indirect
Returns the subset of "outrefs" that are indirect references via RVs.
outrefs_inferred
@refs = $sv->outrefs_inferred
Returns the subset of "outrefs" that are not directly stored in the SV structure, but
instead inferred by "Devel::MAT" itself.
outref_named
$ref = $sv->outref_named( $name )
Since version 0.49.
Looks for a reference whose name is exactly that given, and returns it if so.
Throws an exception if the SV has no such outref of that name.
maybe_outref_named
$ref = $sv->maybe_outref_named( $name )
Since version 0.49.
As "outref_named" but returns "undef" if there is no such reference.
is_mortal
$mortal = $sv->is_mortal
Returns true if this SV is referenced by the temps stack.
IMMORTAL SVs
Three special SV objects exist outside of the heap, to represent "undef" and boolean true
and false. They are
• Devel::MAT::SV::UNDEF
• Devel::MAT::SV::YES
• Devel::MAT::SV::NO
Devel::MAT::SV::GLOB
Represents a glob; an SV of type "SVt_PVGV".
file
line
location
$file = $gv->file
$line = $gv->line
$location = $gv->location
Returns the filename, line number, or combined location ("FILE line LINE") that the GV
first appears at.
name
$name = $gv->name
Returns the value of the "GvNAME" field, for named globs.
stash
$stash = $gv->stash
Returns the stash to which the GV belongs.
scalar
array
hash
code
egv
io
form
$sv = $gv->scalar
$av = $gv->array
$hv = $gv->hash
$cv = $gv->code
$gv = $gv->egv
$io = $gv->io
$form = $gv->form
Return the SV in the various glob slots.
Devel::MAT::SV::SCALAR
Represents a non-referential scalar value; an SV of any of the types up to and including
"SVt_PVMV" (that is, "IV", "NV", "PV", "PVIV", "PVNV" or "PVMG"). This includes all
numbers, integers and floats, strings, and dualvars containing multiple parts.
uv
$uv = $sv->uv
Returns the integer numeric portion as an unsigned value, if valid, or "undef".
iv
$iv = $sv->iv
Returns the integer numeric portion as a signed value, if valid, or "undef".
nv
$nv = $sv->nv
Returns the floating numeric portion, if valid, or "undef".
pv
$pv = $sv->pv
Returns the string portion, if valid, or "undef".
pvlen
$pvlen = $sv->pvlen
Returns the length of the string portion, if valid, or "undef".
qq_pv
$str = $sv->qq_pv( $maxlen )
Returns the PV string, if defined, suitably quoted. If $maxlen is defined and the PV is
longer than this, it is truncated and "..." is appended after the containing quote marks.
ourstash
$stash = $sv->ourstash
Returns the stash of the SCALAR, if it is an '"our"' variable.
After perl 5.20 this is no longer used, and will return "undef".
Devel::MAT::SV::REF
Represents a referential scalar; any SCALAR-type SV with the "SvROK" flag set.
rv
$svrv = $sv->rv
Returns the SV referred to by the reference.
is_weak
$weak = $sv->is_weak
Returns true if the SV is a weakened RV reference.
ourstash
$stash = $sv->ourstash
Returns the stash of the SCALAR, if it is an '"our"' variable.
Devel::MAT::SV::ARRAY
Represents an array; an SV of type "SVt_PVAV".
is_unreal
$unreal = $av->is_unreal
Returns true if the AvREAL() flag is not set on the array - i.e. that its SV pointers do
not contribute to the "SvREFCNT" of the SVs it points at.
is_backrefs
$backrefs = $av->is_backrefs
Returns true if the array contains the backrefs list of a hash or weakly-referenced
object.
elems
@svs = $av->elems
Returns all of the element SVs in a list
elem
$sv = $av->elem( $index )
Returns the SV at the given index
Devel::MAT::SV::PADLIST
A subclass of ARRAY, this is used to represent the PADLIST of a CODE SV.
Devel::MAT::SV::PADNAMES
A subclass of ARRAY, this is used to represent the PADNAMES of a CODE SV.
padname
$padname = $padnames->padname( $padix )
Returns the name of the lexical at the given index, or "undef"
padix_from_padname
$padix = $padnames->padix_from_padname( $padname )
Returns the index of the lexical with the given name, or "undef"
Devel::MAT::SV::PAD
A subclass of ARRAY, this is used to represent a PAD of a CODE SV.
padcv
$cv = $pad->padcv
Returns the "CODE" SV for which this is a pad.
lexvars
( $name, $sv, $name, $sv, ... ) = $pad->lexvars
Returns a name/value list of the lexical variables in the pad.
maybe_lexvar
$sv = $pad->maybe_lexvar( $padname )
Since version 0.49.
Returns the SV associated with the given padname if one exists, or "undef" if not.
Used to be named "lexvar".
Devel::MAT::SV::HASH
Represents a hash; an SV of type "SVt_PVHV". The "Devel::MAT::SV::STASH" subclass is used
to represent hashes that are used as stashes.
keys
@keys = $hv->keys
Returns the set of keys present in the hash, as plain perl strings, in no particular
order.
value
$sv = $hv->value( $key )
Returns the SV associated with the given key
values
@svs = $hv->values
Returns all of the SVs stored as values, in no particular order (though, in an order
corresponding to the order returned by "keys").
Devel::MAT::SV::STASH
Represents a hash used as a stash; an SV of type "SVt_PVHV" whose HvNAME() is non-NULL.
This is a subclass of "Devel::MAT::SV::HASH".
mro_linear_all
mro_linearcurrent
mro_nextmethod
mro_isa
$hv = $stash->mro_linear_all
$sv = $stash->mro_linearcurrent
$sv = $stash->mro_nextmethod
$av = $stash->mro_isa
Returns the fields from the MRO structure
value_code
$cv = $stash->value_code( $key )
Returns the CODE associated with the given symbol name, if it exists, or "undef" if not.
This is roughly equivalent to
$cv = $stash->value( $key )->code
Except that it is aware of the direct reference to CVs that perl 5.22 will optimise for.
This method should be used in preference to the above construct.
stashname
$name = $stash->stashname
Returns the name of the stash
Devel::MAT::SV::CODE
Represents a function or closure; an SV of type "SVt_PVCV".
stash
glob
file
line
scope
padlist
constval
oproot
depth
$stash = $cv->stash
$gv = $cv->glob
$filename = $cv->file
$line = $cv->line
$scope_cv = $cv->scope
$av = $cv->padlist
$sv = $cv->constval
$addr = $cv->oproot
$depth = $cv->depth
Returns the stash, glob, filename, line number, scope, padlist, constant value, oproot or
depth of the code.
location
$location = $cv->location
Returns "FILE line LINE" if the line is defined, or "FILE" if not.
is_clone
is_cloned
is_xsub
is_weakoutside
is_cvgv_rc
is_lexical
$clone = $cv->is_clone
$cloned = $cv->is_cloned
$xsub = $cv->is_xsub
$weak = $cv->is_weakoutside
$rc = $cv->is_cvgv_rc
$lexical = $cv->is_lexical
Returns the CvCLONE(), CvCLONED(), CvISXSUB(), CvWEAKOUTSIDE(), CvCVGV_RC() and
CvLEXICAL() flags.
protosub
$protosub = $cv->protosub
Returns the protosub CV, if known, for a closure CV.
constants
@svs = $cv->constants
Returns a list of the SVs used as constants or method names in the code. On ithreads perl
the constants are part of the padlist structure so this list is constructed from parts of
the padlist at loading time.
globrefs
@svs = $cv->globrefs
Returns a list of the SVs used as GLOB references in the code. On ithreads perl the
constants are part of the padlist structure so this list is constructed from parts of the
padlist at loading time.
padname
$padname = $cv->padname( $padix )
Returns the name of the $padix'th lexical variable, or "undef" if it doesn't have a name.
The returned padname is a structure of the following fields:
$name = $padname->name
$bool = $padname->is_outer
$bool = $padname->is_state
$bool = $padname->is_lvalue
$bool = $padname->is_typed
$bool = $padname->is_our
$bool = $padname->is_field
padix_from_padname
$padix = $cv->padix_from_padname( $padname )
Returns the index of the first lexical variable with the given pad name, or "undef" if one
does not exist.
max_padix
$max_padix = $cv->max_padix
Returns the maximum valid pad index.
This is typically used to create a list of potential pad indexes, such as
0 .. $cv->max_padix
Note that since pad slots may contain things other than lexical variables, not every pad
slot between 0 and this index will necessarily contain a lexical variable or have a pad
name.
padnames_av
$padnames_av = $cv->padnames_av
Returns the AV reference directly which stores the pad names.
After perl version 5.20, this is no longer used directly and will return "undef". The
individual pad names themselves can still be found via the "padname" method.
pads
@pads = $cv->pads
Returns a list of the actual pad AVs.
pad
$pad = $cv->pad( $depth )
Returns the PAD at the given depth (given by 1-based index).
maybe_lexvar
$sv = $cv->maybe_lexvar( $padname, $depth )
Since version 0.49.
Returns the SV on the PAD associated with the given padname, at the optionally-given depth
(1-based index). If $depth is not provided, the topmost live PAD will be used. If no
variable exists of the given name returns "undef".
Used to be called "lexvar".
Devel::MAT::SV::IO
Represents an IO handle; an SV type of "SVt_PVIO".
ifileno
ofileno
$ifileno = $io->ifileno
$ofileno = $io->ofileno
Returns the input or output file numbers.
Devel::MAT::SV::OBJECT
Represents an object instance; an SV of type "SVt_PVOBJ". These are only present in files
from perls with "feature 'class'".
fields
@svs = $obj->fields
Returns all the values of all the fields in a list.
Note that to find the names of the fields you'll have to enquire with the class
field
$sv = $obj->field( $name_or_fieldix )
Returns the value of the given field; which may be specified by name or index directly.
Devel::MAT::SV::CLASS
Represents a class; a sub-type of stash for implementing object classes. These are only
present in files from perls with "feature 'class'".
fields
@fields = $class->fields
Returns a list of the field definitions of the class, in declaration order. Each is a
structure whose form is given below.
field
$field = $class->field( $name_or_fieldix )
Returns the field definition of the given field; which may be specified by name or index
directly. Throws an exception if none such exists.
The returned field is a structure of the following fields:
$fieldix = $field->fieldix
$name = $field->name
maybe_field
$field = $class->maybe_field( $name_or_fieldix )
Since version 0.49.
Similar to "field" but returns undef if none such exists.
Devel::MAT::SV::C_STRUCT
Represents a C-level c<struct> type.
fields
@kvlist = $struct->fields
Returns an even-sized name/value list of all the field values stored by the struct; each
preceeded by its field type structure.
field_named
$val = $struct->field_named( $name )
Looks for a field whose name is exactly that given, and returns its value.
Throws an exception if the struct has no such field of that name.
maybe_field_named
$val = $struct->maybe_field_named( $name )
Since version 0.49.
As "field_named" but returns "undef" if there is no such field.
structtype
$structtype = $struct->structtype
Returns a metadata structure describing the type of the struct itself.
Has the following named accessors
name => STRING
The name of the struct type, as given by the dumpfile.
fields => ARRAY[ Field ]
An ARRAY reference containing the definitions of each field in turn
AUTHOR
Paul Evans <leonerd@leonerd.org.uk>