[ViewVC] Diff of: cvs/AnyEvent-FastPing/FastPing.pm

Comparing AnyEvent-FastPing/FastPing.pm (file contents):
Revision 1.10 by root, Sat Jan 29 23:55:37 2011 UTC vs.
Revision 1.13 by root, Wed Feb 2 19:26:45 2011 UTC

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

Diff Legend

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

Comparing AnyEvent-FastPing/FastPing.pm (file contents): Revision 1.10 by root, Sat Jan 29 23:55:37 2011 UTC vs. Revision 1.13 by root, Wed Feb 2 19:26:45 2011 UTC

Diff Legend

Comparing AnyEvent-FastPing/FastPing.pm (file contents):
Revision 1.10 by root, Sat Jan 29 23:55:37 2011 UTC vs.
Revision 1.13 by root, Wed Feb 2 19:26:45 2011 UTC