--- AnyEvent-SNMP/README 2007/12/03 17:27:38 1.1 +++ AnyEvent-SNMP/README 2009/04/19 11:06:21 1.3 @@ -1,41 +1,113 @@ NAME - Net::SNMP::EV - adaptor to integrate Net::SNMP into the EV event loop. + AnyEvent::SNMP - adaptor to integrate Net::SNMP into Anyevent. SYNOPSIS - use EV; + use AnyEvent::SNMP; use Net::SNMP; - use Net::SNMP::EV; - # just use Net::SNMP and EV as you like: + # just use Net::SNMP and AnyEvent as you like: - ... start non-blocking snmp request(s)... + # use a condvar to transfer results, this is + # just an example, you can use a naked callback as well. + my $cv = AnyEvent->condvar; + + # ... start non-blocking snmp request(s)... + Net::SNMP->session (-hostname => "127.0.0.1", + -community => "public", + -nonblocking => 1) + ->get_request (-callback => sub { $cv->send (@_) }); - EV::loop; + # ... do something else until the result is required + my @result = $cv->wait; DESCRIPTION - This module coerces the Net::SNMP scheduler to use the EV high - performance event loop as underlying event loop, i.e. EV will be used by - Net::SNMP for all events. - - This integrates Net::SNMP into EV: You can make non-blocking Net::SNMP - calls and as long as your main program uses the EV event loop, they will - run in parallel to anything else that uses EV or AnyEvent. + This module implements an alternative "event dispatcher" for Net::SNMP, + using AnyEvent as a backend. - This module does not export anything and does not require you to do - anything special apart from loading it. + This integrates Net::SNMP into AnyEvent: You can make non-blocking + Net::SNMP calls and as long as other parts of your program also use + AnyEvent (or some event loop supported by AnyEvent), they will run in + parallel. + + Also, the Net::SNMP scheduler is very inefficient with respect to both + CPU and memory usage. Most AnyEvent backends (including the pure-perl + backend) fare much better than the Net::SNMP dispatcher. + + A potential disadvantage is that replacing the dispatcher is not at all + a documented thing to do, so future changes in Net::SNP might break this + module (or the many similar ones). - The module is quite short, you cna use it to do a similar integration - into e.g. Event or other event loops. + This module does not export anything and does not require you to do + anything special apart from loading it *before doing any non-blocking + requests with Net::SNMP*. It is recommended but not required to load + this module before "Net::SNMP". + +GLOBAL VARIABLES + $AnyEvent::SNMP::MAX_OUTSTANDING (default: 50, dynamic) + Use this package variable to restrict the number of outstanding SNMP + requests at any point in time. + + Net::SNMP is very fast at creating and sending SNMP requests, but + much slower at parsing (big, bulk) responses. This makes it easy to + request a lot of data that can take many seconds to parse. + + In the best case, this can lead to unnecessary delays (and even + time-outs, as the data has been received but not yet processed) and + in the worst case, this can lead to packet loss, when the receive + queue overflows and the kernel can no longer accept new packets. + + To avoid this, you can (and should) limit the number of outstanding + requests to a number low enough so that parsing time doesn't + introduce noticable delays. + + Unfortunately, this number depends not only on processing speed and + load of the machine running Net::SNMP, but also on the network + latency and the speed of your SNMP agents. + + AnyEvent::SNMP tries to dynamically adjust this number dynamically + upwards and downwards. + + Note that you can use Net::SNMP::XS to speed up parsing of responses + considerably. + + $AnyEvent::SNMP::MIN_RECVQUEUE (default: 4) + $AnyEvent::SNMP::MAX_RECVQUEUE (default: 64) + These values specify the minimum and maximum receive queue length + (in units of one response packet). + + When AnyEvent::SNMP handles $MAX_RECVQUEUE or more packets per + iteration it will reduce $MAX_OUTSTANDING. If it handles less than + $MIN_RECVQUEUE, it increases $MAX_OUTSTANDING. + + This has the result of adjusting the number of outstanding requests + so that the recv queue is between the minimum and maximu, usually. + + This algorithm works reasonably well as long as the responses, + response latencies and processing times are the same size per packet + on average. + +COMPATIBILITY + This module may be used as a drop in replacement for the + Net::SNMP::Dispatcher in existing programs. You can still call + "snmp_dispatcher" to start the event-loop, but then you loose the + benefit of mixing Net::SNMP events with other events. + + use AnyEvent::SNMP; + use Net::SNMP; + + # just use Net::SNMP as before + + # ... start non-blocking snmp request(s)... + Net::SNMP->session ( + -hostname => "127.0.0.1", + -community => "public", + -nonblocking => 1, + )->get_request (-callback => sub { ... }); -BUGS - Net::SNMP has no (documented or otherwise) API to do what this module - does. As such, this module rummages around in the internals of Net::SNMP - in a rather inacceptable way, and as thus might be very sensitive to the - version of Net::SNMP used (it has been tested with some 5.x versions - only, YMMV). + snmp_dispatcher; SEE ALSO - EV, Net::SNMP, AnyEvent, Glib::EV. + AnyEvent, Net::SNMP, Net::SNMP::XS, Net::SNMP::EV. AUTHOR Marc Lehmann