/ 
Alive-0.110
/ Alive

NAME

Alive - Ticker to show perl is still alive and working during long time runnings

VERSION

This documentation refers to version 0.100 of Alive

SYNOPSIS

Shortest

use Alive qw(tack);

foreach my $i (1..10000) {
    tack;
}

or fastest

use Alive qw(tack);

my $tick = tack;

foreach my $i (1..10000) {
    $tick->();
}

or individual

my $tick = Alive::create(
    -smaller      => 10,
    -bigger       => 100,
    -newline      => 500,
    -smaller_char => '+',
    -bigger_char  => '#',
    -name         => 'M ##',
);

foreach my $i (1..100000) {
    $tick->();
}

DESCRIPTION

Alive does inform the user that perl job or script is still running by printing to console.

The following script

$| = 1;
use Alive qw(:all);

foreach my $i (1..2000) {
    tack;
}

prints out this

.........,.........,.........,.........,.........
500 .........,.........,.........,.........,.........
1000 .........,.........,.........,.........,.........
1500 .........,.........,.........,.........,.........
2000

Methods

new() does not exist

There is no new(), use create() instead. Reason is, that there are no instances of Alive that could be created.

create()

Alive::create() creates a tick closure (a reference to a anonymous sub) for comfort and fast calling without method name search and without args. The counter is inside.

Using instances is much more work to implement, slower and not so flexible.

Parameters

# name        # default: description
-smaller      #  1: print every $smaller * $factor call $smaller_char 
-bigger       # 10: print every $bigger  * $factor call $bigger_char 
-newline      # 50: print every $newline * $factor call "\n$name$$counter_ref"
-factor       # 10:
-smaller_char # '.'
-bigger_char  # ','
-name         # '': prepend every new line with it
-counter_ref  # reference to counter that should be used
-action       # action will be called by every call of tack; or $tick->();

setup()

Setup create the default ticker tack with same arguments as in create, except that

# -counter_ref => ignored

will be ignored.

tack or $tick->()

$tick->() prints out a '.' every 10th call (default), a ',' every 100th call (default) and starts a new line with number of calls done printed every 500th call (default).

tacks()

returns the value of the counter used by tack.

get_tack_counter()

returns a reference to the counter variable used by tack for fast access.

Running Modes

There are 3 running modes that can be selected:

Alive::on();        # default
Alive::silent();
Alive::all_off();

on()

Call of

$tick->(); or tack;

prints out what is configured. This is the default.

silent()

Call of

$tick->(); tack;

prints out nothing, but does the counting.

all_off()

If you need speed up, use

Alive::all_off();

Now nothing is printed or counted by all ticks. Selecting this mode gives you maximum speed without removing $tick->() calls.

my $tick = Alive::create();

Alive::all_off();

my $tick_never = Alive::create();

call of $tick->(); prints out nothing and does not count.

$tick_never has an empty sub which is same as

my $tick_never = sub {};

This $tick_never will also not print out anything, if

Alive::on();

is called to enable ticking.

Using multiple ticks same time

You can use multiple ticks same time, like in the following example. tick1 ticks all fetched rows and tick2 only those, which are selected by given filter. So you can see, if database select is still running or halted. But start ticking not before more than 40000 rows processed. So don't log out for small selections.

use Alive;

# Ticks all fetched rows
my $tick1 = Alive::create(
    -factor => 100,
    -name   => '   S',
);

my $matches = 0;

# To tick rows selected by filter
my $tick2 = Alive::create(
    -factor       => 10,
    -smaller_char => '+',
    -bigger_char  => '#',
    -name         => 'M ##',
    -counter_ref  => \$matches,
);

Alive::silent();

my @filtered_rows;

foreach my $i (1..100000) {
    my $row = $sql->fetch_row();
    $tick1->();
    
    if ($filter->($row)) {
        push (@filtered_rows, $row);
        $tick2->();
    }
    
    Alive::on() if $i == 40000;
}

say qq();
say "$matches rows matched to filter.";

It will print out something like:

.....#....,.........,........+.,.......+..,.........+
   S 45000 .........+,......+...,.....+....,.......+..,.....+....
   S 50000 .....+....,........
M ## 500 .,......+...,...+......,.....+....
   S 55000 +.........,..+.......,.........,+.........,+.........
   S 60000 .+........,+.........,#.......+..,......+...,..+.......
   S 65000 .........,+.......+..,........+.,....+.....,.+........
   S 70000 .......+..,......#...,........+.,........+.,.........
   S 75000 ..+.......,......+...,....+.....,..+.......,.....+....
   S 80000 ....+.....,.........+,.........,........#.,.......+..
   S 85000 ..+.......,+........+.,.........+,........+.,.........
   S 90000 .......+..,......+...,......+...,...#......,....+.....
   S 95000 +.........,..+.....+..,.........,+.........,.+........+
   S 100000 
987 rows matched to filter.

SEE ALSO

LICENSE AND COPYRIGHT

Copyright (c) 2015 by Ralf Peine, Germany. All rights reserved.

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

DISCLAIMER OF WARRANTY

This library is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.