[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: 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).

    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 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.

        Increasing $MAX_OUTSTANDING will not automatically use the "extra
        request slots. To increase $MAX_OUTSTANDING" and make
        ""AnyEvent::SNMP" make use of the extra paralellity, 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 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 { ... });

       snmp_dispatcher;

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

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

POD ERRORS
    Hey! The above document had some coding errors, which are explained
    below:

    Around line 79:
        Unterminated C<...> sequence

Revision:	1.4
Committed:	Sat Apr 25 12:20:50 2009 UTC (15 years, 1 month ago) by root
Branch:	MAIN
CVS Tags:	rel-0_2
Changes since 1.3:	+19 -1 lines
Log Message:	0.2
#	User	Rev	Content
1	root	1.1	NAME
2	root	1.2	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			using AnyEvent as a backend.
26
27			This integrates Net::SNMP into AnyEvent: You can make non-blocking
28			Net::SNMP calls and as long as other parts of your program also use
29			AnyEvent (or some event loop supported by AnyEvent), they will run in
30			parallel.
31
32			Also, the Net::SNMP scheduler is very inefficient with respect to both
33			CPU and memory usage. Most AnyEvent backends (including the pure-perl
34			backend) fare much better than the Net::SNMP dispatcher.
35
36			A potential disadvantage is that replacing the dispatcher is not at all
37			a documented thing to do, so future changes in Net::SNP might break this
38			module (or the many similar ones).
39	root	1.1
40			This module does not export anything and does not require you to do
41	root	1.2	anything special apart from loading it *before doing any non-blocking
42			requests with Net::SNMP*. It is recommended but not required to load
43			this module before "Net::SNMP".
44	root	1.1
45	root	1.3	GLOBAL VARIABLES
46			$AnyEvent::SNMP::MAX_OUTSTANDING (default: 50, dynamic)
47	root	1.4	AnyEvent::SNMP::set_max_outstanding $new_value
48	root	1.3	Use this package variable to restrict the number of outstanding SNMP
49			requests at any point in time.
50
51			Net::SNMP is very fast at creating and sending SNMP requests, but
52			much slower at parsing (big, bulk) responses. This makes it easy to
53			request a lot of data that can take many seconds to parse.
54
55			In the best case, this can lead to unnecessary delays (and even
56			time-outs, as the data has been received but not yet processed) and
57			in the worst case, this can lead to packet loss, when the receive
58			queue overflows and the kernel can no longer accept new packets.
59
60			To avoid this, you can (and should) limit the number of outstanding
61			requests to a number low enough so that parsing time doesn't
62			introduce noticable delays.
63
64			Unfortunately, this number depends not only on processing speed and
65			load of the machine running Net::SNMP, but also on the network
66			latency and the speed of your SNMP agents.
67
68			AnyEvent::SNMP tries to dynamically adjust this number dynamically
69			upwards and downwards.
70
71	root	1.4	Increasing $MAX_OUTSTANDING will not automatically use the "extra
72			request slots. To increase $MAX_OUTSTANDING" and make
73			""AnyEvent::SNMP" make use of the extra paralellity, call
74			"AnyEvent::SNMP::set_max_outstanding" with the new value, e.g.:"
75
76			AnyEvent::SNMP::set_max_outstanding 500;
77
78			Although due to the dynamic adjustment, this might have little
79			lasting effect.
80
81	root	1.3	Note that you can use Net::SNMP::XS to speed up parsing of responses
82			considerably.
83
84	root	1.4	$AnyEvent::SNMP::MIN_RECVQUEUE (default: 8)
85	root	1.3	$AnyEvent::SNMP::MAX_RECVQUEUE (default: 64)
86			These values specify the minimum and maximum receive queue length
87			(in units of one response packet).
88
89			When AnyEvent::SNMP handles $MAX_RECVQUEUE or more packets per
90			iteration it will reduce $MAX_OUTSTANDING. If it handles less than
91			$MIN_RECVQUEUE, it increases $MAX_OUTSTANDING.
92
93			This has the result of adjusting the number of outstanding requests
94			so that the recv queue is between the minimum and maximu, usually.
95
96			This algorithm works reasonably well as long as the responses,
97			response latencies and processing times are the same size per packet
98			on average.
99
100			COMPATIBILITY
101			This module may be used as a drop in replacement for the
102			Net::SNMP::Dispatcher in existing programs. You can still call
103			"snmp_dispatcher" to start the event-loop, but then you loose the
104			benefit of mixing Net::SNMP events with other events.
105
106			use AnyEvent::SNMP;
107			use Net::SNMP;
108
109			# just use Net::SNMP as before
110
111			# ... start non-blocking snmp request(s)...
112			Net::SNMP->session (
113			-hostname => "127.0.0.1",
114			-community => "public",
115			-nonblocking => 1,
116			)->get_request (-callback => sub { ... });
117
118			snmp_dispatcher;
119
120	root	1.1	SEE ALSO
121	root	1.3	AnyEvent, Net::SNMP, Net::SNMP::XS, Net::SNMP::EV.
122	root	1.1
123			AUTHOR
124			Marc Lehmann <schmorp@schmorp.de>
125			http://home.schmorp.de/
126
127	root	1.4	POD ERRORS
128			Hey! The above document had some coding errors, which are explained
129			below:
130
131			Around line 79:
132			Unterminated C<...> sequence
133