| 1 |
NAME |
| 2 |
AnyEvent::FastPing - quickly ping a large number of hosts |
| 3 |
|
| 4 |
SYNOPSIS |
| 5 |
use AnyEvent::FastPing; |
| 6 |
|
| 7 |
DESCRIPTION |
| 8 |
This module was written for a single purpose only: sending ICMP ECHO |
| 9 |
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 |
AnyEvent::FastPing::ipv4_supported |
| 18 |
Returns true if IPv4 is supported in this module and on this system. |
| 19 |
|
| 20 |
AnyEvent::FastPing::ipv6_supported |
| 21 |
Returns true if IPv6 is supported in this module and on this system. |
| 22 |
|
| 23 |
AnyEvent::FastPing::icmp4_pktsize |
| 24 |
Returns the number of bytes each IPv4 ping packet has. |
| 25 |
|
| 26 |
AnyEvent::FastPing::icmp6_pktsize |
| 27 |
Returns the number of bytes each IPv4 ping packet has. |
| 28 |
|
| 29 |
AnyEvent::FastPing::icmp_ping [ranges...], $send_interval, $payload, |
| 30 |
\&callback |
| 31 |
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 |
pings will be sent as fast as possible. |
| 43 |
|
| 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 |
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 |
.001, 0x12345678, |
| 83 |
sub { |
| 84 |
warn "all ranges pinged\n"; |
| 85 |
$done->broadcast; |
| 86 |
} |
| 87 |
; |
| 88 |
|
| 89 |
$done->wait; |
| 90 |
|
| 91 |
AnyEvent::FastPing::register_cb \&cb |
| 92 |
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 |
regardless of whether the reply is actually a reply to a ping sent |
| 95 |
earlier). |
| 96 |
|
| 97 |
The code reference gets a single parameter - an arrayref with an |
| 98 |
entry for each received packet (replies are being batched for |
| 99 |
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: register a callback which simply dumps the received data. |
| 105 |
Since the coderef is created on the fly via sub, it would be hard to |
| 106 |
unregister this callback again :) |
| 107 |
|
| 108 |
AnyEvent::FastPing::register_cb sub { |
| 109 |
for (@{$_[0]}) { |
| 110 |
printf "%s %d %g\n", |
| 111 |
(4 == length $_->[0] ? inet_ntoa $_->[0] : Socket6::inet_ntop (&AF_INET6, $_->[0])), |
| 112 |
$_->[2], |
| 113 |
$_->[1]; |
| 114 |
} |
| 115 |
}; |
| 116 |
|
| 117 |
Example: a single ping reply with payload of 1 from "::1" gets |
| 118 |
passed like this: |
| 119 |
|
| 120 |
[ [ |
| 121 |
"\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\1", |
| 122 |
"0.000280141830444336", |
| 123 |
1 |
| 124 |
] ] |
| 125 |
|
| 126 |
Example: ping replies for 127.0.0.1 and 127.0.0.2, with a payload of |
| 127 |
0x12345678: |
| 128 |
|
| 129 |
[ |
| 130 |
[ |
| 131 |
"\177\0\0\1", |
| 132 |
"0.00015711784362793", |
| 133 |
305419896 |
| 134 |
], |
| 135 |
[ |
| 136 |
"\177\0\0\2", |
| 137 |
"0.00090184211731", |
| 138 |
305419896 |
| 139 |
] |
| 140 |
] |
| 141 |
|
| 142 |
AnyEvent::FastPing::unregister_cb \&cb |
| 143 |
Unregister the callback again (make sure you pass the same |
| 144 |
codereference as to "register_cb"). |
| 145 |
|
| 146 |
AUTHOR |
| 147 |
Marc Lehmann <schmorp@schmorp.de> |
| 148 |
http://home.schmorp.de/ |
| 149 |
|
| 150 |
LICENSE |
| 151 |
This software is distributed under the GENERAL PUBLIC LICENSE, version 2 |
| 152 |
or any later version or, at your option, the Artistic License. |
| 153 |
|
