/ 
Devel-MAT-0.53
River stage one • 3 direct dependents • 3 total dependents
/ Devel::MAT::SV

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>