The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
SNMP-Query-Asynch-v0.1_38
River stage zero No dependents
++
/ SNMP::Query::Asynch

NAME

SNMP::Query::Asynch - Fast asynchronous execution of batches of SNMP queries

VERSION

Version 0.01

SYNOPSIS

 use SNMP::Query::Asynch;
  
 my @varbinds = qw(
        ifDescr ifInOctets ifOutOctets ifAlias ifType
        ifName  ifInErrors ifOutErrors ifSpeed
        ifAdminStatus      ifOperStatus
    );
 
 my $query = SNMP::Query::Asynch->new();
 
 # You should create and populate @hosts to make this synposis code work. 
 # It's an AoH, fairly simple. For example...
 my @hosts = create_hosts_array('snmp_hosts.csv');
 
 foreach my $host (@hosts) {
     
     # Add a getbulk operation to the queue.
     $query->add_getbulk({            
             # Params passed to directly to SNMP::Session->new()
             DestHost     => $host->{HOSTIP},
             Community    => $host->{COMMUNITY},
             Version      => $host->{SNMPVER},  # getbulk only supports 2 or 3.

             # Params concerning the type of query operation
             # See POD for SNMP::Session->getbulk() in this case.
             MaxRepeaters => 20,
             NonRepeaters => 0, 
 
             # The varbinds to be operated on - can be a reference to anything 
             # supported by the corresponding query operation in SNMP::Session.
             VarBinds     => \@varbinds, 
         });
     
 }
 
 # Execute the queries that were added, get a reference to the results array.
 my $results = $query->execute({ 
         InFlight      => 50, # Simultaneous operations
         MasterTimeout => 60, # Seconds until unfinished operations are aborted.
     });
 
 # See what the results look like.
 use Data::Dumper; 
 print Dumper $results;

DESCRIPTION

This module allows for a fairly simple, streamlined means of executing large numbers of SNMP operations as fast as your systems can handle. It extensively uses net-snmp's asynchronous operation interfaces and callbacks to keep as much data flowing as you need.

Perl's support of closures and anonymous subroutines provide the means for sophisticated, elegant control of query operations before and after execution. There are also facilities to install callbacks that are run after pre-set numbers (batches) of operations are completed .

These callbacks can be used to log progress, update the user, transfer results from memory to disk (or even another thread or process!) or anything you can think of! If there's some feature you desire, do not hesitate to ask me!!!

Please be aware - my primary design concern is speed and flexibility. I have certain non-scientific, subjective benchmarks I use to decide if some modification is worth-while, but so far the design of the internals of this module has lent itself to feature additions and enhancements very well.

SUBROUTINES/METHODS

new

Constructs a new query object with an empty queue.

Query Operation Addition Methods

In order to build a queue of query operations, you would repeatedly call one or more of these methods below to add an operation to the queue.

In addition to the parameters described for each method, they all require parameters that are passed directly to SNMP::Session->new() at execution time. However, those parameters are somewhat validated when the methods are called, to try to make debugging easier for code using this module.

See the discussion below on "Required Parameters SNMP::Session->new()" for more information.

add_getbulk

Adds a getbulk query operation to the queue.

add_gettable - NOT YET IMPLEMENTED

Adds a gettable query operation to the queue.

add_get - NOT YET IMPLEMENTED

Adds a get query operation to the queue.

add_fget - NOT YET IMPLEMENTED

Adds an fget query operation to the queue.

add_bulkwalk - NOT YET IMPLEMENTED

Adds a bulkwalk query operation to the queue.

add_getnext - NOT YET IMPLEMENTED

Adds a getnext query operation to the queue.

add_fgetnext - NOT YET IMPLEMENTED

Adds an fgetnext query operation to the queue.

add_set - NOT YET IMPLEMENTED

Adds a set query operation to the queue.

Required Parameters SNMP::Session->new()

Each query operation in the queue requires that a SNMP::Session object is constructed, but you can't pre-construct the SNMP::Session objects and pass those in because any more than 1023 of these in memory at a time will crash the program.

We get around this limitation by constructing only as many sessions as are needed to support the in-flight operations, and no more. To do that at execution time requires that the user specify the SNMP::Session->new() parameters whenever they add a new query operation using the methods below.

Therefore, I have listed below the parameters for SNMP::Session->new() that will be accepted by each of the query operation additions methods.

Because of these limitations, this module is tightly coupled with the SNMP module. There's really no other way to go about it, at least none that I can think of that doesn't unacceptably degrade the execution speed.

  • DestHost

  • Community

  • Version

  • RemotePort

  • Timeout

  • Retries

  • RetryNoSuch

  • SecName

  • SecLevel

  • SecEngineId

  • ContextEngineId

  • Context

  • AuthProto

  • AuthPass

  • PrivProto

  • PrivPass

  • AuthMasterKey

  • PrivMasterKey

  • AuthLocalizedKey

  • PrivLocalizedKey

  • VarFormats

  • TypeFormats

  • UseLongNames

  • UseSprintValue

  • UseEnums

  • UseNumeric

  • BestGuess

  • NonIncreasing

execute

Executes all operations in the queue.

shuffle

Shuffles the operations in the queue so they are executed in random order.

current_in_flight

Returns the number of operations currently issued which have not yet been completed.

Please note: completed means that the operation was issued and either results data or an error condition were recieved. If the operation was interrupted before that happens, then is not counted as completed. This typically only happens when the call to execute() was interrupted by a fatal error or the query-object's master timeout was exceeded.

this_run_issued

Returns the number of operations that have been issued during the current execute() call. If called after execute() has completed, returns the number issued during the most recent execute() call.

Each call to execute() resets this value to zero.

this_run_finished

Returns the number of operations that have been completed during the current execute() call. If called after execute() has completed, returns the number completed during the most recent execute() call.

Each call to execute() resets this value to zero.

grand_total_issued

Returns the number of operations that have been issued during all calls to execute() since the query object was created. This value is *never* reset.

grand_total_finished

Returns the number of operations that have been completed during all calls to execute() since the query object was created. This value is *never* reset.

get_results_ref

Returns a reference to the query object's internal results array.

NOTE: Yes, I *know* that providing access to an object's internal data is poor OO design, but it gets the job done right now. I do plan on converting the results array into it's own type of object with OO-kosher semantics, but only if that does not substantially impact overall speed.

That said, use this method with caution because in the future it will likely be changed to return something completely different than an array-ref or maybe even be removed and replaced with a different method. I may also have a moment of insanity and make the results-object tied so as to look like an array. But I doubt it unless people ask for it enough.

EXPORTS

Nothing.

SEE ALSO

SNMP SNMP::Effective SNMP::Multi MRTG RTG YATG

AUTHOR

Steve Scaffidi, <sscaffidi at cpan.org>

BUGS

Please report any bugs or feature requests to bug-snmp-query-asynch at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=SNMP-Query-Asynch. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc SNMP::Query::Asynch

You can also look for information at:

ACKNOWLEDGEMENTS

DEPENDENCIES

BUGS AND LIMITATIONS

INCOMPATIBILITIES

LICENSE AND COPYRIGHT

Copyright 2008 Steve Scaffidi, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.