view release on metacpan or  search on metacpan

DBUG.pm  view on Meta::CPAN

   # While enforcing a minimum version ...
   use Fred::Fish::DBUG 2.03 qw / on /;

=head1 TRAPPING SIGNALS IN FISH

As an extension to the Fred Fish library, this module allows the trapping and
logging to B<fish> of all trappable signals for your OS.  This list of signals
varies per OS.  But the most common two being B<__DIE__> and B<__WARN__>.

But in order to trace these signals you must first ask B<fish> to do so by
by first sourcing in L<Fred::Fish::DBUG::Signal>, and then calling
B<DBUG_TRAP_SIGNAL>.  See that module for more details.  You don't have to
use that module, but it can make thigs easier if you do.

Just be aware that both B<__DIE__> and B<__WARN__> signals can be thrown
during Perl's parsing phase of your code.  So care must be taken if you try
to trap these signals in a BEGIN block.  Since if set in BEGIN these traps
may end up interfering with your attempts to debug your code.

=head1 TRAPPING STDOUT AND STDERR IN FISH

Another extension to the Fred Fish libary allowing you to trap all prints to
STDOUT and/or STDERR to also appear in your B<fish> logs.  Implemented as a
wrapper to Perl's "B<tie>" feature against the SDTOUT and STDERR file handles.

Very useful for putting prints from your program or other modules into context
in your fish logs.  Just be aware that you may have only one B<tie> per file
handle.  But if your code does require ties to work, this module provides a
way to coexist.

See L<Fred::Fish::DBUG::TIE> for more details on how to enable this feature.

=head1 FISH FOR MULTI-THREADED PERL PROGRAMS

This module should be thread-safe as long as Perl's I<print> command is
thread-safe.  If threads are used, there are two ways to use this module.

The first way is call DBUG_PUSH($file, multi=>1) in the main process and then
spawn your threads.  This will cause all threads to write to the same B<fish>
file as your main program.  But you'll have to use a tool such as B<grep> in
order to be able to trace the logic of individual threads.  Thread 0 is the main
process.  If you don't use the B<multi> option, your B<fish> log will be
unusable since you'll be unable to tell which thread wrote each entry in your
log.

The second way is to not call DBUG_PUSH() in the main thread until after you
spawn all your threads.  In this case you can't share the same B<fish> file
name.  Each thread should call DBUG_PUSH($file) using a unique file name for
each thread's B<fish> log.  Using option B<multi> is optional in this case,
but still recommended.

But what happens with the B<second> option if you reuse the same filename
between threads?  In that case this module is B<not> thread-safe!  Each thread
can step on each other.  You can limit the impact with a creative combination
of options to DBUG_PUSH(), but you can't reliably remove all the corruption
and dropped lines in the shared B<fish> logs.  And your work around may
break in future releases of this module.

As a reminder, when the main process (I<thread # 0>) terminates, this causes
all the child threads to terminate as well.  Even if they are still busy.
Also child threads do not normally call I<BEGIN> and/or I<END> blocks of code!
And all threads share the same PID.

=head1 FISH FOR MULTI-PROCESS PERL PROGRAMS

This is when you spawn a child process using B<fork>.  In this case all
processes have a unique PID and each child process will call their own I<END>
blocks.  But otherwise it follows the same B<fish> rules as multi-threading.

When the parent process terminates, it allows any running child process to
finish it's work and they can still write to B<fish>.

To turn on fish for multi-process use DBUG_PUSH($file, multi=>1) as well.

=head1 FURTHER INFORMATION

Not all Perl implementations support mutli-threading and/or multi-processing.
So if you are not using multi-threading or multi-processing, I recommend
I<not> using the B<multi> option.

=head1 USING GOTO STATEMENTS

Using a B<goto> can cause B<fish> issues where the return statements get out
of sync with the proper function entry points in your B<fish> logs.  This is
because calls like B<goto &MyPackage::MyFunction;> jump to MyFunction's entry
point, and removes the function using B<goto> from Perl's stack as if it was
never there.

Currently the only fix for this is to not use B<DBUG_ENTER_(FUNC|BLOCK)> and
the corresponding B<DBUG_RETURN> methods in functions that use B<goto>.
Limit yourself to calls to B<DBUG_PRINT> in those methods instead.

Your other choice is to reorganize your code to avoid using the B<goto>
statement in the first place.

A common place you'd see a B<goto> is if you used the I<AUTOLOAD> function.
But even there, there are alternatives to using the B<goto> if you want
clean B<fish> logging.

=head1 USING THIS MODULE IN A CPAN MODULE

When you upload a module using B<fish> to CPAN, you probably don't want your
code trace being dumped to an end user's B<fish> logs by default.  So I
recommend doing the following in your code so that "make test" will still have
B<fish> turned on, while normal usage won't trace in B<fish>.

  use Fred::Fish::DBUG qw / on_if_set  my_special_module_flag /;

For an explination on how this works, reread the POD above.

=head1 FUNCTIONS

=over 4

=cut 

package Fred::Fish::DBUG;

use strict;
use warnings;