ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent-FastPing/README
(Generate patch)

Comparing AnyEvent-FastPing/README (file contents):
Revision 1.3 by root, Sat May 5 23:20:26 2007 UTC vs.
Revision 1.8 by root, Wed Apr 7 14:13:16 2010 UTC

1NAME 1NAME
2 Net::FPing - quickly ping a large number of hosts 2 AnyEvent::FastPing - quickly ping a large number of hosts
3 3
4SYNOPSIS 4SYNOPSIS
5 use Net::FPing; 5 use AnyEvent::FastPing;
6 6
7DESCRIPTION 7DESCRIPTION
8 This module was written for a single purpose only: sendinf ICMP EHCO 8 This module was written for a single purpose only: sending ICMP ECHO
9 REQUEST packets as quickly as possible to a large number of hosts 9 REQUEST packets as quickly as possible to a large number of hosts
10 (thousands to millions). 10 (thousands to millions).
11 11
12 It employs a sending thread and is fully event-driven (using AnyEvent), 12 It employs a sending thread and is fully event-driven (using AnyEvent),
13 so you have to run an event model supported by AnyEvent to use this 13 so you have to run an event model supported by AnyEvent to use this
14 module. 14 module.
15 15
16FUNCTIONS 16FUNCTIONS
17 Net::FPing::ipv4_supported 17 AnyEvent::FastPing::ipv4_supported
18 Returns true if IPv4 is supported in this module and on this system. 18 Returns true if IPv4 is supported in this module and on this system.
19 19
20 Net::FPing::ipv6_supported 20 AnyEvent::FastPing::ipv6_supported
21 Returns true if IPv6 is supported in this module and on this system. 21 Returns true if IPv6 is supported in this module and on this system.
22 22
23 Net::FPing::icmp4_pktsize 23 AnyEvent::FastPing::icmp4_pktsize
24 Returns the number of bytes each IPv4 ping packet has. 24 Returns the number of bytes each IPv4 ping packet has.
25 25
26 Net::FPing::icmp6_pktsize 26 AnyEvent::FastPing::icmp6_pktsize
27 Returns the number of bytes each IPv4 ping packet has. 27 Returns the number of bytes each IPv4 ping packet has.
28 28
29 Net::FPing::icmp_ping [ranges...], $send_interval, $payload, \&callback 29 AnyEvent::FastPing::icmp_ping [ranges...], $send_interval, $payload,
30 \&callback
30 Ping the given IPv4 address ranges. Each range is an arrayref of the 31 Ping the given IPv4 address ranges. Each range is an arrayref of the
31 form "[lo, hi, interval]", where "lo" and "hi" are octet strings 32 form "[lo, hi, interval]", where "lo" and "hi" are octet strings
32 with either 4 octets (for IPv4 addresses) or 16 octets (for IPV6 33 with either 4 octets (for IPv4 addresses) or 16 octets (for IPV6
33 addresses), representing the lowest and highest address to ping (you 34 addresses), representing the lowest and highest address to ping (you
34 can convert a dotted-quad IPv4 address to this format by using 35 can convert a dotted-quad IPv4 address to this format by using
… …
36 seconds between pings to the given range. If omitted, defaults to 37 seconds between pings to the given range. If omitted, defaults to
37 $send_interval. 38 $send_interval.
38 39
39 The $send_interval is the minimum interval between sending any two 40 The $send_interval is the minimum interval between sending any two
40 packets and is a way to make an overall rate limit. If omitted, 41 packets and is a way to make an overall rate limit. If omitted,
41 pings will be send as fast as possible. 42 pings will be sent as fast as possible.
42 43
43 The $payload is a 32 bit unsigned integer given as the ICMP ECHO 44 The $payload is a 32 bit unsigned integer given as the ICMP ECHO
44 REQUEST ident and sequence numbers (in unspecified order :). 45 REQUEST ident and sequence numbers (in unspecified order :).
45 46
46 The request will be queued and all requests will be served by a 47 The request will be queued and all requests will be served by a
… …
71 11.0.0.1-11.0.255.255 with at most 1000 packets/s. Do not, however, 72 11.0.0.1-11.0.255.255 with at most 1000 packets/s. Do not, however,
72 exceed 1000 packets/s overall: 73 exceed 1000 packets/s overall:
73 74
74 my $done = AnyEvent->condvar; 75 my $done = AnyEvent->condvar;
75 76
76 Net::FPing::icmp_ping 77 AnyEvent::FastPing::icmp_ping
78 [
77 [v10.0.0.1, v10.0.0.15, .01], 79 [v10.0.0.1, v10.0.0.15, .01],
78 [v11.0.0.1, v11.0.255.255, .001], 80 [v11.0.0.1, v11.0.255.255, .001],
81 ],
79 .001, 0x12345678, 82 .001, 0x12345678,
80 sub { 83 sub {
81 warn "all ranges pinged\n"; 84 warn "all ranges pinged\n";
82 $done->broadcast; 85 $done->broadcast;
83 } 86 }
84 ; 87 ;
85 88
86 $done->wait; 89 $done->wait;
87 90
88 Net::FPing::register_cb \&cb 91 AnyEvent::FastPing::register_cb \&cb
89 Register a callback that is called for every received ping reply 92 Register a callback that is called for every received ping reply
90 (regardless of whether a ping is still in process or not and 93 (regardless of whether a ping is still in process or not and
91 regardless of whether the reply is actually a reply ot a ping sent 94 regardless of whether the reply is actually a reply to a ping sent
92 earlier). 95 earlier).
93 96
94 The code reference gets a single parameter - an arrayref with an 97 The code reference gets a single parameter - an arrayref with an
95 entry for each received packet (replies are beign batched for 98 entry for each received packet (replies are being batched for
96 greater efficiency). Each packet is represented by an arrayref with 99 greater efficiency). Each packet is represented by an arrayref with
97 three members: the source address (an octet string of either 4 100 three members: the source address (an octet string of either 4
98 (IPv4) or 16 (IPv6) octets length), the payload as passed to 101 (IPv4) or 16 (IPv6) octets length), the payload as passed to
99 "icmp_ping" and the round trip time in seconds. 102 "icmp_ping" and the round trip time in seconds.
103
104 Example: register a callback which simply dumps the received data.
105 Since the coderef is created on the fly via sub, it would be hard to
106 unregister this callback again :)
107
108 AnyEvent::FastPing::register_cb sub {
109 for (@{$_[0]}) {
110 printf "%s %d %g\n",
111 (4 == length $_->[0] ? inet_ntoa $_->[0] : Socket6::inet_ntop (&AF_INET6, $_->[0])),
112 $_->[2],
113 $_->[1];
114 }
115 };
100 116
101 Example: a single ping reply with payload of 1 from "::1" gets 117 Example: a single ping reply with payload of 1 from "::1" gets
102 passed like this: 118 passed like this:
103 119
104 [ [ 120 [ [
… …
121 "0.00090184211731", 137 "0.00090184211731",
122 305419896 138 305419896
123 ] 139 ]
124 ] 140 ]
125 141
126 Net::FPing::unregister_cb \&cb 142 AnyEvent::FastPing::unregister_cb \&cb
127 Unregister the callback again (make sure you pass the same 143 Unregister the callback again (make sure you pass the same
128 codereference as to "register_cb"). 144 codereference as to "register_cb").
129 145
130AUTHOR 146AUTHOR
131 Marc Lehmann <schmorp@schmorp.de> 147 Marc Lehmann <schmorp@schmorp.de>
132 http://home.schmorp.de/ 148 http://home.schmorp.de/
133 149
134AUTHOR 150LICENSE
135 This software is distributed under the GENERAL PUBLIC LICENSE, 151 This software is distributed under the GENERAL PUBLIC LICENSE, version 2
136 version 2 or any later. 152 or any later version or, at your option, the Artistic License.
137 153

Diff Legend

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