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.13 by root, Wed Feb 2 19:26:45 2011 UTC

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

Diff Legend

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