AnyEvent-FastPing/FPing.pm

=head1 NAME

Net::FPing - quickly ping a large number of hosts

=head1 SYNOPSIS

 use Net::FPing;

=head1 DESCRIPTION

This module was written for a single purpose only: sendinf ICMP EHCO
REQUEST packets as quickly as possible to a large number of hosts
(thousands to millions).

It employs a sending thread and is fully event-driven (using AnyEvent), so
you have to run an event model supported by AnyEvent to use this module.

=head1 FUNCTIONS

=over 4

=cut

package Net::FPing;

use strict;
no warnings;

use AnyEvent;

BEGIN {
   our $VERSION = '0.9';
   our @ISA = qw(Exporter);

   require Exporter;
   #Exporter::export_ok_tags (keys %EXPORT_TAGS);

   require XSLoader;
   XSLoader::load (__PACKAGE__, $VERSION);
}

our ($THR_REQ_FD, $THR_RES_FD, $ICMP4_FD, $ICMP6_FD);

our $THR_REQ_FH; open $THR_REQ_FH, ">&=$THR_REQ_FD" or die "FATAL: cannot fdopen";
our $THR_RES_FH; open $THR_RES_FH, "<&=$THR_RES_FD" or die "FATAL: cannot fdopen";

our $THR_REQ_W;
our $THR_RES_W = AnyEvent->io (fh => $THR_RES_FH, poll => 'r', cb => sub {
   my $sv = _read_res
      or return;

   $sv->();
});

our $THR_REQ_BUF;

sub _send_req($) {
   $THR_REQ_BUF .= $_[0];

   $THR_REQ_W ||= AnyEvent->io (fh => $THR_REQ_FH, poll => 'w', cb => sub {
      my $len = syswrite $THR_REQ_FH, $THR_REQ_BUF;
      substr $THR_REQ_BUF, 0, $len, "";

      undef $THR_REQ_W unless length $THR_REQ_BUF;
   });
}

=item Net::FPing::ipv4_supported

Returns true if IPv4 is supported in this module and on this system.

=item Net::FPing::ipv6_supported

Returns true if IPv6 is supported in this module and on this system.

=item Net::FPing::icmp4_pktsize

Returns the number of bytes each IPv4 ping packet has.

=item Net::FPing::icmp6_pktsize

Returns the number of bytes each IPv4 ping packet has.

=item Net::FPing::icmp_ping [ranges...], $send_interval, $payload, \&callback

