Documentation—clusterpunch.pm
NAME
clusterpunch.pm - API for the Clusterpunch system
SYNOPSIS
use clusterpunch;
@filenames = ConfigFiles($mycfgfile1,$mycfgfile2); %CONFIG = LoadConfig(@filenames);
%RESPONSE = ClusterPunch(broadcast=>"10.1.2.255",port=>8095,
command=>"benchmem;benchio(60000,2);mhz;load(1)",
timeout=>15);
@besthostnames = ProcessResponse(response=>\%RESPONSE,config=>\%CONFIG,
sortstr=>"b_all",
getbestnodes=>10);
# print formatted table
ProcessResponse(response=>\%RESPONSE,
config=>\%CONFIG,
sortstr=>"b_all");
DESCRIPTION
This module provides an API for the Clusterpunch distributed mini-benchmark system. The functions provide a way to (a) load configuration files (b) communiate with the clusterpunchservers on your network and (c) process the results. Each function is described in detail below.
USAGE
use clusterpunch;
Generate a list of configuration files found on the system. You can optionally pass any of your files to be appended to the list.
@filenames = ConfigFiles($mycfgfile1,$mycfgfile2);
Load the configuration files into a hash. Parameters defined in files parsed first may be overwritten by later files.
%CONFIG = LoadConfig(@filenames);
Send a punch command to all listeners. You can use a broadcast address, like shown below, or a host address.
%RESPONSE = ClusterPunch(broadcast=>"10.1.2.255",
port=>8095,
command=>"benchmem;benchio(60000,2);mhz;load(1)",
timeout=>15);
Retrieve the top N ranking nodes (e.g. 10) from the responses, sorting appropriately on the value of the b_all statistic.
@besthostnames = ProcessResponse(response=>\%RESPONSE,
config=>\%CONFIG,
sortstr=>"b_all",
getbestnodes=>10);
Print out a table with all results, sorted by the value of the b_all result (cumulative benchmark).
ProcessResponse(response=>\%RESPONSE,
config=>\%CONFIG,
sortstr=>"b_all");
DATA STRUCTURES
- Punch Command
-
The punch command keyed by 'command' in the call to ClusterPunch must be of the format
name1;name2(arg1,arg2);...;nameM
where nameN is the name of the Nth punch (e.g. name1=benchmem), and argN is any argument that the punch understands (e.g.
benchio(60000,2)).The names must be the same as defined in the punch blocks in the configuration file, clusterpunch.conf'. - Responses
-
Each responding node sends back a hash of punch return values, keyed by the statistic of the punch. For example,
$noderesponse = ('b_mem' => '0.808106', 'load' => '2.08', 'live' => 1, 'b_io' => '1.382093', 'b_all' => '2.190199', 'host' => '8of3', 'mhz' => 2522);These responses are grouped together in one large response hash,
%RESPONSE = (node1name=>$node1response, node2name=>$node2response,...);
METHODS
- ConfigFiles()
-
This function returns a list of configuration files which are found on the system, along with any that are passed as arguments. By default, the system expects that configuration files exist in one, or more, of the following locations:
~/.clusterpunch ../etc/clusterpunch.conf /usr/local/etc/clusterpunch.conf /etc/clusterpunch.conf
If you pass any arguments to
ConfigFiles()then these filenames will be appended to the list above andConfigFiles()will return any files that are found and are readable. For example, if ~/.clusterpunch and /etc/clusterpunch.conf existed then in the call@files = ConfigFiles("/home/martink/special.conf");the value of files would be (``~/clusterpunch'', ``/etc/clusterpunch.conf'', ``/home/martink/special.conf'').
- LoadConfig(@files) {
-
Once you have located the available configuration files with
ConfigFiles(),LoadConfig is used to parse the files and create a configuration hash.%CONFIG = LoadConfig(@files);
The configuration will be loaded from the files in the order that they appear in the input list. Any parameters defined in a file can be overwritten by the definitions in files parsed afterwords. Thus, you can create a network-wide configuration in /usr/local/etc/clusterpunch.conf, create host-specific configuration in /etc/clusterpunch.conf and then override any of these definitions using your own files.
- ClusterPunch()
-
This is the main communication driver for the system.
ClusterPunch()expects the following inputs passed as a hash, shown below with sample values%RESPONSE = ClusterPunch(broadcast=>"10.1.2.255", port=>"8095", command=>"benchmem;benchio(60000,2);mhz;load(1)", timeout=>15);The broadcast and port specify the UDP broadcast address and port to use. The clusterpunchserver must be configured to listen to the same port. If the broadcast address ends in 255, then a true UDP broadcast is used. If the address ends in any other value (e.g. 10.1.2.80) then it is assumed that you want to talk to a specific host and broadcast is not used.
The command parameter specifies the string command to send to the clusterpunchservers. It should be of the format
name1;name2;name3(arg1);name4;(arg1,arg2,...);name5
where nameN is the name of the punch, as defined in the configuration file, and argN are any arguments that the punch code understands.
The timeout specifies the number of seconds to wait for a response from the clusterpunchservers.
The returned
%RESPONSEis a hash in which entries are keyed by the responding hosts\' name and the value is the data structure returned by that host.%RESPONSE = ( '8of3' => { 'b_mem' => '0.808106', 'load' => '2.08', 'live' => 1, 'b_io' => '1.382093', 'b_all' => '2.190199', 'host' => '8of3', 'mhz' => 2522 }, '4of7' => { 'b_mem' => '0.79169', 'load' => '2.08', 'live' => 1, 'b_io' => '1.297371', 'b_all' => '2.089061', 'host' => '4of7', 'mhz' => 2792 }, ... ) - ProcessResponse()
-
This function provides some canned facilities for sorting through and formatting the response hash returned by
ClusterPunch().To dump a formatted table to STDOUT,ProcessResponse(config=>\%CONFIG,response=>\%RESPONSE,sortstr=>"b_all");
The STDOUT table would look something like
host b_all b_io b_mem live load mhz 5of0 1.495 0.588 0.906 1 2.0 1992 7of0 1.501 0.590 0.912 1 2.0 1992 6of0 1.502 0.594 0.908 1 2.1 1992 4of0 1.505 0.599 0.906 1 2.0 1992 0of1 1.508 0.599 0.909 1 0.0 1992 .... 3of4 5.052 4.046 1.006 1 1.4 2522 4of4 5.771 4.651 1.119 1 3.2 2522 TOTAL 138.772 87.102 51.670 58 79.0 138416It is important that
ProcessResponse()has access to the%CONFIGhash returned byLoadConfig()because this hash contains information about how to sort the punch results.If you would like to receive the names of the top N nodes using a particular punch value,
@bestnodes = ProcessResponse(config=>\%CONFIG,response=>\%RESPONSE, sortstr=>"b_all",getbestnodes=>$N);Again, the value in
ProcessResponse()is that the results are sorted in the way defined in the particular punch, or statistic. In otherwords, we have specified that we want the nodes ranked by ``b_all'', but did not need to specify whether the sort is ascending/descending and numerical/asciibetical. These definitions are found in the configuration file.For example, in the examples below we don\'t need to specify anything other than the sort string (sortstr) and the sorts will be done in the right way.
# numeric, descending sort - larger mhz values are better @bestnodes = ProcessResponse(config=>\%CONFIG,response=>\%RESPONSE, sortstr=>"mhz",getbestnodes=>$N);# numeric, ascending sort - smaller benchmark times are better @bestnodes = ProcessResponse(config=>\%CONFIG,response=>\%RESPONSE, sortstr=>"b_all",getbestnodes=>$N);
SEE ALSO
Daemons
clusterpunchserver, clusterpunch.start, clusterpunch.shutdown
API
clusterpunch.pm
Utilities
benchdriver, clusterbench, clusterlogin, clusternodecount, clustersnapshot
CHANGES
AUTHOR
Martin Krzywinski (martink@bcgsc.ca) January 2003
$Id: clusterpunch.pm,v 1.7 2003/02/03 19:07:59 martink Exp $