update/fix comments.

use more proper local variable names.

4 files changed, 83 insertions, 51 deletions

diff --git a/fml/lib/FML/Error/Analyze.pm b/fml/lib/FML/Error/Analyze.pm
index 6a43dced..d92df1f7 100644
--- a/fml/lib/FML/Error/Analyze.pm
+++ b/fml/lib/FML/Error/Analyze.pm
@@ -4,7 +4,7 @@
 #   All rights reserved. This program is free software; you can
 #   redistribute it and/or modify it under the same terms as Perl itself.
 #
-# $FML: Analyze.pm,v 1.23 2003/08/23 07:24:44 fukachan Exp $
+# $FML: Analyze.pm,v 1.24 2003/10/15 01:03:31 fukachan Exp $
 #
 
 package FML::Error::Analyze;
@@ -23,6 +23,19 @@ FML::Error::Analyze - provide model specific analyzer routines.
 
 =head1 SYNOPSIS
 
+    use FML::Error::Cache;
+    my $cache = new FML::Error::Cache $curproc;
+    my $rdata = $cache->get_all_values_as_hash_ref();
+
+    # $rdata format = { 
+    #             key1 => [ value1, value2, ... ],
+    #             key2 => [ value1, value2, ... ],
+    #          }
+    use FML::Error::Analyze;
+    my $analyzer = new FML::Error::Analyze $curproc;
+    $analyzer->$evaluator_function($curproc, $rdata);
+
+
 =head1 DESCRIPTION
 
 =head1 METHODS
@@ -49,7 +62,7 @@ sub new
 
 =head2 summary()
 
