NAME

AnyEvent::Ping::TCP - Asynchronous and Synchronous TCP ping functions.

SYNOPSIS

  use AnyEvent::Ping::TCP;
  
  # Synchronous TCP Ping
  my $latency = tcp_ping 'www.google.co.nz', 80;
  
  # Asynchronous TCP Ping
  tcp_ping_syn 'www.google.co.nz', 80;
  
  # Sometime later
  my $latency = tcp_ping_ack 'www.google.co.nz', 80;
  

DESCRIPTION

This module provides a very simple implementation of TCP Ping, with both an asynchronous and synchronous interface.

Latency is always returned in milliseconds, and is provided by Time::HiRes

Socket functionality is provided by AnyEvent::Socket

All functions are exported by default.

Synchronous API

$latency = tcp_ping $site, $port [, $timeout]

Measures the time taken to connect to the provided $site:$port and returns it synchronously.

$timeout is optional, and defaults to 5 seconds if not provided.

Asynchronous API

tcp_ping_syn $site, $port [, $timeout]

Initiates the connection to the provided $site:$port and sets a callback to calculate the latency. Correct latency measurement is not dependant on timely calls to tcp_ping_ack.

$timeout is optional, and defaults to 5 seconds if not provided.

If this function is called multiple times for the same $site:$port pair, a counter indicating the number of responses requrested is incremented per call, but additional connections are not initiated - it is therefore safe to call this function on an unsorted list of $site:$port pairs.

$latency = tcp_ping_ack $site, $port;

Waits for the latency of the connection to the $site:$port pair. If the connection has already completed, it returns the latency immediately.

This function uses the counter maintained by tcp_ping_syn to know how many responses are expected before cleaning up the memory associated with the ping operation. Again, this allows the calling program to be fairly naive about the lists it uses. All tcp_ping_syn calls for a given $site:$port pair will yield the same latency value until tcp_ping_ack has drained the queue. Only then will a new connection and measurement be taken.

SEE ALSO

AnyEvent AnyEvent::Socket Time::HiRes

AUTHOR

Phillip O'Donnell, <podonnell@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2013 by Phillip O'Donnell

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.1 or, at your option, any later version of Perl 5 you may have available.