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

Diff Legend

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