NAME

Fred::Fish::DBUG::Signal - Fred Fish library extension to trap Signals.

SYNOPSIS

use Fred::Fish::DBUG::Signal;
  or
require Fred::Fish::DBUG::Signal;

DESCRIPTION

Fred::Fish::DBUG::Signal is a pure Perl extension to the Fred::Fish::DBUG module. Using this module allows you to trap the requested signal and write the event to your fish logs. Kept separate since not all OS support Signal handling. Also the list of Signals supported varry by OS.

You are not required to use this module when trapping signals, but it's useful for logging in fish that a signal was trapped and where in the code the signal was trigereed when seeing how a caught signal affects your code.

FUNCTIONS

DBUG_TRAP_SIGNAL ( $signal, $action [, @forward_to] )

This function instructs DBUG to trap the requested signal and write the event to fish. If the signal name isn't in the %SIG hash, or the $action is invalid, then the request will be ignored! Just be warned that not all signals are trappable, and the list of signals may vary per OS. Also note that if the untrapped signal causes your program to terminate, any clean up done in any END blocks will also be ignored.

This signal is trapped even when fish is turned off. So the behavior of your program doesn't change when fish is turned on and off. Except that nothing is writen to fish when fish is turned off.

If called multiple times for the same signal, only the info for the last time called is active. It returns 1 if the signal is now trapped or removed. It returns 0 if it had issues that prevented it from taking the requested action against the signal.

Never call this function in a BEGIN block of code. If you do so and hit compile time issues, it can make your life very difficult trying to debug things.

The $action flag tells what this module is to do with this signal once it is trapped and logged to fish. See below for this list of valid action constants! If the action is a negative value, it will call abs() before it's validated.

DBUG_SIG_ACTION_REMOVE - Remove this $signal from the list of signals trapped. Then restore $SIG{$signal} to it's original setting. It does nothing if the signal wasn't trapped by this module.

DBUG_SIG_ACTION_EXIT13 - Exit your program with the status of 13. (Recommended for most signals.)

DBUG_SIG_ACTION_EXIT_SIGNUM - Exit your program with the signal number associated with the trapped signal as your exit status. For signals DIE and WARN, they will exit with 240/241 since they have no signal numbers!

DBUG_SIG_ACTION_DIE - Call die, it's trappable by eval or try/catch. (Recommended for signal DIE, using anything else for DIE could break a lot of code.)

DBUG_SIG_ACTION_LOG - Just log to fish and return control to your code. (Recommended for signal WARN) Doesn't work for signal DIE, so can't use this action to try to avoid the need for eval or try/catch blocks in your code.

Just be aware that trapping certain signals and returning control back to your program can sometimes cause strange behavior.

If action DBUG_SIG_ACTION_DIE was used for your non-die signal, it will also call die's list of functions if die was also trapped by this module. But if you trap die outside of this module this may trigger an unexpected duplicate call to your custom die routine. So in this case it's best to leave die untrapped or trapped via this module as well.

If you provided @forward_to it will assume you wish to call those function(s) in the order specified after the signal has been logged to fish, but before the specified $action is taken. This array may contain zero or more entries in it! Each entry in this array may be a reference to a function or a fully qualified function name as a string.

When called, these functions will be passed one argument. For most signals its the name of the trapped signal. But if called by trapping DIE or WARN, it is the message printed by die or warn. Just be aware that calls to die and warn with multiple arguments have them joined together before the signal is generated. Any return value will be ignored.

But what happens if you call die in one of these forward_to functions? In that case the die request is ignored. It's treated as an instruction to the signal handler that it is to stop calling additional forward_to function(s) in this list. It will not override the action selected. If you really want to terminate your program in one of these functions, write your message to STDERR and call exit or DBUG_LEAVE instead!

NOTE: If you really, really want DBUG_SIG_ACTION_LOG to work for die, see module Fred::Fish::DBUG::SignalKiller and immediately forget you asked about this.

DBUG_FIND_CURRENT_TRAPS ( $signal )

This function tells if the requested $signal is currently being trapped by this module via DBUG_TRAP_SIGNAL or not.

It can return one or more values: ($action_taken [, $func1 [, $func2 [, ...]]])

If the signal isn't being trapped by this module it returns (undef).

If the signal is being trapped, but not forwarded it returns ($action_taken). As an FYI, no valid action has a value of zero.

Otherwise it returns the $action_taken and the list of functions it is scheduled to call if the signal gets trapped.

But if called in scalar mode it just returns $action_taken and tosses the list of functions.

Each function will be returned as a CODE reference. Even if it was originally passed to DBUG_TRAP_SIGNAL as a string containing the function to call.

If someone reset $SIG{$signal} manually, this function will detect that and return (-1 * $action) for the action. To make it easy to detect this problem.

DBUG_DIE_CONTEXT ( )

This is a helper method to DBUG_TRAP_SIGNAL. For use when your custom die routine(s) are called by the signal handler on a die request. You call this method for the context of the die request being handled.

It returns ( $fish_managed, $eval_trap, $original_signal, $rethrown, $die_action ).

If called in scalar mode it returns ( $fish_managed ).

$fish_managed - A boolean flag that tells if Fred::Fish::DBUG managed the call to your custom die function via a trapped __DIE__ signal.

$eval_trap - Boolean value telling if this call to die is going to be trapped by an eval block of code and/or a try/catch block of code. Otherwise it is false if it will be terminating your program when you return to the signal handler. It has no way of telling what the caller will do once it catches the result.

$original_signal - Tells which signal triggered the call to die. If a non-die signal was trapped using action DBUG_SIG_ACTION_DIE, it returns the name of the trapped signal. It returns __DIE__ if triggered directly. Otherwise it returns the empty string if the call wasn't managed by fish.

$rethrown - A boolean flag that attempts to detect if your code caught a previous call to die in an eval or try block and then called die again with the same mesage. It's set to 1 if the previous die message was the same as the current die message. Else it's set to 0. So if you change the messsage before rethrowing the error again, this flag can't help you. Many times you'd like to do nothing on a rethrown die signal.

$die_action - A code that tells what the die handler will do when it catches any die thrown by your custom function. 1 - Die is ignored. 2 - Tells the DIE handler not to call any more custom DIE function(s). 0 - The context function doesn't know the answer.

CREDITS

Thanks to Fred Fish for developing the basic algorithm and putting it into the public domain! Any bugs in its implementation are purely my fault.

SEE ALSO

Fred::Fish::DBUG The controling Fred Fish DBUG module.

Fred::Fish::DBUG::ON The live version of the DBUG module. Used to log fish calls made by this module.

Fred::Fish::DBUG::OFF The stub version of the DBUG module.

Fred::Fish::DBUG::TIE - Allows you to trap and log STDOUT/STDERR to fish.

Fred::Fish::DBUG::SignalKiller - Allows you to implement action DBUG_SIG_ACTION_LOG for die. Really dangerous to use. Will break most code bases.

Fred::Fish::DBUG::Test - A Test::More wrapper to redirect test results to fish.

Fred::Fish::DBUG::Tutorial - Sample code demonstrating using DBUG module.

COPYRIGHT

Copyright (c) 2007 - 2024 Curtis Leach. All rights reserved.

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