view release on metacpan or  search on metacpan

README  view on Meta::CPAN

        octets for IPv4, 16 for IPv6) and the approximate round trip time,
        in seconds.

        The replies will be passed to the callback as soon as they arrive,
        and this callback can be called many times with batches of replies.

        The receive callback will be called whenever a suitable reply
        arrives, whether generated by this pinger or not, whether this
        pinger is started or not. The packets will have a unique 64 bit ID
        to distinguish them from other pinger objects and other generators,
        but this doesn't help against malicious replies.

        Note that very high packet rates can overwhelm your process, causing
        replies to be dropped (configure your kernel with long receive
        queues for raw sockets if this is a problem).

        Example: register a callback which simply dumps the received data.

           use AnyEvent::Socket;

           $pinger->on_recv (sub {
              for (@{ $_[0] }) {
                 printf "%s %g\n", (AnyEvent::Socket::format_address $_->[0]), $_->[1];
              }
           });

        Example: a single ping reply with payload of 1 from "::1" gets
        passed like this:

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

        Example: ping replies for 127.0.0.1 and 127.0.0.2:

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

    $pinger->on_idle ($callback->())
        Registers a callback to be called when the pinger becomes *idle*,
        that is, it has been started, has exhausted all ping ranges and
        waited for the "max_rtt" time. An idle pinger is also stopped, so
        the callback can instantly add new ranges, if it so desires.

    $pinger->interval ($seconds)
        Configures the minimum interval between packet sends for this pinger
        - the pinger will not send packets faster than this rate (or
        actually 1 / rate), even if individual ranges have a lower interval.

        A value of 0 selects the fastest possible speed (currently no faster
        than 1_000_000 packets/s).

    $pinger->max_rtt ($seconds)
        If your idle callback were called instantly after all ranges were
        exhausted and you destroyed the object inside (which is common),
        then there would be no chance to receive some replies, as there
        would be no time of the packet to travel over the network.

        This can be fixed by starting a timer in the idle callback, or more
        simply by selecting a suitable "max_rtt" value, which should be the
        maximum time you allow a ping packet to travel to its destination
        and back.

        The pinger thread automatically waits for this amount of time before
        becoming idle.

        The default is currently 0.5 seconds, which is usually plenty.

    $pinger->add_range ($lo, $hi[, $interval])
        Ping the IPv4 (or IPv6, but see below) address range, starting at
        binary address $lo and ending at $hi (both $lo and $hi will be
        pinged), generating no more than one ping per $interval seconds (or
        as fast as possible if omitted).

        You can convert IP addresses from text to binary form by using
        "AnyEvent::Util::parse_address", "Socket::inet_aton",
        "Socket6::inet_pton" or any other method that you like :)

        The algorithm to select the next address is O(log n) on the number
        of ranges, so even a large number of ranges (many thousands) is
        manageable.

        No storage is allocated per address.

        Note that, while IPv6 addresses are currently supported, the
        usefulness of this option is extremely limited and might be gone in
        future versions - if you want to ping a number of IPv6 hosts, better
        specify them individually using the "add_hosts" method.

    $pinger->add_hosts ([$host...], $interval, $interleave)
        Similar to "add_range", but uses a list of single addresses instead.
        The list is specified as an array reference as first argument. Each
        entry in the array should be a binary host address, either IPv4 or
        IPv6. If all addresses are IPv4 addresses, then a compact IPv4-only
        format will be used to store the list internally.

        Minimum $interval is the same as for "add_range" and can be left
        out.

        $interlave specifies an increment between addresses: often address
        lists are generated in a way that results in clustering - first all
        addresses from one subnet, then from the next, and so on. To avoid
        this, you can specify an interleave factor. If it is 1 (the
        default), then every address is pinged in the order specified. If it
        is 2, then only every second address will be pinged in the first
        round, followed by a second round with the others. Higher factors
        will create $interleave runs of addresses spaced $interleave indices
        in the list.

        The special value 0 selects a (hopefully) suitable interleave factor
        automatically - currently 256 for lists with less than 65536
        addresses, and the square root of the list length otherwise.

    $pinger->start
        Start the pinger, unless it is running already. While a pinger is
        running you must not modify the pinger. If you want to change a
        parameter, you have to "stop" the pinger first.

        The pinger will automatically stop when destroyed.