untie#

Break the binding between a variable and its tied class.

untie reverses a prior tie: after the call, VARIABLE goes back to being a plain scalar, array, hash, or filehandle, and subsequent reads and writes touch the raw storage rather than being routed through the tied package’s FETCH, STORE, and friends. If the variable is not tied, untie is a no-op.

Synopsis#

untie VARIABLE

What you get back#

Returns a true value if the variable was tied and the binding was removed, false otherwise. The return value is rarely checked — call sites know whether they are unwinding a tie they set up themselves.

As a side effect, if the tied package defines an UNTIE method, it is invoked on the tied object before the binding is dropped. UNTIE receives the object and a count of any outstanding inner references held to it (see Edge cases below).

What it does#

Locate the magic on VARIABLE that a prior tie installed.
If the tied package provides UNTIE, call it on the object.
Remove the magic so the variable reverts to ordinary storage.
Release the interpreter’s reference to the tied object. The object is destroyed (triggering DESTROY if defined) once no other references to it remain.

After untie, any value tied previously returned for this variable no longer corresponds to a live binding.

Examples#

Tie a hash, use it, then release it:

use Tie::File;
tie my @lines, 'Tie::File', 'log.txt' or die $!;
push @lines, "new entry";
untie @lines;                       # flush and release

A round-trip through tied — grab the underlying object so you can call a non-tied method on it, then drop the binding:

my $obj = tied %cache;
$obj->flush;
untie %cache;

untie on a variable that was never tied is harmless:

my %h;
untie %h;                           # no-op, no warning

An UNTIE hook that runs before the binding goes away:

package My::Tied;
sub TIEHASH { bless {}, shift }
sub UNTIE   { my ($self, $count) = @_;
              warn "untie with $count outstanding refs" if $count }
# ...
tie   my %h, 'My::Tied';
untie %h;                           # calls My::Tied::UNTIE($obj, 0)

Edge cases#

Outstanding inner references: if code stashed the object returned by tie or tied somewhere that still holds it at the moment untie runs, Perl issues
```
untie attempted while N inner references still exist
```
under use warnings. The binding is removed anyway, but those stashed references continue to point at the now-detached object. Drop those references first, or accept that they will now see the un-tied object in isolation.
Calling untie on a non-tied variable is a no-op. No warning, no error, no method call.
Filehandle tie: untie *FH removes the tie installed by tie *FH, $class, .... The underlying glob and any real file descriptor behind it are unaffected — untie does not close.
UNTIE is optional: if the tied package does not define one, the binding is simply removed. Do not rely on UNTIE running; many tied classes omit it.
Destruction order: untie does not itself call DESTROY. The object is destroyed when its refcount hits zero, which may be immediately after untie (if nothing else holds it) or later (if the caller kept a copy from tied).
Localised tied variables: a tie installed inside a scope on a localised variable is undone automatically when the scope exits; you do not need an explicit untie, and calling one is harmless.

Differences from upstream#

Fully compatible with upstream Perl 5.42.