Guard-Stats

 view release on metacpan or  search on metacpan

README  view on Meta::CPAN

    # in diagnostic procedures started via external event
    my $data = $stat->get_stat;
    warn "$data->{running} instances still running";

METER TABLE

Statistics show numbers of guards for which end()/DESTROY() were called
in various combinations.

    DESTROY: *        0        1
    end:*    total+   alive    dead
    end:0    ?        running  broken+
    end:1    done+    zombie   complete+

A "+" marks values directly measured by Guard::Stats. They all are monotonous.
Other counterss are derived from these.

TIME AND LEVELS

The on_level( [-] $n, CODEFER ) method allows to perform certain actions
upon guard count changes. (-$n means "count decreased to $n").

lib/Guard/Stats.pm  view on Meta::CPAN

    my $callback = sub {
        $guard->finish("taken route 1");
        # now do useful stuff
    };
    # ... do whatever we need and call $callback eventually

    # in diagnostic procedures triggered by an external event
    my $data = $stat->get_stat;
    warn "$data->{running} callbacks still waiting to be executed";

Of course, alive/dead counts of any objects (not only sub refs) may be
monitored in a similar way.

=head1 DESCRIPTION

A guard is a special object that does something useful in destructor, typically
freeing a resource or lock. These guards however don't free anything. Instead,
they call home to keep their master (YOU) informed.

=head2 The classes

lib/Guard/Stats.pm  view on Meta::CPAN

Its public methods are guard() and various statistic getters.

Guard::Stats::Instance is the guard. When it is DESTROYed, it signals the stat
object which created it.

Its public methods are end( [$result] ) and is_done().

=head2 The counters

When a guard is created, the C<total> counter increases. When it's detroyed,
C<dead> counter increases. C<alive> = C<total> - C<dead> is the number of
guards that still exist.

Additionally, guards implement a C<end()> method which indicates that
the action associates with the guard is complete. Typically a guard should
be destroyed soon afterwards. The guards for which neither DESTROY nor
end were called are considered C<running> (this is used in C<on_level>).

The full matrix or DESTROY()/end() combinations is as follows:

    DESTROY: *        0        1
    end:*    total+   alive    dead
    end:0    ?        running  broken+
    end:1    done+    zombie   complete+

A "+" marks values directly measured by Guard::Stats. They all happen to be
monotonous. Other statistics are derived from these.

Note that counter showing end() NOT called regardless of DESTROY() does not
have a meaningful name (yet?).

=head2 Running count callback

lib/Guard/Stats.pm  view on Meta::CPAN

=head1 Statistics

The following getters represent numbers of guards in respective states:

=over

=item * total() - all guards ever created;

=item * dead() - DESTROY was called;

=item * alive() - DESTROY was NOT called;

=item * done() - end() was called;

=item * complete() - both end() and DESTROY were called;

=item * zombie() - end() was called, but not DESTROY;

=item * running() - neither end() nor DESTROY called;

=item * broken() - number of guards for which DESTROY was called,

lib/Guard/Stats.pm  view on Meta::CPAN

	my $name = $_;
	my $code = sub { return shift->{$name} };
	no strict 'refs'; ## no critic
	*$name = $code;
};

sub running {
	my __PACKAGE__ $self = shift;
	return $self->{total} - $self->{done} - $self->{broken};
};
sub alive {
	my __PACKAGE__ $self = shift;
	return $self->{total} - $self->{complete} - $self->{broken};
};
sub dead {
	my __PACKAGE__ $self = shift;
	return $self->{complete} + $self->{broken};
};
sub zombie {
	my __PACKAGE__ $self = shift;
	return $self->{done} - $self->{complete};

lib/Guard/Stats.pm  view on Meta::CPAN

Get all statistics as a single hashref.

=cut

sub get_stat {
	my __PACKAGE__ $self = shift;
	my %ret;
	$ret{$_} = $self->{$_} for @values;
	$ret{dead} = $ret{complete} + $ret{broken};
	$ret{zombie} = $ret{done} - $ret{complete};
	$ret{alive} = $ret{total} - $ret{dead};
	$ret{running} = $ret{alive} - $ret{zombie};

	return \%ret;
};

=head2 get_stat_result

Provide statistics on agruments provided to end() method.

=cut

t/10-stat-guard.t  view on Meta::CPAN

is ($neg, 0, "on_level(-1) not called yet");

# sleep 0.001;
ok (!$g->is_done, "is_done = 0");
$g->end;
ok ($g->is_done, "is_done = 1");

note Dumper($G->get_stat);
nonnegative($G->get_stat);

is ($G->alive, 2, "2 items alive");
is ($G->done, 1, "1 done");

is ($neg, 1, "on_level(-1) called once");

is ($G->zombie, 1, "1 zombie");
undef $g;
is ($G->zombie, 0, "1 zombie gone");

# note Dumper($G->get_time_stat);
nonnegative($G->get_stat);
is ($G->alive, 1, "1 item alive");
is ($neg, 1, "on_level(-1) called once");

undef $g2;
# note Dumper($G->get_time_stat);
is ($G->alive, 0, "none alive");
is ($G->done, 1, "1 done (still)");
is ($neg, 1, "on_level(-1) called once");

note Dumper($G->get_stat);
nonnegative($G->get_stat);

my $results = $G->get_stat_result;
is (ref $results, 'HASH', "Fetched results");
is_deeply($results, { ""=>1 }, "results as expected");