tied#

Return the object backing a tied variable.

tied hands you the same reference that tie originally returned when VARIABLE was bound to a class. Through that reference you can call methods directly on the tie implementation — bypassing the usual FETCH / STORE dispatch — which is how tie classes expose extra operations that have no natural scalar / array / hash syntax. If VARIABLE is not tied, tied returns undef.

Synopsis#

tied VARIABLE

What you get back#

A reference to the underlying tie object when VARIABLE is tied, and undef when it is not. The reference is the exact value originally returned by the matching tie call — same class, same blessed identity — so ref(tied $v) names the tie class and method calls on it dispatch normally:

my $obj = tied %hash;
$obj->flush if defined $obj;

Use defined (or a boolean test, when the tie class never blesses into a false-overloading package) to distinguish a tied variable from an untied one before calling methods on the result.

The “tie handle” trick#

tied is the only supported way to talk to the tie implementation directly. Any method on the tie class that is not one of the standard hooks (FETCH, STORE, EXISTS, DELETE, CLEAR, FIRSTKEY, NEXTKEY, and their array / scalar / handle equivalents) is reachable only through the object tied returns:

tie my %cache, 'My::LRU', size => 1024;
tied(%cache)->stats;           # class-specific method, no hash syntax
tied(%cache)->evict_older_than(3600);

This is also the pattern for introspection — asking a tied variable “who are you tied to?” without assuming knowledge of the binding site:

my $class = ref tied @array;   # e.g. "Tie::File"

Examples#

Basic test for tiedness:

tie my %h, 'My::Tied::Hash';
print defined(tied %h) ? "tied\n" : "not tied\n";   # tied

Calling a class-specific method through the tie object:

tie my @log, 'Tie::File', 'app.log' or die $!;
tied(@log)->flock(2);          # LOCK_EX; Tie::File API
# ... mutate @log ...
tied(@log)->flock(8);          # LOCK_UN

A plain scalar, array, hash, or filehandle that was never tied:

my $x;
print defined(tied $x) ? "yes" : "no", "\n";        # no

tied does not untie — the variable stays tied after the call, and successive calls return the same reference:

tie my $t, 'My::Counter';
my $a = tied $t;
my $b = tied $t;
print $a == $b ? "same\n" : "different\n";          # same

Round-tripping through ref to learn the tie class:

tie my %db, 'DB_File', 'data.db', O_RDWR | O_CREAT, 0644;
print ref tied %db, "\n";      # DB_File

Edge cases#

Not tied: returns undef. No warning, no exception. This is the idiomatic way to check whether a variable is tied at all — there is no separate is_tied built-in.
Filehandles: tied *FH returns the object for a tied filehandle (bound with tie *FH, ...). A glob that was never tied yields undef just like any other untied variable.
tied does not untie. It is a pure accessor. To release the binding, call untie. Holding the reference returned by tied past the point where the variable is untied keeps the tie object alive, which is deliberate — that is how untie warnings about “untie attempted while N inner references still exist” are triggered.
Tied element of an aggregate: when an individual array or hash element is itself tied (separate from a tie on the container), tied $array[0] or tied $hash{key} returns the per-element object, not the container’s. A container tie and an element tie are independent bindings.
Copied values are not tied. my $copy = $tied_scalar; stringifies through FETCH; $copy is a plain scalar and tied $copy returns undef. Tie is a property of the variable, not of the value.
References to tied variables preserve the tie. \%hash where %hash is tied still refers to the tied container, so tied %{ $ref } returns the same tie object.

Differences from upstream#

Fully compatible with upstream Perl 5.42.