… | |
… | |
10 | |
10 | |
11 | This module was written for a single purpose only: sending ICMP ECHO |
11 | This module was written for a single purpose only: sending ICMP ECHO |
12 | REQUEST packets as quickly as possible to a large number of hosts |
12 | REQUEST packets as quickly as possible to a large number of hosts |
13 | (thousands to millions). |
13 | (thousands to millions). |
14 | |
14 | |
15 | It employs a sending thread and is fully event-driven (using AnyEvent), so |
15 | It employs a separate thread and is fully event-driven (using AnyEvent), |
16 | you have to run an event model supported by AnyEvent to use this module. |
16 | so you have to run an event model supported by AnyEvent to use this |
|
|
17 | module. |
17 | |
18 | |
18 | =head1 FUNCTIONS |
19 | =head1 FUNCTIONS |
19 | |
20 | |
20 | =over 4 |
21 | =over 4 |
21 | |
22 | |
… | |
… | |
101 | When a range is exhausted, it is removed. When all ranges are exhausted, |
102 | When a range is exhausted, it is removed. When all ranges are exhausted, |
102 | the pinger waits another C<max_rtt> seconds and then exits, causing the |
103 | the pinger waits another C<max_rtt> seconds and then exits, causing the |
103 | idle callback to trigger. |
104 | idle callback to trigger. |
104 | |
105 | |
105 | Performance: On my 2 GHz Opteron system with a pretty average nvidia |
106 | Performance: On my 2 GHz Opteron system with a pretty average nvidia |
106 | gigabit network card I can ping around 60k to 200k adresses per second, |
107 | gigabit network card I can ping around 60k to 200k addresses per second, |
107 | depending on routing decisions. |
108 | depending on routing decisions. |
108 | |
109 | |
109 | Example: ping 10.0.0.1-10.0.0.15 with at most 100 packets/s, and |
110 | Example: ping 10.0.0.1-10.0.0.15 with at most 100 packets/s, and |
110 | 11.0.0.1-11.0.255.255 with at most 1000 packets/s. Also ping the IPv6 |
111 | 11.0.0.1-11.0.255.255 with at most 1000 packets/s. Also ping the IPv6 |
111 | loopback address 5 times as fast as possible. Do not, however, exceed 1000 |
112 | loopback address 5 times as fast as possible. Do not, however, exceed 1000 |
112 | packets/s overall. Dump each received reply: |
113 | packets/s overall. Also dump each received reply. |
113 | |
114 | |
114 | use AnyEvent::Socket; |
115 | use AnyEvent::Socket; |
115 | use AnyEvent::FastPing; |
116 | use AnyEvent::FastPing; |
116 | |
117 | |
117 | my $done = AnyEvent->condvar; |
118 | my $done = AnyEvent->condvar; |
… | |
… | |
144 | =over 4 |
145 | =over 4 |
145 | |
146 | |
146 | =item $pinger = new AnyEvent::FastPing |
147 | =item $pinger = new AnyEvent::FastPing |
147 | |
148 | |
148 | Creates a new pinger - right now there can be at most C<65536> pingers in |
149 | Creates a new pinger - right now there can be at most C<65536> pingers in |
149 | a process, although that limit might change to somethind drastically lower |
150 | a process, although that limit might change to something drastically lower |
150 | - you should be stringy with your pinger objects. |
151 | - you should be stingy with your pinger objects. |
151 | |
152 | |
152 | =cut |
153 | =cut |
153 | |
154 | |
154 | sub new { |
155 | sub new { |
155 | my ($klass) = @_; |
156 | my ($klass) = @_; |
… | |
… | |
164 | &_free; |
165 | &_free; |
165 | } |
166 | } |
166 | |
167 | |
167 | =item $pinger->on_recv ($callback->([[$host, $rtt], ...])) |
168 | =item $pinger->on_recv ($callback->([[$host, $rtt], ...])) |
168 | |
169 | |
169 | Registeres a callback to be called for ping replies. If no callback has |
170 | Registers a callback to be called for ping replies. If no callback has |
170 | been registered than ping replies will be ignored, otherwise this module |
171 | been registered than ping replies will be ignored, otherwise this module |
171 | calculates the round trip time, in seconds, for each reply and calls this |
172 | calculates the round trip time, in seconds, for each reply and calls this |
172 | callback. |
173 | callback. |
173 | |
174 | |
174 | The callback receives a single argument, which is an array reference |
175 | The callback receives a single argument, which is an array reference |
175 | with an entry for each reply packet (the replies will be batched for |
176 | with an entry for each reply packet (the replies will be batched for |
176 | efficiency). Each member in the array reference is again an array |
177 | efficiency). Each member in the array reference is again an array |
177 | reference with exactly two members: the binary host addresss (4 octets for |
178 | reference with exactly two members: the binary host address (4 octets for |
178 | IPv4, 16 for IPv6) and the approximate round trip time, in seconds. |
179 | IPv4, 16 for IPv6) and the approximate round trip time, in seconds. |
179 | |
180 | |
180 | The replies will be passed to the callback as soon as they arrive, and |
181 | The replies will be passed to the callback as soon as they arrive, and |
181 | this callback can be called many times with batches of replies. |
182 | this callback can be called many times with batches of replies. |
182 | |
183 | |
… | |
… | |
196 | |
197 | |
197 | $pinger->on_recv (sub { |
198 | $pinger->on_recv (sub { |
198 | for (@{ $_[0] }) { |
199 | for (@{ $_[0] }) { |
199 | printf "%s %g\n", (AnyEvent::Socket::format_address $_->[0]), $_->[1]; |
200 | printf "%s %g\n", (AnyEvent::Socket::format_address $_->[0]), $_->[1]; |
200 | } |
201 | } |
201 | }; |
202 | }); |
202 | |
203 | |
203 | Example: a single ping reply with payload of 1 from C<::1> gets passed |
204 | Example: a single ping reply with payload of 1 from C<::1> gets passed |
204 | like this: |
205 | like this: |
205 | |
206 | |
206 | [ |
207 | [ |
… | |
… | |
237 | }; |
238 | }; |
238 | |
239 | |
239 | =item $pinger->interval ($seconds) |
240 | =item $pinger->interval ($seconds) |
240 | |
241 | |
241 | Configures the minimum interval between packet sends for this pinger - the |
242 | Configures the minimum interval between packet sends for this pinger - the |
242 | pinger will not send packets faster than this rate (or atcually 1 / rate), |
243 | pinger will not send packets faster than this rate (or actually 1 / rate), |
243 | even if individual ranges have a lower interval. |
244 | even if individual ranges have a lower interval. |
244 | |
245 | |
245 | A value of C<0> selects the fastests possible speed (currently no faster |
246 | A value of C<0> selects the fastest possible speed (currently no faster |
246 | than 1_000_000 packets/s). |
247 | than 1_000_000 packets/s). |
247 | |
248 | |
248 | =item $pinger->max_rtt ($seconds) |
249 | =item $pinger->max_rtt ($seconds) |
249 | |
250 | |
250 | If your idle callback were called instantly after all ranges were |
251 | If your idle callback were called instantly after all ranges were |
251 | exhausted and you destroyed the object inside (which is common), then |
252 | exhausted and you destroyed the object inside (which is common), then |
252 | there would be no chance to receive some replies, as there would be no |
253 | there would be no chance to receive some replies, as there would be no |
253 | time fo the packet to travel over the network. |
254 | time of the packet to travel over the network. |
254 | |
255 | |
255 | This can be fixed by starting a timer in the idle callback, or more simply |
256 | This can be fixed by starting a timer in the idle callback, or more simply |
256 | by selecting a suitable C<max_rtt> value, which should be the maximum time |
257 | by selecting a suitable C<max_rtt> value, which should be the maximum time |
257 | you allow a ping packet to travel to its destinazion and back. |
258 | you allow a ping packet to travel to its destination and back. |
258 | |
259 | |
259 | The pinger thread automatically waits for this amount of time before becoming idle. |
260 | The pinger thread automatically waits for this amount of time before becoming idle. |
260 | |
261 | |
261 | The default is currently C<0.5> seconds, which is usually plenty. |
262 | The default is currently C<0.5> seconds, which is usually plenty. |
262 | |
263 | |
… | |
… | |
270 | You can convert IP addresses from text to binary form by |
271 | You can convert IP addresses from text to binary form by |
271 | using C<AnyEvent::Util::parse_address>, C<Socket::inet_aton>, |
272 | using C<AnyEvent::Util::parse_address>, C<Socket::inet_aton>, |
272 | C<Socket6::inet_pton> or any other method that you like :) |
273 | C<Socket6::inet_pton> or any other method that you like :) |
273 | |
274 | |
274 | The algorithm to select the next address is O(log n) on the number of |
275 | The algorithm to select the next address is O(log n) on the number of |
275 | ranges, so even a large number of ranges (many thousands) is managable. |
276 | ranges, so even a large number of ranges (many thousands) is manageable. |
276 | |
277 | |
277 | No storage is allocated per address. |
278 | No storage is allocated per address. |
278 | |
279 | |
279 | Note that, while IPv6 addresses are currently supported, the usefulness of |
280 | Note that, while IPv6 addresses are currently supported, the usefulness of |
280 | this option is extremely limited and might be gone in future versions - if |
281 | this option is extremely limited and might be gone in future versions - if |