[ViewVC] Annotation of: cvs/AnyEvent-SNMP/README

NAME
    AnyEvent::SNMP - adaptor to integrate Net::SNMP into AnyEvent.

SYNOPSIS
     use AnyEvent::SNMP;
     use Net::SNMP;

     # just use Net::SNMP and AnyEvent as you like:

     # 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 (@_) });

     # ... do something else until the result is required
     my @result = $cv->wait;

DESCRIPTION
    This module implements an alternative "event dispatcher" for Net::SNMP,
    using AnyEvent as a backend. This integrates Net::SNMP into AnyEvent.
    That means 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.

    Another major added feature of this module over Net::SNMP is automatic
    rate-adjustments: Net::SNMP is so slow that firing a few thousand
    requests can cause many timeouts simply because Net::SNMP cannot process
    the replies in time. This module automatically adapts the send rate to
    avoid false timeouts caused by slow reply processing.

    A potential disadvantage of this module is that replacing the dispatcher
    is not at all a documented thing to do, so future changes in Net::SNMP
    might break this module (or the many similar ones).

    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)
    AnyEvent::SNMP::set_max_outstanding $new_value
        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 noticeable 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 upwards and
        downwards.

        Increasing $MAX_OUTSTANDING will not automatically use the extra
        request slots. To increase $MAX_OUTSTANDING and make
        "AnyEvent::SNMP" make use of the extra parallelity, call
        "AnyEvent::SNMP::set_max_outstanding" with the new value, e.g.:

           AnyEvent::SNMP::set_max_outstanding 500;

        Although due to the dynamic adjustment, this might have little
        lasting effect.

        Note that you can use Net::SNMP::XS to speed up parsing of responses
        considerably.

    $AnyEvent::SNMP::MIN_RECVQUEUE (default: 8)
    $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 maximum, usually.

        This algorithm works reasonably well as long as the responses,
        response latencies and processing times are the same 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 { ... });

       snmp_dispatcher;

SEE ALSO
    AnyEvent, Net::SNMP, Net::SNMP::XS, Net::SNMP::EV.

AUTHOR
     Marc Lehmann <schmorp@schmorp.de>
     http://home.schmorp.de/

