NAME

Forks::Super::Util - utility routines for Forks::Super module

VERSION

0.86

SYNOPSIS

    use Forks::Super::Util qw(functions to import);
    use Forks::Super::Util qw(:all);

DESCRIPTION

A collection of useful and mostly unrelated routines for things that the Forks::Super distribution needs to do.

SUBROUTINES

In alphabetical order.

$absolute_path = abs_path($relative_path)

Slightly more portable, slightly more robust, and slightly more taint-resistant function to return the absolute path of a specified file or directory. The input file need not exist. If the input is already an absolute path and is not tainted, then the output of this function will not be tainted, either.

Ctime

Returns a millisecond-resolution timestamp for the current time, like 14:38:19.018; helpful for logging methods. If the Time::HiRes module is not available, the result will show 0 in the milliseconds place, like 14:38:19.000.

@match = filter \&condition, @list

Returns the elements of a list that satisfy some condition while removing those elements from the original list as a side effect. Like Perl's grep and map functions, each element of the list will be loaded into $_ before the code block is evaluated. The @list argument must be a named array.

Examples:

    @x = (1..10);
    @y = filter { $_ % 2 } @x;
    # result: @y => (1,3,5,7,9); @x => (0,2,4,6,8)

    # trivial passthru filter
    @x = @ARGV;
    @y = filter { 1 } @x;
    # result: @y => @ARGV; @x => ()

$bool = is_continue_signal($signal_name_or_number)

Returns true if the specified signal is generally used to resume a suspended process. See "is_stop_signal".

$bool = is_kill_signal($signal_name_or_number)

Returns true if the specified signal is generally used to terminate a process, for some vague definition of generally. See also "is_stop_signal" and "is_continue_signal".

$bool = is_number($scalar)

A ripoff of "looks_like_number" in Scalar::Util to tell if a scalar input is a number.

$bool = is_pipe($handle)

Returns true if, as far as the Forks::Super module can tell, the specified I/O handle is a pipe handle. See also "is_socket".

$bool = is_socket($handle)

Returns true if, as far as the Forks::Super module can tell, the specified I/O handle is a socket handle. See also "is_pipe".

$bool = is_stop_signal($signal_name_or_number)

Returns true if the specified signal is generally used to suspend a process. See "is_continue_signal".

isValidPid($pid)

Portable function call to check if the return value of "fork" in Forks::Super is a valid process id (On Windows, forked processes are pseudo-processes with negative process identifiers, so the conventional if ($pid > 0) ... check is not portable).

Returns 0 when a "fork" in Forks::Super call creates a "deferred" job (see "Deferred processes" in Forks::Super).

pause($delay)

A productive and interruption-resistant drop-in replacement for the builtin sleep function or Time::HiRes::sleep.

This function carries out "productive" tasks periodically while waiting for the timer to expire.

In programs that use Forks::Super, the default "productive" behavior is to check for completed background processes and to dispatch deferred jobs. On Windows systems that lack a proper framework for handling SIGCHLD framework, using this function in place of sleep is one of the best ways to make sure that completed and deferred processes receive the attention they need. You can override the default behavior by passing a code reference to the "set_productive_pause_code" function.

Since the "productive" code could take an arbitrarily long time to execute, the actual delay can be longer, and sometimes much longer, than the requested delay.

The return value of this function is the estimated number of seconds that the function actually waited.

$qualified_name = qualify_sub_name($unqualified_sub_name_or_code_ref)

Prepends a package qualifier from the current context, if necessary, from current execution context of a scalar subroutine name. Used when an unqualified subroutine name is passed in any Forks::Super function argument that expects a code reference.

    package Foo;
    sub do_something_in_background { ... }

    # invokes Forks::Super::Util::qualify_sub_name 
    $job = fork { sub => 'do_something_in_background' };
    print $job->{sub};   # ---> Foo::do_something_in_background

set_productive_pause_code($coderef)

Specifies the code that the "pause" method should run during down time. In most Forks::Super programs, the default will be to check if running processes have completed and to manage tasks in the job queue.

Can be called with an undef argument to disable productive code during "pause" calls.

$signal_name = signal_name($signal_number)

Returns the canonical name of a signal (e.g., TERM) that is associated with the given signal number (say, 15). See also "signal_number". Returns undef for a signal number that is out of the valid range for your system.

$signal_number = signal_number($signal_name)

Returns the number of a signal (say, 15) that is associated with the given signal name (say, TERM). Returns undef for an unrecognized signal name.

SEE ALSO

Forks::Super

AUTHOR

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

LICENSE AND COPYRIGHT

Copyright (c) 2009-2013, 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