NAME

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

SYNOPSIS

  # Can be loaded via Exception::Base pragma
  use Exception::Base 'Exception::Died';

  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::Died::__DIE__;
      eval { die "Boom!"; }
      print ref $@;           # "Exception::Died"
      print $@->eval_error;   # "Boom!"
  }
  eval { die "Boom"; }
  print ref $@;       # ""

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.

BASE CLASSES

• Exception::Base

IMPORTS

use Exception::Died '%SIG';

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

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

no Exception::Died '%SIG';

Undefines $SIG{__DIE__} hook.

CONSTANTS

ATTRS

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 (ro)

Contains the message which returns eval block. This attribute is automatically filled on object creation.

eval_thrown (rw)

Contains the flag for catch method if it should rebless thrown exception based on simple die. The flag is marked by internal __DIE__ hook.

METHODS

CLASS->catch([$variable])

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

If the popped value is an Exception::Died object and has an attribute eval_thrown set, this object is reblessed to class CLASS with its attributes unchanged. It will mimic the behaviour of Exception::Base if it was caught simple die.

  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"

stringify([$verbosity[, $message]])

Returns the string representation of exception object. It is called automatically if the exception object is used in scalar context. The method can be used explicity and then the verbosity level can be used.

The format of output is "message: eval_error".

PRIVATE METHODS

_collect_system_data

Collect system data and fill the attributes of exception object. This method is called automatically if exception if throwed.

See Exception::Base.

PRIVATE 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::__DIE__;

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@debian.org>

LICENSE

Copyright (C) 2008 by Piotr Roszatycki <dexter@debian.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

cpanm Exception::Died

perl -MCPAN -e shell
install Exception::Died