Revision:	1.7
Committed:	Wed Oct 9 18:22:59 2019 UTC (4 years, 7 months ago) by root
Branch:	MAIN
CVS Tags:	rel-6_02, HEAD
Changes since 1.6:	+7 -7 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	NAME
2	root	1.5	AnyEvent::SNMP - adaptor to integrate Net::SNMP into AnyEvent.
3	root	1.1
4			SYNOPSIS
5	root	1.2	use AnyEvent::SNMP;
6	root	1.1	use Net::SNMP;
7
8	root	1.2	# just use Net::SNMP and AnyEvent as you like:
9	root	1.1
10	root	1.2	# use a condvar to transfer results, this is
11			# just an example, you can use a naked callback as well.
12			my $cv = AnyEvent->condvar;
13
14			# ... start non-blocking snmp request(s)...
15			Net::SNMP->session (-hostname => "127.0.0.1",
16			-community => "public",
17			-nonblocking => 1)
18			->get_request (-callback => sub { $cv->send (@_) });
19	root	1.1
20	root	1.2	# ... do something else until the result is required
21			my @result = $cv->wait;
22	root	1.1
23			DESCRIPTION
24	root	1.2	This module implements an alternative "event dispatcher" for Net::SNMP,
25	root	1.6	using AnyEvent as a backend. This integrates Net::SNMP into AnyEvent.
26			That means you can make non-blocking Net::SNMP calls and as long as
27			other parts of your program also use AnyEvent (or some event loop
28			supported by AnyEvent), they will run in parallel.
29	root	1.2
30			Also, the Net::SNMP scheduler is very inefficient with respect to both
31			CPU and memory usage. Most AnyEvent backends (including the pure-perl
32			backend) fare much better than the Net::SNMP dispatcher.
33
34	root	1.7	Another major added feature of this module over Net::SNMP is automatic
35	root	1.6	rate-adjustments: Net::SNMP is so slow that firing a few thousand
36			requests can cause many timeouts simply because Net::SNMP cannot process
37			the replies in time. This module automatically adapts the send rate to
38			avoid false timeouts caused by slow reply processing.
39
40			A potential disadvantage of this module is that replacing the dispatcher
41	root	1.7	is not at all a documented thing to do, so future changes in Net::SNMP
42	root	1.6	might break this module (or the many similar ones).
43	root	1.1
44			This module does not export anything and does not require you to do
45	root	1.2	anything special apart from loading it *before doing any non-blocking
46			requests with Net::SNMP*. It is recommended but not required to load
47			this module before "Net::SNMP".
48	root	1.1
49	root	1.3	GLOBAL VARIABLES
50			$AnyEvent::SNMP::MAX_OUTSTANDING (default: 50, dynamic)
51	root	1.4	AnyEvent::SNMP::set_max_outstanding $new_value
52	root	1.3	Use this package variable to restrict the number of outstanding SNMP
53			requests at any point in time.
54
55			Net::SNMP is very fast at creating and sending SNMP requests, but
56			much slower at parsing (big, bulk) responses. This makes it easy to
57			request a lot of data that can take many seconds to parse.
58
59			In the best case, this can lead to unnecessary delays (and even
60			time-outs, as the data has been received but not yet processed) and
61			in the worst case, this can lead to packet loss, when the receive
62			queue overflows and the kernel can no longer accept new packets.
63
64			To avoid this, you can (and should) limit the number of outstanding
65			requests to a number low enough so that parsing time doesn't
66	root	1.7	introduce noticeable delays.
67	root	1.3
68			Unfortunately, this number depends not only on processing speed and
69			load of the machine running Net::SNMP, but also on the network
70			latency and the speed of your SNMP agents.
71
72	root	1.6	AnyEvent::SNMP tries to dynamically adjust this number upwards and
73			downwards.
74	root	1.3
75	root	1.5	Increasing $MAX_OUTSTANDING will not automatically use the extra
76			request slots. To increase $MAX_OUTSTANDING and make
77	root	1.7	"AnyEvent::SNMP" make use of the extra parallelity, call
78	root	1.5	"AnyEvent::SNMP::set_max_outstanding" with the new value, e.g.:
79	root	1.4
80			AnyEvent::SNMP::set_max_outstanding 500;
81
82			Although due to the dynamic adjustment, this might have little
83			lasting effect.
84
85	root	1.3	Note that you can use Net::SNMP::XS to speed up parsing of responses
86			considerably.
87
88	root	1.4	$AnyEvent::SNMP::MIN_RECVQUEUE (default: 8)
89	root	1.3	$AnyEvent::SNMP::MAX_RECVQUEUE (default: 64)
90			These values specify the minimum and maximum receive queue length
91			(in units of one response packet).
92
93			When AnyEvent::SNMP handles $MAX_RECVQUEUE or more packets per
94			iteration it will reduce $MAX_OUTSTANDING. If it handles less than
95			$MIN_RECVQUEUE, it increases $MAX_OUTSTANDING.
96
97			This has the result of adjusting the number of outstanding requests
98	root	1.7	so that the recv queue is between the minimum and maximum, usually.
99	root	1.3
100			This algorithm works reasonably well as long as the responses,
101	root	1.7	response latencies and processing times are the same per packet on
102			average.
103	root	1.3
104			COMPATIBILITY
105			This module may be used as a drop in replacement for the
106			Net::SNMP::Dispatcher in existing programs. You can still call
107			"snmp_dispatcher" to start the event-loop, but then you loose the
108			benefit of mixing Net::SNMP events with other events.
109
110			use AnyEvent::SNMP;
111			use Net::SNMP;
112
113			# just use Net::SNMP as before
114
115			# ... start non-blocking snmp request(s)...
116			Net::SNMP->session (
117			-hostname => "127.0.0.1",
118			-community => "public",
119			-nonblocking => 1,
120			)->get_request (-callback => sub { ... });
121
122			snmp_dispatcher;
123
124	root	1.1	SEE ALSO
125	root	1.3	AnyEvent, Net::SNMP, Net::SNMP::XS, Net::SNMP::EV.
126	root	1.1
127			AUTHOR
128			Marc Lehmann <schmorp@schmorp.de>
129			http://home.schmorp.de/
130