SETI::Stats - gather local and remote SETI@home stats and manipulate them
use SETI::Stats; $s = new SETI::Stats ( rsh => "/semi-free/bin/ssh -l ernie", host => "bert", dir => "/seti" ); $s->visit; print $s->user_info("email_addr"); print $s->bar . "\n"; $t = new SETI::Stats ( dir => "/martin/seti", save => "p" ); while (1) { $t->visit; print $t->dump . "\n\n"; sleep(60); }
This Perl class provides an object oriented API which lets you gather SETI@home stats from one or more machines and gives you a programmatic way of getting access to them. It can cope with multiple SETI@home clients which share a directory hierarchy accessible to the machine it is run on, clients which each have their own private filespace (using rsh, ssh or equivalent) and even works for boxes running Windows NT.
SETI::Stats borrows from Jan Rocho's perlseti.pl, but differs in several ways - this is a module devoted to stats gathering rather than a general purpose control program, it can be used to monitor remote machines without even requiring Perl to be installed on them, and it provides a generic framework for access to (both local and remote) SETI@home client stats. It could also be extended to cover stats gathering from the SETI@home WWW server, though this may be better done in a separate module to avoid code bloat.
Each SETI::Stats object supports the following methods:
Create a new SETI::Stats object. The following parameters are supported:
This is the (local or remote) directory where SETI::Stats will look for the SETI@home client's stats files. It defaults to /home/seti.
When gathering stats remotely, this is the name of the host to contact. It will also be used as part of the name of SETI::Stats' own state file - see below for more info on this.
The command (rsh or equivalent) which will be used to contact the remote host when gathering stats over the Internet. If you need to specify a user name or other parameters, you can add them here, e.g.
rsh => "/semi-free/bin/ssh -l ernie"
This defaults to ssh.
The filename (absolute or relative) prefix of the local file to store SETI::Stats' state info in. This defaults to perlseti_data. See below for more information on state file naming.
The radio telescope data source for the SETI@home client. By default this is set to the Arecibo Radio Observatory, which is currently the only source of data for the SETI@home experiment.
Note that none of these parameters is mandatory. In particular, you don't have to store state info between polling clients - unless you want to use the dump method. The visit method will store it for you, however!
This method polls the SETI@home client being monitored by this SETI::Stats object for a given section of its stats. It takes the following parameters:
This indicates that the poll invocation is of the local checkpoint file maintained by SETI::Stats rather than a (possibly remote) state file maintained by the SETI@home client itself. It's set automatically by the visit method when updating the local checkpoint file.
This is the section name to poll for, corresponding to the file section.sah in the SETI@home working directory on the client machine.
This method is normally used internally by the visit method.
This method populates the internal data structures used by SETI::Stats for this section of the stats. It takes the following parameters:
An array of results, in the format attribute=value, with one attribute/value pair per entry - e.g. prog=0.487688
The section name of the stats to populate, e.g. work_unit.
This method saves SETI::Stats' current state info to a file on the local machine (even when monitoring a remote one). The file name is determined by the values of the dir and save parameters when the object was created, e.g. with a dir of /seti and a save of perlseti_state, the file created would be /seti/perlseti_state.txt when the local host was being monitored.
In the case of a remote client being monitored, the host name is appended to dir and save, prefixed by an underscore, e.g. for the client machine bert, the file would be /seti/perlseti_state_bert.txt. Note that the value of save no longer needs to contain the string perlseti (as was the case in SETI::Stats 1.00 and 1.01) for this feature to work properly.
You don't have to checkpoint, but be aware that this info is used by the dump method.
This method is the one you would normally call when polling a given SETI@home client for its stats. It in turn calls the poll method for each of the result_header, state, user_info, version and work_unit stats files and populates the SETI::Stats object's internal data structures with the contents of these files.
These are then accessible through the result_header, state, user_info, version and work_unit methods.
visit also calls the checkpoint and poll methods, which store SETI::Stats' state information and populates the internal data structure used by the perlseti_data method.
Access methods:
Returns a progress bar of '#' characters, representing the percentage of the work unit which has been analysed so far - on a scale of 0 to 80 characters, where 80 indicates that the work unit is complete.
Returns a SETI stats info 'screen' in the style of perlseti.pl, based on the last polled values for this SET@home client.
The method returns the value of the nominated parameter in the perlseti_data section of the client's stats. This section is unusual in that it is collected by SETI::Stats rather than the SETI@home client itself.
This method returns the value of the nominated parameter in the result_header section of the client's stats.
This method returns the value of the nominated parameter in the state section of the client's stats.
This method returns the value of the nominated parameter in the user_info section of the client's stats.
This method returns the value of the nominated parameter in the version section of the client's stats.
This method returns the value of the nominated parameter in the work_unit section of the client's stats.
Examples of the access methods in use can be found above in the SYNOPSIS section of this manpage.
This is still fairly new stuff, so probably contains much which is apocryphal, or just plain wrong :-)
If the object existed already we should probably take care to overwrite or remove old stats in a section when doing an update, or we could end up with the situation that some stats are current but others aren't.
Return codes should be documented.
There should be a test module.
Debugging options would be useful!
Copyright (c) 1999, Martin Hamilton <martinh@gnu.org>. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
Martin Hamilton <martinh@gnu.org>
To install SETI::Stats, copy and paste the appropriate command in to your terminal.
cpanm
cpanm SETI::Stats
CPAN shell
perl -MCPAN -e shell install SETI::Stats
For more information on module installation, please visit the detailed CPAN module installation guide.