[GNUnet-SVN] r15128 - in gauger: . web

[gnunet]

Author: bartpolot
Date: 2011-04-29 20:51:57 +0200 (Fri, 29 Apr 2011)
New Revision: 15128

Modified:
   gauger/gauger-cli.py
   gauger/web/io.php
Log:
Documented all functions


Modified: gauger/gauger-cli.py
===================================================================
--- gauger/gauger-cli.py        2011-04-29 17:04:00 UTC (rev 15127)
+++ gauger/gauger-cli.py        2011-04-29 18:51:57 UTC (rev 15128)
@@ -76,7 +76,7 @@
   except:
     print >> sys.stderr, "please put 'remotehost username password' in 
gauger-cli.conf"
     exit(1)
-    
+
 if(args.check):
     exit(0)
 else:
@@ -93,14 +93,14 @@
   print >> sys.stderr, "please make sure to be in a svn respoitory and have 
svn installed"
   print >> sys.stderr, "or specify an identifier at runtime with the --id 
option"
   exit(1)
-  
+
 if (int(revision) == 0):
   print >> sys.stderr, "revision number cannot be 0, please try again with a 
valid number"
   exit(1)
 
 if(args.unit):
     args.name = args.name + "___" + args.unit
-    
+
 if(args.category):
     args.name = args.category + ":::" + args.name
 

Modified: gauger/web/io.php
===================================================================
--- gauger/web/io.php   2011-04-29 17:04:00 UTC (rev 15127)
+++ gauger/web/io.php   2011-04-29 18:51:57 UTC (rev 15128)
@@ -139,6 +139,17 @@
     return $lm ? $lm : 1;
 }
 
+/**
+ * explore: traverse all data direcories and list all files
+ * populates the following global arrays:
+ * $hosts     Contains a list of arrays indexed per hostname.
+ *            Each array contains the metrics available for that host
+ * $metrics   Contains all the metrics globally for any host, The metrics are
+ *            indexed by filename and having the simplified name of the 
counter.
+ * $mertics_c Contains all the metrics grouped in arrays by category.
+ *            Indexed by category name.there is an array which is contains
+ *            the simplified name of the counter indexed by filename.
+ */
 function explore() {
     global $DATADIR;
     global $hosts;
@@ -178,6 +189,13 @@
     $d->close();
 }
 
+/**
+ * line beginning: Puts the file cursor at the beginning of the current line.
+ *                 In case the cursor is already at the beginning, no change is
+ *                 made.
+ * @param $f file handler
+ * @return new position of the cursor inside the file
+ */
 function line_beginning($f) {
     $pos = ftell($f);
     if($pos < 2) {
@@ -192,12 +210,25 @@
     return ftell($f);
 }
 
+/**
+ * previous_line: Situates the file cursor at the beginning of the line. In 
case
+ *                the cursor is already at the beginning of a line, it goes 
back
+ *                to the beginning of the next one. (most usual case)
+ * @param $f the file handle
+ * @return new position of the cursor inside the file
+ */
 function previous_line($f) {
     if(ftell($f) == 0) return 0;
     fseek($f, -1, SEEK_CUR);
     return line_beginning($f);
 }
 
+/**
+ * fpeek: Reads the current line and situates the cursor back at the beginning
+ *        of it.
+ * @param $f the handle to the file
+ * @return the line read at the position of the cursor
+ */
 function fpeek($f) {
     line_beginning($f);
     $b = fgets($f, 512);
@@ -205,10 +236,24 @@
     return $b;
 }
 
+/**
+ * get_line: Reads the current line and situates the cursor back at the
+ *           beginning of it. Returns the resulting as an array [rev, value]
+ * @param $f the handle to the file
+ * @return array containing the revision and the value on the line
+ */
 function get_line($f) {
     return explode(' ', fpeek($f));
 }
 
+/**
+ * check_permissions: checks that the given path is of the correct type and the
+ *                    script has write permissions for it. It creates it
+ *                    otherwise, if possible. If an error is encountered, it
+ *                    does not return, just shows a message and dies.
+ * @param $path a string containing the path to check
+ * @param $type a string containing either "file" or "dir", "file" if omitted
+ */
 function check_permissions($path, $type = 'file') {
     if(file_exists($path)) {
         $f = 'is_'.$type;
@@ -230,6 +275,13 @@
     }
 }
 
+/**
+ * find_position: finds the position in a file where a given index should go
+ * @param $f    the handler to the file
+ * @param $size the size of the file
+ * @param $rev  the revision number / index of the data looked for
+ * @return the position in the file where the data could be
+ */
 function find_position($f, $size, $rev) {
     $pos = $gap = (int)($size/2);
     $lastpos = 0;
@@ -262,6 +314,13 @@
     return ftell($f);
 }
 
+/**
+ * add_data_to_file: adds the given data to the raw file at filename
+ * @param $filename path to the file where to add the data
+ * @param $rev revision/index of the data
+ * @param $data value itself
+ * @return position at which the data was added
+ */
 function add_data_to_file($filename, $rev, $data) {
     $f = @fopen("$filename", 'r+');
     if ($f === false) return false;
@@ -280,6 +339,14 @@
     return $pos;
 }
 
+/**
+ * recalculate_data: reads the relevant lines from the file of raw data and
+ *                   calculates the average and standard deviation
+ * @param $filename path to the file where read the data from
+ * @param $rev revision/index of the data
+ * @param $pos position where the last data was stored
+ * @return size 2 array with the average of the data and the standard deviation
+ */
 function recalculate_data($filename, $rev, $pos) {
     $f = @fopen("$filename", 'r+');
     if ($f === false) return false;
@@ -314,6 +381,15 @@
     return array($avg, $stddev);
 }
 
+/**
+ * write_data_to_summary: writes the average and standard deviation of the data
+ *                        to the summary file
+ * @param $filename path to the file with raw data
+ * @param $rev revision/index of the data
+ * @param $data size 2 array with the average of the data and
+ *              the standard deviation
+ * @return true on success, false of failure
+ */
 function write_data_to_summary($filename, $rev, $data) {
     $f = @fopen("$filename.dat", 'r+');
     if ($f === false) return false;
@@ -339,7 +415,17 @@
     return true;
 }
 
-
+/**
+ * add_data_to_host: High level function that appends data to the metric on the
+ *                   host given as parameters and updates the summary
+ *                   information used for plotting.
+ *                   Does not return, informs the client about the success or
+ *                   failure of the operation.
+ * @param $h hostname
+ * @param $g graph / metric where to add the data
+ * @param $rev revision/index of the data
+ * @param $value data itself
+ */
 function add_data_to_host($h, $g, $rev, $value) {
     global $CONF;
     $datadir = preg_replace('/(.*)\/.*/', '\1', $_SERVER['SCRIPT_FILENAME']);