/ 
Exception-Died-0.06
River stage one • 3 direct dependents • 7 total dependents
/ Exception::Died

NAME

Exception::Died - Convert simple die into real exception object

SYNOPSIS

use Exception::Died;

use warnings FATAL => 'all';
eval { open $f, "x", "bad_open_mode" };
Exception::Died->throw( message=>"cannot open" ) if $@;

eval { die "Bum!\n" };
if ($@) {
  my $e = Exception::Died->catch;
  $e->throw;
};

# Can replace die hook globally
use Exception::Died '%SIG' => 'die';
eval { die "Boom!\n" };
print ref $@;           # "Exception::Died"
print $@->eval_error;   # "Boom!"

# Can be used in local scope only
use Exception::Died;
{
    local $SIG{__DIE__};
    Exception::Fatal->import('%SIG');
    eval { die "Boom!" };
    print ref $@;           # "Exception::Died"
    print $@->eval_error;   # "Boom!"
};
eval { die "Boom" };
print ref $@;       # ""

# Debugging with increased verbosity
$ perl -MException::Died=:debug script.pl

# Debugging one-liner script
$ perl -MException::Died=:debug -ale '\
use File::Temp; $tmp = File::Temp->new( DIR => "/notfound" )'

DESCRIPTION

This class extends standard Exception::Base and converts eval's error into real exception object. The eval's error message is stored in eval_error attribute.

This class can be also used for debugging scripts with use simple "die" in perlfunc or Carp. You can raise verbosity level and print stack trace if script doesn't use Exception::Base and has stopped with "die" in perlfunc.

INHERITANCE

CONSTANTS

ATTRS : HashRef

Declaration of class attributes as reference to hash.

See Exception::Base for details.

ATTRIBUTES

This class provides new attributes. See Exception::Base for other descriptions.

eval_error : Str {ro}

Contains the message from failed eval block. This attribute is automatically filled on object creation.

use Exception::Died '%SIG';
eval { die "string" };
print $@->eval_error;  # "string"
catch_can_rebless : Str {ro}

Contains the flag for catch method which marks that this exception object should be reblessed. The flag is marked by internal __DIE__ hook.

eval_attribute : Str = "eval_error"

Meta-attribute contains the name of the attribute which is filled if error stack is empty. This attribute will contain value of $@ variable. This class overrides the default value from Exception::Base class.

string_attributes : ArrayRef[Str] = ["message", "eval_error"]

Meta-attribute contains the format of string representation of exception object. This class overrides the default value from Exception::Base class.

default_attribute : Str = "eval_error"

Meta-attribute contains the name of the default attribute. This class overrides the default value from Exception::Base class.

IMPORTS

use Exception::Died '%SIG';
use Exception::Died '%SIG' => 'die';

Changes $SIG{__DIE__} hook to Exception::Died::__DIE__.

use Exception::Died ':debug';

Changes $SIG{__DIE__} hook and sets verbosity level to 4 (maximum).

no Exception::Died '%SIG';

Undefines $SIG{__DIE__} hook.

CONSTRUCTORS

catch() : Self|$@

This method overwrites the default catch constructor. It works as method from base class and has one exception in its behavior.

my $e = CLASS->catch;

If the popped value is an Exception::Died object and has an attribute catch_can_rebless set, this object is reblessed to class $class with its attributes unchanged. It is because original Exception::Base->catch method doesn't change exception class but it should be changed if Exception::Died handles $SIG{__DIE__} hook.

use Exception::Base
  'Exception::Fatal'  => { isa => 'Exception::Died' },
  'Exception::Simple' => { isa => 'Exception::Died' };
use Exception::Died '%SIG' => 'die';

eval { die "Died\n"; };
my $e = Exception::Fatal->catch;
print ref $e;   # "Exception::Fatal"

eval { Exception::Simple->throw; };
my $e = Exception::Fatal->catch;
print ref $e;   # "Exception::Simple"

METHODS

_collect_system_data() : Self

Collect system data and fill the attributes of exception object. This method is called automatically if exception if thrown. This class overrides the method from Exception::Base class.

See Exception::Base.

FUNCTIONS

__DIE__()

This is a hook function for $SIG{__DIE__}. This hook can be enabled with pragma:

use Exception::Died '%SIG';

or manually, i.e. for local scope:

{
    local $SIG{__DIE__};
    Exception::Died->import('%SIG');
    # ...
};

PERFORMANCE

The Exception::Died module can change $SIG{__DIE__} hook. It costs a speed for simple die operation. The failure scenario was benchmarked with default setting and with changed $SIG{__DIE__} hook.

-----------------------------------------------------------------------
| Module                              | Without %SIG  | With %SIG     |
-----------------------------------------------------------------------
| eval/die string                     |      237975/s |        3069/s |
-----------------------------------------------------------------------
| eval/die object                     |      124853/s |       90575/s |
-----------------------------------------------------------------------
| Exception::Base eval/if             |        8356/s |        7984/s |
-----------------------------------------------------------------------
| Exception::Base try/catch           |        9218/s |        8891/s |
-----------------------------------------------------------------------
| Exception::Base eval/if verbosity=1 |       14899/s |       14300/s |
-----------------------------------------------------------------------
| Exception::Base try/catch verbos.=1 |       18232/s |       16992/s |
-----------------------------------------------------------------------

It means that Exception::Died with die hook makes simple die 30 times slower. However it has no significant difference if the exception objects are used.

Note that Exception::Died will slow other exception implementations, like Class::Throwable and Exception::Class.

SEE ALSO

Exception::Base.

BUGS

If you find the bug, please report it.

AUTHOR

Piotr Roszatycki <dexter@cpan.org>

LICENSE

Copyright (c) 2008, 2009 by Piotr Roszatycki <dexter@cpan.org>.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

See http://www.perl.com/perl/misc/Artistic.html