NAME

Forks::Super::Debug - debugging and logging routines for Forks::Super distro

VERSION

0.97

VARIABLES

$DEBUG

Many routines in the Forks::Super module look at this variable to decide whether to invoke the "debug" function. So if this variable is set to true, a lot of information about what the Forks::Super module is doing will be written to the debugging output stream.

If the environment variable FORKS_SUPER_DEBUG is set, the $DEBUG variable will take on its value. Otherwise, the default value of this variable is zero.

$DEBUG_FH

An output file handle for all debugging messages. Initially, this module tries to open $DEBUG_FH as an output handle to the current tty (CON on MSWin32). If that fails, it will try to dup file descriptor 2 (which is usually STDERR) or alias $DEBUG_FH directly to *STDERR.

The initial setting can be overwritten at runtime. See t/15-debug.t in this distribution for an example.

FUNCTIONS

debug

Output the given message to the current $DEBUG_FH file handle. Usually you check whether $DEBUG is set to a true value before calling this function.

carp_once

Like "carp" in Carp, but remembers what warning messages have already been printed and suppresses duplicate messages. This is useful for heavily used code paths that usually work, but tend to produce an enormous number of warnings when they don't.

    use Forks::Super::Debug 'carp_once';
    for (1 .. 9999) {
        $var = &some_function_that_should_be_zero_but_sometimes_isnt;
        if ($var != 0) {
            carp_once "var was $var, not zero!";
        }
    }

should produce at most one warning in the lifetime of the program,

carp_once can take a list reference as an optional first argument to provide additional context for the warning message. This code, for example, will produce one warning message for every different value of $! that can be produced.

    while (<$fh>) {
        local $! = 0;
        do_something($_);
        if ($!) {
            carp_once [$!], "do_something() did something!: $!";
        }
    }

enable_dump

Writes information about all known jobs to the console in response to an OS signal.

This feature is inspired by the many implementations of the Java Virtual Machine that can dump a list of all thread stack traces when the JVM receives a SIGQUIT signal.

Forks::Super::Debug::enable_dump is this module's attempt to emulate this feature. When the program receives the specified signal, it will dump information about all known jobs to the console.

enable_dump takes one argument. If the argument evaluates to false, the process dump will be disabled and all signals will revert to their default behavior. If the argument is a signal name, the program will respond to that signal by dumping information about all processes to the console. If the argument is a true value but not a signal name, the program will respond to SIGQUIT signals.

This feature may also be enabled upon import of Forks::Super using the ENABLE_DUMP arg. For example,

    use Forks::Super ENABLE_DUMP => 'USR1';

will configure the program to respond to SIGUSR1 events. The module can also enable this feature based on the value of the $ENV{FORKS_SUPER_ENABLE_DUMP} environment variable.

EXPORTS

This module exports the $DEBUG variable and the debug and carp_once methods. The :all tag exports all of these symbols.

SEE ALSO

Forks::Super, Carp

AUTHOR

Marty O'Brien, <mob@cpan.org>

LICENSE AND COPYRIGHT

Copyright (c) 2009-2017, Marty O'Brien.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

See http://dev.perl.org/licenses/ for more information.

cpanm Forks::Super

perl -MCPAN -e shell
install Forks::Super