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

  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" )'

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.

• extends Exception::Base

ATTRS : HashRef

Declaration of class attributes as reference to hash.

See Exception::Base for details.

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.

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.

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"

_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.

__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');
      # ...
  };

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.

Exception::Base.

If you find the bug, please report it.

Piotr Roszatycki <dexter@cpan.org>

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