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

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.18 by root, Fri Nov 11 01:18:56 2016 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.18 by root, Fri Nov 11 01:18:56 2016 UTC