ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent-FastPing/FastPing.pm
(Generate patch)

Comparing AnyEvent-FastPing/FastPing.pm (file contents):
Revision 1.11 by root, Mon Jan 31 05:35:48 2011 UTC vs.
Revision 1.18 by root, Fri Nov 11 01:18:56 2016 UTC

… …
10 10
11This module was written for a single purpose only: sending ICMP ECHO 11This module was written for a single purpose only: sending ICMP ECHO
12REQUEST packets as quickly as possible to a large number of hosts 12REQUEST packets as quickly as possible to a large number of hosts
13(thousands to millions). 13(thousands to millions).
14 14
15It employs a sending thread and is fully event-driven (using AnyEvent), so 15It employs a separate thread and is fully event-driven (using AnyEvent),
16you have to run an event model supported by AnyEvent to use this module. 16so you have to run an event model supported by AnyEvent to use this
17module.
17 18
18=head1 FUNCTIONS 19=head1 FUNCTIONS
19 20
20=over 4 21=over 4
21 22
… …
26use common::sense; 27use common::sense;
27 28
28use AnyEvent; 29use AnyEvent;
29 30
30BEGIN { 31BEGIN {
31 our $VERSION = '2.0'; 32 our $VERSION = 2.03;
32 our @ISA = qw(Exporter); 33 our @ISA = qw(Exporter);
33 34
34 require Exporter; 35 require Exporter;
35 #Exporter::export_ok_tags (keys %EXPORT_TAGS); 36 #Exporter::export_ok_tags (keys %EXPORT_TAGS);
36 37
… …
40 41
41our ($THR_RES_FD, $ICMP4_FD, $ICMP6_FD); 42our ($THR_RES_FD, $ICMP4_FD, $ICMP6_FD);
42 43
43our $THR_RES_FH; open $THR_RES_FH, "<&=$THR_RES_FD" or die "FATAL: cannot fdopen"; 44our $THR_RES_FH; open $THR_RES_FH, "<&=$THR_RES_FD" or die "FATAL: cannot fdopen";
44 45
46our $ICMP4_FH;
47our $ICMP6_FH;
48
49our @IDLE_CB;
50
51AnyEvent::post_detect {
45our $ICMP4_FH; our $ICMP4_W = $ICMP4_FD >= 0 && (open $ICMP4_FH, "<&=$ICMP4_FD") && AE::io $ICMP4_FH, 0, \&_recv_icmp4; 52 our $ICMP4_W = $ICMP4_FD >= 0 && (open $ICMP4_FH, "<&=$ICMP4_FD") && AE::io $ICMP4_FH, 0, \&_recv_icmp4;
46our $ICMP6_FH; our $ICMP6_W = $ICMP6_FD >= 0 && (open $ICMP6_FH, "<&=$ICMP6_FD") && AE::io $ICMP6_FH, 0, \&_recv_icmp6; 53 our $ICMP6_W = $ICMP6_FD >= 0 && (open $ICMP6_FH, "<&=$ICMP6_FD") && AE::io $ICMP6_FH, 0, \&_recv_icmp6;
54
55 our $THR_RES_W = AE::io $THR_RES_FH, 0, sub {
56 sysread $THR_RES_FH, my $buf, 8;
57
58 for my $id (unpack "S*", $buf) {
59 _stop_id $id;
60 ($IDLE_CB[$id] || sub { })->();
61 }
62 };
63};
47 64
48=item AnyEvent::FastPing::ipv4_supported 65=item AnyEvent::FastPing::ipv4_supported
49 66
50Returns true if IPv4 is supported in this module and on this system. 67Returns true iff IPv4 is supported in this module and on this system.
51 68
52=item AnyEvent::FastPing::ipv6_supported 69=item AnyEvent::FastPing::ipv6_supported
53 70
54Returns true if IPv6 is supported in this module and on this system. 71Returns true iff IPv6 is supported in this module and on this system.
55 72
56=item AnyEvent::FastPing::icmp4_pktsize 73=item AnyEvent::FastPing::icmp4_pktsize
57 74
58Returns the number of bytes each IPv4 ping packet has. 75Returns the number of octets per IPv4 ping packet (the whole IP packet
76including headers, excluding lower-level headers or trailers such as
77Ethernet).
78
79Can be used to calculate e.g. octets/s from rate ...
80
81 my $octets_per_second = $packets_per_second * AnyEvent::FastPing::icmp4_pktsize;
82
83... or convert kilobit/second to packet rate ...
84
85 my $packets_per_second = $kilobit_per_second
86 * (1000 / 8 / AnyEvent::FastPing::icmp4_pktsize);
87
88etc.
59 89
60=item AnyEvent::FastPing::icmp6_pktsize 90=item AnyEvent::FastPing::icmp6_pktsize
61 91
62Returns the number of bytes each IPv4 ping packet has. 92Like AnyEvent::FastPing::icmp4_pktsize, but for IPv6.
93
94=back
95
96=head1 THE AnyEvent::FastPing CLASS
97
98The AnyEvent::FastPing class represents a single "pinger". A "pinger"
99comes with its own thread to send packets in the background, a rate-limit
100machinery and separate idle/receive callbacks.
101
102The recommended workflow (there are others) is this: 1. create a new
103AnyEvent::FastPing object 2. configure the address lists and ranges to
104ping, also configure an idle callback and optionally a receive callback
1053. C<start> the pinger.
106
107When the pinger has finished pinging all the configured addresses it will
108call the idle callback.
109
110The pinging process works like this: every range has a minimum interval
111between sends, which is used to limit the rate at which hosts in that
112range are being pinged. Distinct ranges are independent of each other,
113which is why there is a per-pinger "global" minimum interval as well.
114
115The pinger sends pings as fats as possible, while both obeying the pinger
116rate limit as well as range limits.
117
118When a range is exhausted, it is removed. When all ranges are exhausted,
119the pinger waits another C<max_rtt> seconds and then exits, causing the
120idle callback to trigger.
121
122Performance: On my 2 GHz Opteron system with a pretty average nvidia
123gigabit network card I can ping around 60k to 200k addresses per second,
124depending on routing decisions.
125
126Example: ping 10.0.0.1-10.0.0.15 with at most 100 packets/s, and
12711.0.0.1-11.0.255.255 with at most 1000 packets/s. Also ping the IPv6
128loopback address 5 times as fast as possible. Do not, however, exceed 1000
129packets/s overall. Also dump each received reply.
130
131 use AnyEvent::Socket;
132 use AnyEvent::FastPing;
133
134 my $done = AnyEvent->condvar;
135
136 my $pinger = new AnyEvent::FastPing;
137
138 $pinger->interval (1/1000);
139 $pinger->max_rtt (0.1); # reasonably fast/reliable network
140
141 $pinger->add_range (v10.0.0.1, v10.0.0.15, 1/100);
142 $pinger->add_range (v11.0.0.1, v11.0.255.255, 1/1000);
143 $pinger->add_hosts ([ (v0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.1) x 5 ]);
144
145 $pinger->on_recv (sub {
146 for (@{ $_[0] }) {
147 printf "%s %g\n", (AnyEvent::Socket::format_address $_->[0]), $_->[1];
148 }
149 });
150
151 $pinger->on_idle (sub {
152 print "done\n";
153 undef $pinger;
154 });
155
156 $pinger->start;
157 $done->wait;
158
159=head2 METHODS
160
161=over 4
162
163=item $pinger = new AnyEvent::FastPing
164
165Creates a new pinger - right now there can be at most C<65536> pingers in
166a process, although that limit might change to something drastically lower
167- you should be stingy with your pinger objects.
63 168
64=cut 169=cut
65 170
66sub new { 171sub new {
67 my ($klass) = @_; 172 my ($klass) = @_;
68 173
174 AnyEvent::detect unless defined $AnyEvent::MODEL;
175
69 _new $klass, (rand 65536), (rand 65536), (rand 65536) 176 _new $klass, (rand 65536), (rand 65536), (rand 65536)
70} 177}
71
72our @IDLE_CB;
73 178
74sub DESTROY { 179sub DESTROY {
75 undef $IDLE_CB[ &id ]; 180 undef $IDLE_CB[ &id ];
76 &_free; 181 &_free;
77} 182}
78 183
184=item $pinger->on_recv ($callback->([[$host, $rtt], ...]))
185
186Registers a callback to be called for ping replies. If no callback has
187been registered than ping replies will be ignored, otherwise this module
188calculates the round trip time, in seconds, for each reply and calls this
189callback.
190
191The callback receives a single argument, which is an array reference
192with an entry for each reply packet (the replies will be batched for
193efficiency). Each member in the array reference is again an array
194reference with exactly two members: the binary host address (4 octets for
195IPv4, 16 for IPv6) and the approximate round trip time, in seconds.
196
197The replies will be passed to the callback as soon as they arrive, and
198this callback can be called many times with batches of replies.
199
200The receive callback will be called whenever a suitable reply arrives,
201whether generated by this pinger or not, whether this pinger is started
202or not. The packets will have a unique 64 bit ID to distinguish them from
203other pinger objects and other generators, but this doesn't help against
204malicious replies.
205
206Note that very high packet rates can overwhelm your process, causing
207replies to be dropped (configure your kernel with long receive queues for
208raw sockets if this is a problem).
209
210Example: register a callback which simply dumps the received data.
211
212 use AnyEvent::Socket;
213
214 $pinger->on_recv (sub {
215 for (@{ $_[0] }) {
216 printf "%s %g\n", (AnyEvent::Socket::format_address $_->[0]), $_->[1];
217 }
218 });
219
220Example: a single ping reply with payload of 1 from C<::1> gets passed
221like this:
222
223 [
224 [ "\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\1", 0.000280141830444336 ]
225 ]
226
227Example: ping replies for C<127.0.0.1> and C<127.0.0.2>:
228
229 [
230 [ "\177\0\0\1", 0.00015711784362793 ],
231 [ "\177\0\0\2", 0.00090184211731 ]
232 ]
233
234=item $pinger->on_idle ($callback->())
235
236Registers a callback to be called when the pinger becomes I<idle>, that
237is, it has been started, has exhausted all ping ranges and waited for
238the C<max_rtt> time. An idle pinger is also stopped, so the callback can
239instantly add new ranges, if it so desires.
240
241=cut
242
79sub on_idle { 243sub on_idle {
80 $IDLE_CB[ &id ] = $_[1]; 244 $IDLE_CB[ &id ] = $_[1];
81} 245}
82 246
83our $THR_RES_W = AE::io $THR_RES_FH, 0, sub { 247=item $pinger->interval ($seconds)
84 sysread $THR_RES_FH, my $buf, 8;
85 248
86 for my $id (unpack "S*", $buf) { 249Configures the minimum interval between packet sends for this pinger - the
87 _stop_id $id; 250pinger will not send packets faster than this rate (or actually 1 / rate),
88 ($IDLE_CB[$id] || sub { })->(); 251even if individual ranges have a lower interval.
89 }
90};
91 252
92for(1..10) { 253A value of C<0> selects the fastest possible speed (currently no faster
93my $p = new AnyEvent::FastPing;#d# 254than 1_000_000 packets/s).
94$p->interval (0);
95$p->max_rtt (0.5);
96#$p->add_range (v127.0.0.1, v127.255.255.254, 0);
97$p->add_range (v1.0.0.1, v1.255.255.254, 0);
98$p->on_idle (my $cv = AE::cv);
99my $cnt;
100$p->on_recv (sub {
101 $cnt++;
102});
103$p->start;
104$cv->recv;
105warn $cnt;
106}
107 255
108=item AnyEvent::FastPing::icmp_ping [ranges...], $send_interval, $payload, \&callback 256=item $pinger->max_rtt ($seconds)
109 257
110Ping the given IPv4 address ranges. Each range is an arrayref of the 258If your idle callback were called instantly after all ranges were
111form C<[lo, hi, interval]>, where C<lo> and C<hi> are octet strings with 259exhausted and you destroyed the object inside (which is common), then
112either 4 octets (for IPv4 addresses) or 16 octets (for IPV6 addresses), 260there would be no chance to receive some replies, as there would be no
113representing the lowest and highest address to ping (you can convert a 261time of the packet to travel over the network.
114dotted-quad IPv4 address to this format by using C<inet_aton $address>. The
115range C<interval> is the minimum time in seconds between pings to the
116given range. If omitted, defaults to C<$send_interval>.
117 262
118The C<$send_interval> is the minimum interval between sending any two 263This can be fixed by starting a timer in the idle callback, or more simply
119packets and is a way to make an overall rate limit. If omitted, pings will 264by selecting a suitable C<max_rtt> value, which should be the maximum time
120be sent as fast as possible. 265you allow a ping packet to travel to its destination and back.
121 266
122The C<$payload> is a 32 bit unsigned integer given as the ICMP ECHO 267The pinger thread automatically waits for this amount of time before becoming idle.
123REQUEST ident and sequence numbers (in unspecified order :).
124 268
125The request will be queued and all requests will be served by a background 269The default is currently C<0.5> seconds, which is usually plenty.
126thread in order. When all ranges have been pinged, the C<callback> will be
127called.
128 270
129Algorithm: Each range has an associated "next time to send packet" 271=item $pinger->add_range ($lo, $hi[, $interval])
130time. The algorithm loops as long as there are ranges with hosts to be
131pinged and always serves the range with the most urgent packet send
132time. It will at most send one packet every C<$send_interval> seconds.
133 272
134This will ensure that pings to the same range are nicely interleaved with 273Ping the IPv4 (or IPv6, but see below) address range, starting at binary
135other ranges - this can help reduce per-subnet bandwidth while maintaining 274address C<$lo> and ending at C<$hi> (both C<$lo> and C<$hi> will be
136an overall high packet rate. 275pinged), generating no more than one ping per C<$interval> seconds (or as
276fast as possible if omitted).
137 277
138The algorithm to send each packet is O(log n) on the number of ranges, so 278You can convert IP addresses from text to binary form by
279using C<AnyEvent::Util::parse_address>, C<Socket::inet_aton>,
280C<Socket6::inet_pton> or any other method that you like :)
281
282The algorithm to select the next address is O(log n) on the number of
139even a large number of ranges (many thousands) is managable. 283ranges, so even a large number of ranges (many thousands) is manageable.
140 284
141No storage is allocated per address. 285No storage is allocated per address.
142 286
143Performance: On my 2 GHz Opteron system with a pretty average nvidia 287Note that, while IPv6 addresses are currently supported, the usefulness of
144gigabit network card I can ping around 60k to 200k adresses per second, 288this option is extremely limited and might be gone in future versions - if
145depending on routing decisions. 289you want to ping a number of IPv6 hosts, better specify them individually
290using the C<add_hosts> method.
146 291
147Example: ping 10.0.0.1-10.0.0.15 with at most 100 packets/s, and 292=item $pinger->add_hosts ([$host...], $interval, $interleave)
14811.0.0.1-11.0.255.255 with at most 1000 packets/s. Do not, however, exceed
1491000 packets/s overall:
150 293
151 my $done = AnyEvent->condvar; 294Similar to C<add_range>, but uses a list of single addresses instead. The
295list is specified as an array reference as first argument. Each entry in
296the array should be a binary host address, either IPv4 or IPv6. If all
297addresses are IPv4 addresses, then a compact IPv4-only format will be used
298to store the list internally.
152 299
153 AnyEvent::FastPing::icmp_ping 300Minimum C<$interval> is the same as for C<add_range> and can be left out.
154 [
155 [v10.0.0.1, v10.0.0.15, .01],
156 [v11.0.0.1, v11.0.255.255, .001],
157 ],
158 .001, 0x12345678,
159 sub {
160 warn "all ranges pinged\n";
161 $done->broadcast;
162 }
163 ;
164 301
165 $done->wait; 302C<$interlave> specifies an increment between addresses: often address
303lists are generated in a way that results in clustering - first all
304addresses from one subnet, then from the next, and so on. To avoid this,
305you can specify an interleave factor. If it is C<1> (the default), then
306every address is pinged in the order specified. If it is C<2>, then only
307every second address will be pinged in the first round, followed by a
308second round with the others. Higher factors will create C<$interleave>
309runs of addresses spaced C<$interleave> indices in the list.
166 310
167=cut 311The special value C<0> selects a (hopefully) suitable interleave factor
312automatically - currently C<256> for lists with less than 65536 addresses,
313and the square root of the list length otherwise.
168 314
169sub icmp_ping($$$&) { 315=item $pinger->start
170# _send_req _req_icmp_ping @_;
171}
172 316
173=item AnyEvent::FastPing::register_cb \&cb 317Start the pinger, unless it is running already. While a pinger is running
318you must not modify the pinger. If you want to change a parameter, you
319have to C<stop> the pinger first.
174 320
175Register a callback that is called for every received ping reply 321The pinger will automatically stop when destroyed.
176(regardless of whether a ping is still in process or not and regardless of
177whether the reply is actually a reply to a ping sent earlier).
178 322
179The code reference gets a single parameter - an arrayref with an 323=item $pinger->stop
180entry for each received packet (replies are being batched for greater
181efficiency). Each packet is represented by an arrayref with three members:
182the source address (an octet string of either 4 (IPv4) or 16 (IPv6) octets
183length), the payload as passed to C<icmp_ping> and the round trip time in
184seconds.
185 324
186Example: register a callback which simply dumps the received data. Since 325Stop the pinger, if it is running. A pinger can be stopped at any time,
187the coderef is created on the fly via sub, it would be hard to unregister 326after which it's current state is preserved - starting it again will
188this callback again :) 327continue where it left off.
189 328
190 AnyEvent::FastPing::register_cb sub {
191 for (@{$_[0]}) {
192 printf "%s %d %g\n",
193 (4 == length $_->[0] ? inet_ntoa $_->[0] : Socket6::inet_ntop (&AF_INET6, $_->[0])),
194 $_->[2],
195 $_->[1];
196 }
197 };
198
199Example: a single ping reply with payload of 1 from C<::1> gets passed
200like this:
201
202 [ [
203 "\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\1",
204 "0.000280141830444336",
205 1
206 ] ]
207
208Example: ping replies for C<127.0.0.1> and C<127.0.0.2>, with a payload of
209C<0x12345678>:
210
211 [
212 [
213 "\177\0\0\1",
214 "0.00015711784362793",
215 305419896
216 ],
217 [
218 "\177\0\0\2",
219 "0.00090184211731",
220 305419896
221 ]
222 ]
223
224=item AnyEvent::FastPing::unregister_cb \&cb
225
226Unregister the callback again (make sure you pass the same codereference
227as to C<register_cb>).
228
229=cut 329=cut
230
231our @CB;
232
233sub register_cb($) {
234 push @CB, $_[0];
235}
236
237sub unregister_cb($) {
238 @CB = grep $_ != $_[0], @CB;
239}
240 330
2411; 3311;
242 332
243=back 333=back
244 334

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines