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

NAME
    AnyEvent::FastPing - quickly ping a large number of hosts

SYNOPSIS
     use AnyEvent::FastPing;

DESCRIPTION
    This module was written for a single purpose only: sending ICMP ECHO
    REQUEST packets as quickly as possible to a large number of hosts
    (thousands to millions).

    It employs a sending thread and is fully event-driven (using AnyEvent),
    so you have to run an event model supported by AnyEvent to use this
    module.

FUNCTIONS
    AnyEvent::FastPing::ipv4_supported
        Returns true if IPv4 is supported in this module and on this system.

    AnyEvent::FastPing::ipv6_supported
        Returns true if IPv6 is supported in this module and on this system.

    AnyEvent::FastPing::icmp4_pktsize
        Returns the number of bytes each IPv4 ping packet has.

    AnyEvent::FastPing::icmp6_pktsize
        Returns the number of bytes each IPv4 ping packet has.

    AnyEvent::FastPing::icmp_ping [ranges...], $send_interval, $payload,
    \&callback
        Ping the given IPv4 address ranges. Each range is an arrayref of the
        form "[lo, hi, interval]", where "lo" and "hi" are octet strings
        with either 4 octets (for IPv4 addresses) or 16 octets (for IPV6
        addresses), representing the lowest and highest address to ping (you
        can convert a dotted-quad IPv4 address to this format by using
        "inet_aton $address". The range "interval" is the minimum time in
        seconds between pings to the given range. If omitted, defaults to
        $send_interval.

        The $send_interval is the minimum interval between sending any two
        packets and is a way to make an overall rate limit. If omitted,
        pings will be sent as fast as possible.

        The $payload is a 32 bit unsigned integer given as the ICMP ECHO
        REQUEST ident and sequence numbers (in unspecified order :).

        The request will be queued and all requests will be served by a
        background thread in order. When all ranges have been pinged, the
        "callback" will be called.

        Algorithm: Each range has an associated "next time to send packet"
        time. The algorithm loops as long as there are ranges with hosts to
        be pinged and always serves the range with the most urgent packet
        send time. It will at most send one packet every $send_interval
        seconds.

        This will ensure that pings to the same range are nicely interleaved
        with other ranges - this can help reduce per-subnet bandwidth while
        maintaining an overall high packet rate.

        The algorithm to send each packet is O(log n) on the number of
        ranges, so even a large number of ranges (many thousands) is
        managable.

        No storage is allocated per address.

        Performance: On my 2 GHz Opteron system with a pretty average nvidia
        gigabit network card I can ping around 60k to 200k adresses per
        second, depending on routing decisions.

        Example: ping 10.0.0.1-10.0.0.15 with at most 100 packets/s, and
        11.0.0.1-11.0.255.255 with at most 1000 packets/s. Do not, however,
        exceed 1000 packets/s overall:

           my $done = AnyEvent->condvar;

           AnyEvent::FastPing::icmp_ping
              [
                 [v10.0.0.1, v10.0.0.15, .01],
                 [v11.0.0.1, v11.0.255.255, .001],
              ],
              .001, 0x12345678,
              sub {
                 warn "all ranges pinged\n";
                 $done->broadcast;
              }
           ;

           $done->wait;

    AnyEvent::FastPing::register_cb \&cb
        Register a callback that is called for every received ping reply
        (regardless of whether a ping is still in process or not and
        regardless of whether the reply is actually a reply to a ping sent
        earlier).

        The code reference gets a single parameter - an arrayref with an
        entry for each received packet (replies are being batched for
        greater efficiency). Each packet is represented by an arrayref with
        three members: the source address (an octet string of either 4
        (IPv4) or 16 (IPv6) octets length), the payload as passed to
        "icmp_ping" and the round trip time in seconds.

        Example: a single ping reply with payload of 1 from "::1" gets
        passed like this:

           [ [
             "\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\1",
             "0.000280141830444336",
             1
           ] ]

        Example: ping replies for 127.0.0.1 and 127.0.0.2, with a payload of
        0x12345678:

           [
              [
                "\177\0\0\1",
                "0.00015711784362793",
                305419896
              ],
              [
                "\177\0\0\2",
                "0.00090184211731",
                305419896
              ]
           ]

    AnyEvent::FastPing::unregister_cb \&cb
        Unregister the callback again (make sure you pass the same
        codereference as to "register_cb").

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

LICENSE
       This software is distributed under the GENERAL PUBLIC LICENSE, version 2
       or any later version or, at your option, the Artistic License.

Revision:	1.7
Committed:	Tue Nov 17 21:38:07 2009 UTC (14 years, 6 months ago) by root
Branch:	MAIN
CVS Tags:	rel-1_12
Changes since 1.6:	+7 -7 lines
Log Message:	1.12
#	User	Rev	Content
1	root	1.3	NAME
2	root	1.5	AnyEvent::FastPing - quickly ping a large number of hosts
3	root	1.3
4			SYNOPSIS
5	root	1.5	use AnyEvent::FastPing;
6	root	1.3
7			DESCRIPTION
8	root	1.6	This module was written for a single purpose only: sending ICMP ECHO
9	root	1.3	REQUEST packets as quickly as possible to a large number of hosts
10			(thousands to millions).
11
12			It employs a sending thread and is fully event-driven (using AnyEvent),
13			so you have to run an event model supported by AnyEvent to use this
14			module.
15
16			FUNCTIONS
17	root	1.5	AnyEvent::FastPing::ipv4_supported
18	root	1.3	Returns true if IPv4 is supported in this module and on this system.
19
20	root	1.5	AnyEvent::FastPing::ipv6_supported
21	root	1.3	Returns true if IPv6 is supported in this module and on this system.
22
23	root	1.5	AnyEvent::FastPing::icmp4_pktsize
24	root	1.3	Returns the number of bytes each IPv4 ping packet has.
25
26	root	1.5	AnyEvent::FastPing::icmp6_pktsize
27	root	1.3	Returns the number of bytes each IPv4 ping packet has.
28
29	root	1.5	AnyEvent::FastPing::icmp_ping [ranges...], $send_interval, $payload,
30			\&callback
31	root	1.3	Ping the given IPv4 address ranges. Each range is an arrayref of the
32			form "[lo, hi, interval]", where "lo" and "hi" are octet strings
33			with either 4 octets (for IPv4 addresses) or 16 octets (for IPV6
34			addresses), representing the lowest and highest address to ping (you
35			can convert a dotted-quad IPv4 address to this format by using
36			"inet_aton $address". The range "interval" is the minimum time in
37			seconds between pings to the given range. If omitted, defaults to
38			$send_interval.
39
40			The $send_interval is the minimum interval between sending any two
41			packets and is a way to make an overall rate limit. If omitted,
42	root	1.7	pings will be sent as fast as possible.
43	root	1.3
44			The $payload is a 32 bit unsigned integer given as the ICMP ECHO
45			REQUEST ident and sequence numbers (in unspecified order :).
46
47			The request will be queued and all requests will be served by a
48			background thread in order. When all ranges have been pinged, the
49			"callback" will be called.
50
51			Algorithm: Each range has an associated "next time to send packet"
52			time. The algorithm loops as long as there are ranges with hosts to
53			be pinged and always serves the range with the most urgent packet
54			send time. It will at most send one packet every $send_interval
55			seconds.
56
57			This will ensure that pings to the same range are nicely interleaved
58			with other ranges - this can help reduce per-subnet bandwidth while
59			maintaining an overall high packet rate.
60
61			The algorithm to send each packet is O(log n) on the number of
62			ranges, so even a large number of ranges (many thousands) is
63			managable.
64
65			No storage is allocated per address.
66
67			Performance: On my 2 GHz Opteron system with a pretty average nvidia
68			gigabit network card I can ping around 60k to 200k adresses per
69			second, depending on routing decisions.
70
71			Example: ping 10.0.0.1-10.0.0.15 with at most 100 packets/s, and
72			11.0.0.1-11.0.255.255 with at most 1000 packets/s. Do not, however,
73			exceed 1000 packets/s overall:
74
75			my $done = AnyEvent->condvar;
76
77	root	1.5	AnyEvent::FastPing::icmp_ping
78			[
79			[v10.0.0.1, v10.0.0.15, .01],
80			[v11.0.0.1, v11.0.255.255, .001],
81			],
82	root	1.3	.001, 0x12345678,
83			sub {
84			warn "all ranges pinged\n";
85			$done->broadcast;
86			}
87			;
88
89			$done->wait;
90
91	root	1.5	AnyEvent::FastPing::register_cb \&cb
92	root	1.3	Register a callback that is called for every received ping reply
93			(regardless of whether a ping is still in process or not and
94	root	1.5	regardless of whether the reply is actually a reply to a ping sent
95	root	1.3	earlier).
96
97			The code reference gets a single parameter - an arrayref with an
98	root	1.7	entry for each received packet (replies are being batched for
99	root	1.3	greater efficiency). Each packet is represented by an arrayref with
100			three members: the source address (an octet string of either 4
101			(IPv4) or 16 (IPv6) octets length), the payload as passed to
102			"icmp_ping" and the round trip time in seconds.
103
104			Example: a single ping reply with payload of 1 from "::1" gets
105			passed like this:
106
107			[ [
108			"\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\1",
109			"0.000280141830444336",
110			1
111			] ]
112
113			Example: ping replies for 127.0.0.1 and 127.0.0.2, with a payload of
114			0x12345678:
115
116			[
117			[
118			"\177\0\0\1",
119			"0.00015711784362793",
120			305419896
121			],
122			[
123			"\177\0\0\2",
124			"0.00090184211731",
125			305419896
126			]
127			]
128
129	root	1.5	AnyEvent::FastPing::unregister_cb \&cb
130	root	1.3	Unregister the callback again (make sure you pass the same
131			codereference as to "register_cb").
132
133			AUTHOR
134	root	1.7	Marc Lehmann <schmorp@schmorp.de>
135			http://home.schmorp.de/
136	root	1.3
137	root	1.7	LICENSE
138			This software is distributed under the GENERAL PUBLIC LICENSE, version 2
139			or any later version or, at your option, the Artistic License.
140	root	1.3