184 lines
3.7 KiB
Perl
184 lines
3.7 KiB
Perl
package Scope::Guard;
|
|
|
|
use strict;
|
|
use warnings;
|
|
|
|
use Carp qw(confess);
|
|
use Exporter ();
|
|
|
|
our @ISA = qw(Exporter);
|
|
our @EXPORT_OK = qw(guard scope_guard);
|
|
our $VERSION = '0.21';
|
|
|
|
sub new {
|
|
confess "Can't create a Scope::Guard in void context" unless (defined wantarray);
|
|
|
|
my $class = shift;
|
|
my $handler = shift() || die 'Scope::Guard::new: no handler supplied';
|
|
my $ref = ref $handler || '';
|
|
|
|
die "Scope::Guard::new: invalid handler - expected CODE ref, got: '$ref'"
|
|
unless ref($handler) eq 'CODE';
|
|
|
|
bless [ 0, $handler ], ref $class || $class;
|
|
}
|
|
|
|
sub dismiss {
|
|
my $self = shift;
|
|
my $dismiss = @_ ? shift : 1;
|
|
|
|
$self->[0] = $dismiss;
|
|
}
|
|
|
|
sub guard(&) { __PACKAGE__->new(shift) }
|
|
sub scope_guard($) { __PACKAGE__->new(shift) }
|
|
|
|
sub DESTROY {
|
|
my $self = shift;
|
|
my ($dismiss, $handler) = @$self;
|
|
|
|
$handler->() unless ($dismiss);
|
|
}
|
|
|
|
1;
|
|
|
|
__END__
|
|
|
|
=pod
|
|
|
|
=head1 NAME
|
|
|
|
Scope::Guard - lexically-scoped resource management
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
my $guard = guard { ... };
|
|
|
|
# or
|
|
|
|
my $guard = scope_guard \&handler;
|
|
|
|
# or
|
|
|
|
my $guard = Scope::Guard->new(sub { ... });
|
|
|
|
$guard->dismiss(); # disable the handler
|
|
|
|
=head1 DESCRIPTION
|
|
|
|
This module provides a convenient way to perform cleanup or other forms of resource
|
|
management at the end of a scope. It is particularly useful when dealing with exceptions:
|
|
the C<Scope::Guard> constructor takes a reference to a subroutine that is guaranteed to
|
|
be called even if the thread of execution is aborted prematurely. This effectively allows
|
|
lexically-scoped "promises" to be made that are automatically honoured by perl's garbage
|
|
collector.
|
|
|
|
For more information, see: L<http://www.drdobbs.com/cpp/184403758>
|
|
|
|
=head1 METHODS
|
|
|
|
=head2 new
|
|
|
|
my $guard = Scope::Guard->new(sub { ... });
|
|
|
|
# or
|
|
|
|
my $guard = Scope::Guard->new(\&handler);
|
|
|
|
The C<new> method creates a new C<Scope::Guard> object which calls the supplied handler when its C<DESTROY> method is
|
|
called, typically at the end of the scope.
|
|
|
|
=head2 dismiss
|
|
|
|
$guard->dismiss();
|
|
|
|
# or
|
|
|
|
$guard->dismiss(1);
|
|
|
|
C<dismiss> detaches the handler from the C<Scope::Guard> object. This revokes the "promise" to call the
|
|
handler when the object is destroyed.
|
|
|
|
The handler can be re-enabled by calling:
|
|
|
|
$guard->dismiss(0);
|
|
|
|
=head1 EXPORTS
|
|
|
|
=head2 guard
|
|
|
|
C<guard> takes a block and returns a new C<Scope::Guard> object. It can be used
|
|
as a shorthand for:
|
|
|
|
Scope::Guard->new(...)
|
|
|
|
e.g.
|
|
|
|
my $guard = guard { ... };
|
|
|
|
Note: calling C<guard> anonymously, i.e. in void context, will raise an exception.
|
|
This is because anonymous guards are destroyed B<immediately>
|
|
(rather than at the end of the scope), which is unlikely to be the desired behaviour.
|
|
|
|
=head2 scope_guard
|
|
|
|
C<scope_guard> is the same as C<guard>, but it takes a code ref rather than a block.
|
|
e.g.
|
|
|
|
my $guard = scope_guard \&handler;
|
|
|
|
or:
|
|
|
|
my $guard = scope_guard sub { ... };
|
|
|
|
or:
|
|
|
|
my $guard = scope_guard $handler;
|
|
|
|
As with C<guard>, calling C<scope_guard> in void context will raise an exception.
|
|
|
|
=head1 VERSION
|
|
|
|
0.21
|
|
|
|
=head1 SEE ALSO
|
|
|
|
=over
|
|
|
|
=item * L<B::Hooks::EndOfScope|B::Hooks::EndOfScope>
|
|
|
|
=item * L<End|End>
|
|
|
|
=item * L<Guard|Guard>
|
|
|
|
=item * L<Hook::Scope|Hook::Scope>
|
|
|
|
=item * L<Object::Destroyer|Object::Destroyer>
|
|
|
|
=item * L<Perl::AtEndOfScope|Perl::AtEndOfScope>
|
|
|
|
=item * L<ReleaseAction|ReleaseAction>
|
|
|
|
=item * L<Scope::local_OnExit|Scope::local_OnExit>
|
|
|
|
=item * L<Scope::OnExit|Scope::OnExit>
|
|
|
|
=item * L<Sub::ScopeFinalizer|Sub::ScopeFinalizer>
|
|
|
|
=item * L<Value::Canary|Value::Canary>
|
|
|
|
=back
|
|
|
|
=head1 AUTHOR
|
|
|
|
chocolateboy <chocolate@cpan.org>
|
|
|
|
=head1 COPYRIGHT
|
|
|
|
Copyright (c) 2005-2015, chocolateboy.
|
|
|
|
This module is free software. It may be used, redistributed and/or modified under the same terms
|
|
as Perl itself.
|
|
|
|
=cut
|