NAME

Util.pm - Module containing various convenience functions used by CIToolkit


MODULE

base


SYNOPSIS

        use Util;
        $net_address = net("192.168.254.2", "255.255.255.0");
        my $slave = "some_resolvable_node";
        my $command = "ls -l";
        $return = command_slave($slave, $command);
        my $sub_ref = sub { print "In sub args = @_\n"; };
        my $arg1 = "hello";
        my $arg2 = "world";
        background($sub_ref, $arg1, $arg2);
        background_pipe($sub_ref, $arg1, $arg2);
        my $time = 10;
        waiter($sub_ref, $time);
        my ($scalar_address, $scalar_mask) = 
            parse_net_spec("192.168.254.2-255.255.255.0");
        my ($addr_name) = primary_interface($dev_obj);
        my (@unique_items) = eliminate_dups(@list);
        my (@unique_objects) = eliminate_obj_dups(@list_of_objects);
        my ($device_list) = devs_in_list(@list);
        
        my ($node_list) = nodes_in_list(@list);
        my ($non_leaders) = non_leaders_in_list(@list);
        my ($leaders) = leaders_in_list(@list);
        
        my (@ret_list) = process_list($dev_type, @list);
        #
        # pass any number of references to lists to union_n_intersection
        #
        my (@union, @intersection) = 
            union_n_intersection(\@list1, \@list2);
        my (@union, @intersection) = 
            union_n_intersection(\@list1, \@list2, \@list3);
        my %leader_hash = group_with_leader(@dev_list);
        my $key_string = getalpha($count);


DESCRIPTION

Utility functions used by layered tools. This module contains convenience functions that are, and can be leveraged by the layered tools, and other modules.

Functions

net($host-address, $netmask);
Returns a network address, given a host address and the netmask.

command_slave($slave, $command [,$command [, ...] ]);
Executes a command or commands (with a ``system'' call) on the specified host, via an ``rsh'' command. Host should be resolvable. Returns whatever the ``system'' call generates. Frequently used with the background function.

background($subroutine_reference [, $arg1 [, ...] ]);
background forks a child process and executes sub-routine passing the arguments to the sub-routine that it was passed. Frequently the sub-routine that is passed is command_slave background also keeps track of the children's pid's in a hash referenced by the sub-routine ref that is passed. Use in conjunction with the waiter sub-routine found in this module.

background_pipe($subroutine_reference, $fd [, $arg1 [, ...] ]);
background_pipe uses a forking open to spawn a child process and gathers the output in a file descriptor variable ($fd), which can then be read from in main. Like the background command, it executes the sub-routine ($subroute_reference) in turn passing along the arguments to the sub-routine that it received. background_pipe also keeps track of the children's pid's in a hash referenced by the sub-routine ref that is passed. Use in conjunction with the waiter sub-routine found in this module.

waiter($subroutine_reference [, $time]);
waiter waits on the pid's stored in the hash table created in the background sub-routine, referenced by the $subroutine_reference passed in. There could be one or more pid's in the hash entry. $time id optional, but if passed waiter will only wait $time seconds for all of the entries in the $subroutine_reference hash entry. A value of 0 for $time will tell waiter to wait forever.

parse_net_spec($network_spec);
parse_net_spec will given an address and a mask separated by a ``-'' return the address and netmask given in scalar form, generally to be used for ease of manipulation.

primary_interface($device_object);
primary_interface will return the name of the interface that is marked with the attribute is_primary if a primary interface is specified for the object. If no primary interface is defined function will return undef.

eliminate_obj_dups(@list);
eliminate__obj_dups will surprisingly remove the duplicate objects from a supplied list and return a list of unique objects.

eliminate_dups(@list);
eliminate_dups will surprisingly remove the duplicates from a supplied list and return a list of unique items.

_in_list($class_type, $role, @list);
_in_list is a function intended to be private for Util.pm. The function operates on lists if devices and or collections. In the case of a collection the function will operate recursively on the collection. The fuction will return a list of devices that match the $class_type specified, and optionally the $role. If the $role is not ``undef'' both the $class_type and $role must be match for the device. $class_type should be a valid class as in Device::Node::Alpha::DS10.

devs_in_list
devs_in_list uses the private function _in_list to return all of the entries in the input list that are of type Device. This will include anything in the Device hierarchy like Device::Node etc. devs_in_list passes the type qw(Device) and role undef to _in_list along with the list provided to devs_in_list

nodes_in_list
nodes_in_list uses the private function _in_list to return all of the entries in the input list that are of type Device::Node. This will include anything in the Device::Node hierarchy like Device::Node::Alpha::DS10 etc. nodes_in_list passes the type qw(Device::Node) and role undef to _in_list along with the list provided to nodes_in_list

non_leaders_in_list
non_leaders_in_list uses the private function _in_list to return all of the entries in the input list that are of type Device::Node, and DO NOT HAVE the role of leader. non_leaders_in_list passes the type Device::Node, the role ^leader (meaning not leader), and the list as provided to non_leaders_in_list to _in_list.

leaders_in_list
leaders_in_list uses the private function _in_list to return all of the entries in the input list that are of type Device::Node, and HAVE the role of leader. leaders_in_list passes the type Device::Node, the role leader and the list as provided to non_leaders_in_list to _in_list.

process_list
process_list is a special purpose function used by the csuite of commands. process_list will return a list of entries of type Device or Device::Node based on the type input field. the list provided can be any mixture of devices or collections. When process_list encounters a collection, it will include all of the entries in the collection if the global variable B$main::all> is defined. This is meaningful only for commands that can act on devices of any type. If the $main::all global is not defined, process_list will return devices of type Device::Node that do not have a role of leader. As mentioned this is a very special purpose function that is common amoung the csuite of commands that is needed to do the right thing based on user command line input.

union_n_intersection
union_n_intersection returns both the union and intersection of all of the provided lists. Note that the item must appear in all lists to appear in the intersection. Note you must union_n_intersection pass references to lists to the function so it can differentiate between lists.

group_with_leader
Given a list of devices group_with_leader will group the device with it's leader if the leader is in fact defined for the device. Otherwise the device will be grouped with undef. A hash is returned with leaders as the keys to the hash and anonymouns arrays containing the lists of devices associated with the leader key.

who_am_i
who_am_i returns the valid database name entry for the node that the function is executed on. For example who_am_i will first attempt to query the database for an entry based on what the hostname of the node is. If found the hostname is returned. If the hostname is not a valid database entry who_am_i will do a fetch_by_value call to the database, based on the IP address associated with the hostname. If this results in a valid lookup the name of the interface associated with that IP address will be returned. Otherwise some sort of error will be printed and localhost will be returned.

REAPER
REAPER is used for child cleanup in may utilities. It is normally used by setting the $SIG{CHLD} signal as follows: $SIG{CHLD} = \&REAPER;

getalpha
Given a default character set (or @main::alphabet if it is defined), getalpha translates an integer into an alpha-numeric key string. This is most commonly used for constructing tables that need a compact, and unique, identifier for vmname, jobid, etc. getalpha returns _strings_, so ``0'' != ``00'' and ``a'' != ``aa'', and there really is no limit on how high you can count.

print_status
Primarily used by the status command, but put in this module so other programs can print consistent format. print_status parameters are: $preamble - user specified string to print out with status $obj - the object that the status was performed on $stat_ref - a reference to the status structure returned by all status methods $full - 1 or 0, if true will print out the entire status structure. $only - user specified KEY of the status structure to print, or 0.


FILES

/<install_dir>/lib/Util.pm


SEE ALSO