refcount

Reference count of the thing $ref points at.

Synopsis

use Peta::XS ':facts';
my $x;
my $n = refcount(\$x);   # 2 - see the observer effect below

What you get back

An integer: how many references the runtime currently holds to the referent, at call time. Works on any referent - scalars, arrays, hashes, subs, aggregate elements. Croaks if the argument is not a reference; never dies otherwise.

Observer effect

The reference you pass in contributes one count of its own for the duration of the call, exactly as with Devel::Refcount::refcount. It is deliberately NOT subtracted: a lexical with no other references reports 2 (its pad slot plus your temporary reference).

Examples

my $x = 42;
say refcount(\$x);        # 2: pad slot + the \$x you just made

my $r = \$x;
say refcount($r);         # 2: pad slot + $r (no extra temporary)
my $r2 = \$x;
say refcount($r);         # 3: pad slot + $r + $r2

my @queue = ($r);
say refcount($r);         # 4: the array element counts too

## leak hunting: a cache entry still pinning an object

my $obj = SomeClass->new;
$cache{key} = $obj;
say refcount(\$obj);      # 3 - the cache holds one; forget it and
delete $cache{key};       # the count drops back to 2

See also

• value_slots - which representations the value holds.

• magic - what is attached to the variable.

• Scalar::Util::refaddr / builtin::refaddr - identity, not count.