-return summary of points of addresses as HASH_REF.
+return summary of address and points as HASH_REF.
 
     $summary = {
 	address1 => point,
@@ -69,7 +82,7 @@ return addresses to be removed.
 # Return Value: HASH_REF
 sub summary
 {
-    my ($self) = @_;
+    my ($self)   = @_;
     my $analyzer = $self->{ _analyzer };
 
     if (defined $analyzer) {
@@ -87,7 +100,7 @@ sub summary
 # Return Value: ARRAY_REF
 sub removal_address
 {
-    my ($self) = @_;
+    my ($self)   = @_;
     my $analyzer = $self->{ _analyzer };
 
     if (defined $analyzer) {
@@ -106,7 +119,7 @@ sub removal_address
 sub print
 {
     my ($self, $addr) = @_;
-    my $analyzer = $self->{ _analyzer };
+    my $analyzer      = $self->{ _analyzer };
 
     if (defined $analyzer) {
 	return $analyzer->print($addr);
@@ -124,12 +137,12 @@ C<FML::Command::$MODE::$command>.
 
 
 # Descriptions: run FML::Error::Analyze::XXX()
-#    Arguments: OBJ($self) OBJ($curproc) HASH_REF($anal_args)
+#    Arguments: OBJ($self) OBJ($curproc) HASH_REF($anal_data)
 # Side Effects: load appropriate module
 # Return Value: none
 sub AUTOLOAD
 {
-    my ($self, $curproc, $anal_args) = @_;
+    my ($self, $curproc, $anal_data) = @_;
 
     # we need to ignore DESTROY()
     return if $AUTOLOAD =~ /DESTROY/;
@@ -145,8 +158,8 @@ sub AUTOLOAD
     unless ($@) {
 	# run the actual process
 	if ($analyzer->can('process')) {
-	    $analyzer->process($curproc, $anal_args);
-	    $self->{ _analyzer } = $analyzer;
+	    $analyzer->process($curproc, $anal_data);
+	    $self->{ _analyzer } = $analyzer; # saved for further reference.
 	}
 	else {
 	    $curproc->logerror("${pkg} has no process method");
@@ -163,7 +176,7 @@ sub AUTOLOAD
 =head1 $data STRUCTURE
 
 C<$data> is passed to the error analyer function
-C<FML::Error::Analyze::${fp}> (as $anal_args in AUTOLOAD()).
+C<FML::Error::Analyze::${fp}> (as $anal_data in AUTOLOAD()).
 
 	 $data = {
 	    address => [
@@ -172,8 +185,8 @@ C<FML::Error::Analyze::${fp}> (as $anal_args in AUTOLOAD()).
 	    ]
 	 };
 
-where the error_info_* has error reasons (STR).  $fp parses it, count
-up.  FML::Error or FML::Error::Analyze can retrieve the result via
+where the error_info_* has error reasons (STR). $fp parses it, count
+up. FML::Error or FML::Error::Analyze can retrieve the result via
 summary() method.
 
 =head1 CODING STYLE
diff --git a/fml/lib/FML/Error/Analyze/histgram.pm b/fml/lib/FML/Error/Analyze/histgram.pm
index 1a704369..6a022091 100644
--- a/fml/lib/FML/Error/Analyze/histgram.pm
+++ b/fml/lib/FML/Error/Analyze/histgram.pm
@@ -4,7 +4,7 @@
 #   All rights reserved. This program is free software; you can
 #   redistribute it and/or modify it under the same terms as Perl itself.
 #
-# $FML: histgram.pm,v 1.4 2003/08/23 07:24:45 fukachan Exp $
+# $FML: histgram.pm,v 1.5 2003/10/15 01:03:31 fukachan Exp $
 #
 
 package FML::Error::Analyze::histgram;
@@ -46,7 +46,7 @@ sub new
 }
 
 
-# Descriptions: cost evaluator.
+# Descriptions: top level dipatcher to run cost evaluator.
 #    Arguments: OBJ($self) OBJ($curproc) HASH_REF($data)
 # Side Effects: none
 # Return Value: none
@@ -80,23 +80,31 @@ but sum up count as the delta.
 sub _histgram
 {
     my ($self, $curproc, $data) = @_;
-    my ($addr, $bufarray, $count, $i);
-    my ($time, $status, $reason);
+    my ($addr, $bufarray, $count, $i, $time, $status, $reason);
     my @removelist = ();
     my $summary    = {};
     my $config     = $curproc->config();
     my $limit      = $config->{ error_analyzer_simple_count_limit } || 14;
     my $daylimit   = $config->{ error_analyzer_day_limit } || 14;
-    my $now        = time;
-    my $day        = 24*3600;
-    my $threshold  = $day * $daylimit;
-
+    my $now        = time;                 # unix time (seconds). 
+    my $half_day   = 12   * 3600 ;         # 12 hours  (seconds).
+    my $one_day    = 24   * 3600 ;         # 24 hours  (seconds).
+    my $threshold  = $one_day * $daylimit; # how old   (seconds).
+
+    # $data format = { 
+    #             key1 => [ value1, value2, ... ],
+    #             key2 => [ value1, value2, ... ],
+    #          }
     while (($addr, $bufarray) = each %$data) {
 	$count = 0;
+
 	if (defined $bufarray) {
+	  BUF:
 	    for my $buf (@$bufarray) {
 		($time, $status, $reason) = split(/\s+/, $buf);
-		next if ((time - $time) > $threshold);
+
+		# ignore too old data.
+		next BUF if (($now - $time) > $threshold);
 
 		if ($buf =~ /status=5/i) {
 		    unless (defined $summary->{ $addr }) {
@@ -104,15 +112,15 @@ sub _histgram
 		    }
 
 		    # center of distribution function
-		    $i = int( (time - $time ) / (24*3600) );
+		    $i = int( ($now - $time ) / $one_day );
 		    $summary->{ $addr }->[ $i ] += 2;
 
 		    # +delta
-		    $i = int( (time - $time + 12*3600) / (24*3600) );
+		    $i = int( ($now - $time + $half_day) / $one_day );
 		    $summary->{ $addr }->[ $i ] += 1;
 
 		    # -delta
-		    $i = int( (time - $time - 12*3600) / (24*3600) );
+		    $i = int( ($now - $time - $half_day) / $one_day );
 		    $summary->{ $addr }->[ $i ] += 1 if $i >= 0;
 		}
 		elsif ($buf =~ /status=4/i) {
@@ -121,15 +129,15 @@ sub _histgram
 		    }
 
 		    # center of distribution function
-		    $i = int( (time - $time ) / (24*3600) );
+		    $i = int( ($now - $time ) / $one_day );
 		    $summary->{ $addr }->[ $i ] += 0.25;
 
 		    # +delta
-		    $i = int( (time - $time + 12*3600) / (24*3600) );
+		    $i = int( ($now - $time + $half_day) / $one_day );
 		    $summary->{ $addr }->[ $i ] += 0.25;
 
 		    # -delta
-		    $i = int( (time - $time - 12*3600) / (24*3600) );
+		    $i = int( ($now - $time - $half_day) / $one_day );
 		    $summary->{ $addr }->[ $i ] += 0.25 if $i >= 0;
 		}
 	    }
@@ -139,8 +147,8 @@ sub _histgram
     # debug info
     {
 	my $addr = '';
-	my $sum  = 0;
 	my $ra   = ();
+	my $sum  = 0;
 	while (($addr, $ra) = each %$summary) {
 	    $sum = 0;
 	    for my $v (@$ra) {
@@ -150,7 +158,7 @@ sub _histgram
 		}
 	    }
 
-	    my $array = __debug_printable_array($ra);
+	    my $array = _ra_to_str($ra);
 	    $curproc->log("summary: $addr sum=$sum ($array)");
 	    push(@removelist, $addr) if $sum >= $limit;
 	}
@@ -168,7 +176,7 @@ sub _histgram
 #    Arguments: ARRAY_REF($ra)
 # Side Effects: none
 # Return Value: STR
-sub __debug_printable_array
+sub _ra_to_str
 {
     my ($ra) = @_;
     my $s    = '';
@@ -206,7 +214,7 @@ sub removal_address
 }
 
 
-# Descriptions: print address and the summary
+# Descriptions: print summary for the specified address.
 #    Arguments: OBJ($self) STR($addr)
 # Side Effects: none
 # Return Value: none
@@ -216,17 +224,9 @@ sub print
     my $wh       = \*STDOUT;
     my $summary  = $self->summary();
     my $bufarray = $summary->{ $addr } || [];
-    my $x        = '';
-    my $y        = '';
-
-    for my $y (@$bufarray) {
-	$x .= defined $y ? $y : 0;
-	$x .= " ";
-    }
+    my $result   = _ra_to_str($bufarray);
 
-    $x =~ s/^\s*//;
-    $x =~ s/\s*$//;
-    printf $wh "%25s => (%s)\n", $addr, $x;
+    printf $wh "%25s => (%s)\n", $addr, $result;
 }
 
 
diff --git a/fml/lib/FML/Error/Analyze/simple_count.pm b/fml/lib/FML/Error/Analyze/simple_count.pm
index 55757b33..66e4c577 100644
--- a/fml/lib/FML/Error/Analyze/simple_count.pm
+++ b/fml/lib/FML/Error/Analyze/simple_count.pm
@@ -4,7 +4,7 @@
 #   All rights reserved. This program is free software; you can
 #   redistribute it and/or modify it under the same terms as Perl itself.
 #
-# $FML: simple_count.pm,v 1.3 2003/08/23 04:35:35 fukachan Exp $
+# $FML: simple_count.pm,v 1.4 2003/10/15 01:03:31 fukachan Exp $
 #
 
 package FML::Error::Analyze::simple_count;
@@ -18,7 +18,7 @@ my $debug = 1;
 
 =head1 NAME
 
-FML::Error::Analyze::simple_count - cost evaluator
+FML::Error::Analyze::simple_count - simple cost evaluator
 
 =head1 SYNOPSIS
 
@@ -46,6 +46,14 @@ sub new
 }
 
 
+=head2 process($curproc, $data)
+
+count up the number of error messsages if the status is [45]XX.
+The cost to sum up varies according to the status code.
+
+=cut
+
+
 # Descriptions: main dispatcher
 #    Arguments: OBJ($self) OBJ($curproc) HASH_REF($data)
 # Side Effects: none
@@ -75,10 +83,14 @@ sub _simple_count
     my $day        = 24*3600;
     my $threshold  = $day * $daylimit;
 
+    # $data format = { 
+    #             key1 => [ value1, value2, ... ],
+    #             key2 => [ value1, value2, ... ],
+    #          }
     while (($addr, $bufarray) = each %$data) {
 	$count = 0;
 
-	# count up the number of error messsages if the status is 5XX.
+	# count up the number of error messsages if the status is [45]XX.
 	if (defined $bufarray) {
 	  ELEMENT:
 	    for my $buf (@$bufarray) {
@@ -87,6 +99,7 @@ sub _simple_count
 		# ignore too old data.
 		next ELEMENT if (($now - $time) > $threshold);
 
+		# XXX-TODO: cost should be customizable.
 		if ($buf =~ /status=5/i) {
 		    $count += 1.0;
 		}
diff --git a/fml/lib/FML/Error/Cache.pm b/fml/lib/FML/Error/Cache.pm
index 0abab348..e93feea2 100644
--- a/fml/lib/FML/Error/Cache.pm
+++ b/fml/lib/FML/Error/Cache.pm
@@ -4,7 +4,7 @@
 #   All rights reserved. This program is free software; you can
 #   redistribute it and/or modify it under the same terms as Perl itself.
 #
-# $FML: Cache.pm,v 1.14 2003/08/29 15:34:03 fukachan Exp $
+# $FML: Cache.pm,v 1.15 2003/10/15 01:03:31 fukachan Exp $
 #
 
 package FML::Error::Cache;
@@ -40,6 +40,8 @@ where C<$bounce_info) follows:
 
 =head2 new()
 
+standard constructor.
+
 =cut
 
 
@@ -138,10 +140,12 @@ sub add
 	    $reason =~ s/\s+/_/g;
 	}
 	else {
-	    $curproc->logerror("FML::Error::Cache: add: not implemented \$argv type");
+	    my $s = "FML::Error::Cache: unknown type: \$argv";
+	    $curproc->logerror($s);
 	    return undef;
 	}
 
+	# XXX-TODO: validate $address ?
 	if ($address) {
 	    $db->{ $address } = "$unixtime status=$status reason=$reason";
 	}
@@ -177,6 +181,7 @@ sub delete
 
     my $db = $self->{ _db };
     if (defined $db) {
+	# XXX-TODO: validate $address ?
 	if ($address) {
 	    delete $db->{ $address };
 	}
@@ -208,10 +213,10 @@ following a set of key ($address) and value.
 # Descriptions: open the cache database for File::CacheDir.
 #    Arguments: OBJ($self)
 # Side Effects: none
-# Return Value: OBJ
+# Return Value: HASH_REF
 sub _open_cache
 {
-    my ($self) = @_;
+    my ($self)  = @_;
     my $curproc = $self->{ _curproc };
     my $config  = $curproc->config();
     my $type    = $config->{ error_analyzer_cache_type };
@@ -221,6 +226,7 @@ sub _open_cache
 
     use Tie::JournaledDir;
 
+    # XXX-TODO: use ? $type, $mode, $days
     # tie style
     my %db = ();
     tie %db, 'Tie::JournaledDir', { dir => $dir };
@@ -235,7 +241,7 @@ sub _open_cache
 sub _close_cache
 {
     my ($self) = @_;
-    my $db = $self->{ _db };
+    my $db     = $self->{ _db };
 
     if (defined $db) {
 	untie %$db;
@@ -277,10 +283,10 @@ sub get_primary_keys
 # Return Value: HASH_REF
 sub get_all_values_as_hash_ref
 {
-    my ($self) = @_;
+    my ($self)  = @_;
     my $curproc = $self->{ _curproc };
     my $config  = $curproc->config();
-    my $dir     = $config->{ error_analyzer_cache_dir  };
+    my $dir     = $config->{ error_analyzer_cache_dir };
 
     use Tie::JournaledDir;
     my $obj = new Tie::JournaledDir { dir => $dir };