Ping the given IPv4 address ranges. Each range is an arrayref of the
form C<[lo, hi, interval]>, where C<lo> and C<hi> are octet strings with
either 4 octets (for IPv4 addresses) or 16 octets (for IPV6 addresses),
representing the lowest and highest address to ping (you can convert a
dotted-quad IPv4 address to this format by using C<inet_aton $address>. The
range C<interval> is the minimum time in seconds between pings to the
given range. If omitted, defaults to C<$send_interval>.

The C<$send_interval> is the minimum interval between sending any two
packets and is a way to make an overall rate limit. If omitted, pings will
be send as fast as possible.

The C<$payload> is a 32 bit unsigned integer given as the ICMP ECHO
REQUEST ident and sequence numbers (in unspecified order :).

The request will be queued and all requests will be served by a background
thread in order. When all ranges have been pinged, the C<callback> will be
called.

Algorithm: Each range has an associated "next time to send packet"
time. The algorithm loops as long as there are ranges with hosts to be
pinged and always serves the range with the most urgent packet send
time. It will at most send one packet every C<$send_interval> seconds.

This will ensure that pings to the same range are nicely interleaved with
other ranges - this can help reduce per-subnet bandwidth while maintaining
an overall high packet rate.

The algorithm to send each packet is O(log n) on the number of ranges, so
even a large number of ranges (many thousands) is managable.

No storage is allocated per address.

Performance: On my 2 GHz Opteron system with a pretty average nvidia
gigabit network card I can ping around 60k to 200k adresses per second,
depending on routing decisions.

Example: ping 10.0.0.1-10.0.0.15 with at most 100 packets/s, and
11.0.0.1-11.0.255.255 with at most 1000 packets/s. Do not, however, exceed
1000 packets/s overall:

   my $done = AnyEvent->condvar;

   Net::FPing::icmp_ping
      [v10.0.0.1, v10.0.0.15, .01],
      [v11.0.0.1, v11.0.255.255, .001],
      .001, 0x12345678,
      sub {
         warn "all ranges pinged\n";
         $done->broadcast;
      }
   ;

   $done->wait;

=cut

sub icmp_ping($$$&) {
   _send_req _req_icmp_ping @_;
}

our $ICMP4_FH;
our $ICMP4_W = (open $ICMP4_FH, "<&=$ICMP4_FD") && AnyEvent->io (fh => $ICMP4_FH, poll => 'r', cb => \&_recv_icmp4);
our $ICMP6_FH;
our $ICMP6_W = (open $ICMP6_FH, "<&=$ICMP6_FD") && AnyEvent->io (fh => $ICMP6_FH, poll => 'r', cb => \&_recv_icmp6);

=item Net::FPing::register_cb \&cb

Register a callback that is called for every received ping reply
(regardless of whether a ping is still in process or not and regardless of
whether the reply is actually a reply ot a ping sent earlier).

The code reference gets a single parameter - an arrayref with an
entry for each received packet (replies are beign batched for greater
efficiency). Each packet is represented by an arrayref with three members:
the source address (an octet string of either 4 (IPv4) or 16 (IPv6) octets
length), the payload as passed to C<icmp_ping> and the round trip time in
seconds.

Example: a single ping reply with payload of 1 from C<::1> gets passed
like this:

   [ [
     "\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\1",
     "0.000280141830444336",
     1
   ] ]

Example: ping replies for C<127.0.0.1> and C<127.0.0.2>, with a payload of
C<0x12345678>:

   [
      [
        "\177\0\0\1",
        "0.00015711784362793",
        305419896
      ],
      [
        "\177\0\0\2",
        "0.00090184211731",
        305419896
      ]
   ]

=item Net::FPing::unregister_cb \&cb

Unregister the callback again (make sure you pass the same codereference
as to C<register_cb>).

=cut

our @CB;

sub register_cb(&) {
   push @CB, $_[0];
}

sub unregister_cb($) {
   @CB = grep $_ != $_[0], @CB;
}

1;

=back

=head1 AUTHOR

 Marc Lehmann <schmorp@schmorp.de>
 http://home.schmorp.de/

=head1 AUTHOR

 This software is distributed under the GENERAL PUBLIC LICENSE, version 2
 or any later version or, at your option, the Artistic License.

=cut

Revision:	1.8
Committed:	Tue May 15 19:25:08 2007 UTC (17 years ago) by root
Branch:	MAIN
CVS Tags:	rel-0_9
Changes since 1.7:	+3 -3 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	=head1 NAME
2
3			Net::FPing - quickly ping a large number of hosts
4
5			=head1 SYNOPSIS
6
7			use Net::FPing;
8
9			=head1 DESCRIPTION
10
11	root	1.6	This module was written for a single purpose only: sendinf ICMP EHCO
12	root	1.1	REQUEST packets as quickly as possible to a large number of hosts
13			(thousands to millions).
14
15			It employs a sending thread and is fully event-driven (using AnyEvent), so
16			you have to run an event model supported by AnyEvent to use this module.
17
18	root	1.3	=head1 FUNCTIONS
19
20	root	1.1	=over 4
21
22			=cut
23
24			package Net::FPing;
25
26	root	1.3	use strict;
27			no warnings;
28
29	root	1.1	use AnyEvent;
30
31			BEGIN {
32	root	1.8	our $VERSION = '0.9';
33	root	1.3	our @ISA = qw(Exporter);
34	root	1.1
35			require Exporter;
36	root	1.3	#Exporter::export_ok_tags (keys %EXPORT_TAGS);
37	root	1.1
38			require XSLoader;
39	root	1.3	XSLoader::load (__PACKAGE__, $VERSION);
40	root	1.1	}
41
42	root	1.3	our ($THR_REQ_FD, $THR_RES_FD, $ICMP4_FD, $ICMP6_FD);
43
44	root	1.1	our $THR_REQ_FH; open $THR_REQ_FH, ">&=$THR_REQ_FD" or die "FATAL: cannot fdopen";
45			our $THR_RES_FH; open $THR_RES_FH, "<&=$THR_RES_FD" or die "FATAL: cannot fdopen";
46
47			our $THR_REQ_W;
48			our $THR_RES_W = AnyEvent->io (fh => $THR_RES_FH, poll => 'r', cb => sub {
49			my $sv = _read_res
50			or return;
51
52			$sv->();
53			});
54
55	root	1.3	our $THR_REQ_BUF;
56	root	1.1
57			sub _send_req($) {
58			$THR_REQ_BUF .= $_[0];
59
60			$THR_REQ_W \|\|= AnyEvent->io (fh => $THR_REQ_FH, poll => 'w', cb => sub {
61			my $len = syswrite $THR_REQ_FH, $THR_REQ_BUF;
62			substr $THR_REQ_BUF, 0, $len, "";
63
64			undef $THR_REQ_W unless length $THR_REQ_BUF;
65			});
66			}
67
68	root	1.2	=item Net::FPing::ipv4_supported
69
70			Returns true if IPv4 is supported in this module and on this system.
71
72			=item Net::FPing::ipv6_supported
73
74			Returns true if IPv6 is supported in this module and on this system.
75
76	root	1.5	=item Net::FPing::icmp4_pktsize
77	root	1.2
78			Returns the number of bytes each IPv4 ping packet has.
79
80	root	1.5	=item Net::FPing::icmp6_pktsize
81	root	1.2
82			Returns the number of bytes each IPv4 ping packet has.
83
84			=item Net::FPing::icmp_ping [ranges...], $send_interval, $payload, \&callback
85	root	1.1
86			Ping the given IPv4 address ranges. Each range is an arrayref of the
87			form C<[lo, hi, interval]>, where C<lo> and C<hi> are octet strings with
88			either 4 octets (for IPv4 addresses) or 16 octets (for IPV6 addresses),
89			representing the lowest and highest address to ping (you can convert a
90			dotted-quad IPv4 address to this format by using C<inet_aton $address>. The
91			range C<interval> is the minimum time in seconds between pings to the
92			given range. If omitted, defaults to C<$send_interval>.
93
94			The C<$send_interval> is the minimum interval between sending any two
95			packets and is a way to make an overall rate limit. If omitted, pings will
96			be send as fast as possible.
97
98	root	1.4	The C<$payload> is a 32 bit unsigned integer given as the ICMP ECHO
99			REQUEST ident and sequence numbers (in unspecified order :).
100	root	1.1
101			The request will be queued and all requests will be served by a background
102			thread in order. When all ranges have been pinged, the C<callback> will be
103			called.
104
105			Algorithm: Each range has an associated "next time to send packet"
106			time. The algorithm loops as long as there are ranges with hosts to be
107			pinged and always serves the range with the most urgent packet send
108	root	1.6	time. It will at most send one packet every C<$send_interval> seconds.
109
110			This will ensure that pings to the same range are nicely interleaved with
111			other ranges - this can help reduce per-subnet bandwidth while maintaining
112			an overall high packet rate.
113
114			The algorithm to send each packet is O(log n) on the number of ranges, so
115			even a large number of ranges (many thousands) is managable.
116
117			No storage is allocated per address.
118	root	1.1
119	root	1.3	Performance: On my 2 GHz Opteron system with a pretty average nvidia
120	root	1.1	gigabit network card I can ping around 60k to 200k adresses per second,
121			depending on routing decisions.
122
123			Example: ping 10.0.0.1-10.0.0.15 with at most 100 packets/s, and
124			11.0.0.1-11.0.255.255 with at most 1000 packets/s. Do not, however, exceed
125	root	1.2	1000 packets/s overall:
126	root	1.1
127	root	1.3	my $done = AnyEvent->condvar;
128
129	root	1.2	Net::FPing::icmp_ping
130	root	1.1	[v10.0.0.1, v10.0.0.15, .01],
131			[v11.0.0.1, v11.0.255.255, .001],
132			.001, 0x12345678,
133			sub {
134			warn "all ranges pinged\n";
135	root	1.3	$done->broadcast;
136	root	1.1	}
137			;
138
139	root	1.3	$done->wait;
140
141	root	1.1	=cut
142
143	root	1.2	sub icmp_ping($$$&) {
144			_send_req _req_icmp_ping @_;
145	root	1.1	}
146
147			our $ICMP4_FH;
148			our $ICMP4_W = (open $ICMP4_FH, "<&=$ICMP4_FD") && AnyEvent->io (fh => $ICMP4_FH, poll => 'r', cb => \&_recv_icmp4);
149			our $ICMP6_FH;
150			our $ICMP6_W = (open $ICMP6_FH, "<&=$ICMP6_FD") && AnyEvent->io (fh => $ICMP6_FH, poll => 'r', cb => \&_recv_icmp6);
151
152	root	1.4	=item Net::FPing::register_cb \&cb
153
154			Register a callback that is called for every received ping reply
155			(regardless of whether a ping is still in process or not and regardless of
156			whether the reply is actually a reply ot a ping sent earlier).
157
158			The code reference gets a single parameter - an arrayref with an
159			entry for each received packet (replies are beign batched for greater
160			efficiency). Each packet is represented by an arrayref with three members:
161			the source address (an octet string of either 4 (IPv4) or 16 (IPv6) octets
162			length), the payload as passed to C<icmp_ping> and the round trip time in
163			seconds.
164
165			Example: a single ping reply with payload of 1 from C<::1> gets passed
166			like this:
167
168			[ [
169			"\0\0\0\0\0\0\0\0\0\0\0\0\0\0\0\1",
170			"0.000280141830444336",
171			1
172			] ]
173
174			Example: ping replies for C<127.0.0.1> and C<127.0.0.2>, with a payload of
175			C<0x12345678>:
176
177			[
178			[
179			"\177\0\0\1",
180			"0.00015711784362793",
181			305419896
182			],
183			[
184			"\177\0\0\2",
185			"0.00090184211731",
186			305419896
187			]
188			]
189
190			=item Net::FPing::unregister_cb \&cb
191
192			Unregister the callback again (make sure you pass the same codereference
193			as to C<register_cb>).
194
195			=cut
196
197			our @CB;
198
199			sub register_cb(&) {
200			push @CB, $_[0];
201			}
202
203			sub unregister_cb($) {
204			@CB = grep $_ != $_[0], @CB;
205			}
206
207	root	1.2	1;
208	root	1.1
209	root	1.2	=back
210	root	1.1
211			=head1 AUTHOR
212
213			Marc Lehmann <schmorp@schmorp.de>
214			http://home.schmorp.de/
215
216			=head1 AUTHOR
217
218	root	1.8	This software is distributed under the GENERAL PUBLIC LICENSE, version 2
219			or any later version or, at your option, the Artistic License.
220	root	1.1
221			=cut
222