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

Comparing AnyEvent-FastPing/FastPing.pm (file contents):
Revision 1.9 by root, Sun Jan 16 11:48:15 2011 UTC vs.
Revision 1.19 by root, Sat Nov 12 01:20:46 2016 UTC

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

Diff Legend

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

Comparing AnyEvent-FastPing/FastPing.pm (file contents): Revision 1.9 by root, Sun Jan 16 11:48:15 2011 UTC vs. Revision 1.19 by root, Sat Nov 12 01:20:46 2016 UTC

Diff Legend

Comparing AnyEvent-FastPing/FastPing.pm (file contents):
Revision 1.9 by root, Sun Jan 16 11:48:15 2011 UTC vs.
Revision 1.19 by root, Sat Nov 12 01:20:46 2016 UTC