NAME

AnyEvent::Util - various utility functions.

SYNOPSIS

use AnyEvent::Util;

DESCRIPTION

This module implements various utility functions, mostly replacing well-known functions by event-ised counterparts.

All functions documented without AnyEvent::Util:: prefix are exported by default.

inet_aton $name_or_address, $cb->($binary_address_or_undef)

Works almost exactly like its Socket counterpart, except that it uses a callback. Also, if a host has only an IPv6 address, this might be passed to the callback instead (use the length to detetc this - 4 for IPv4, 16 for IPv6).

This function uses various shortcuts and will fall back to either EV::ADNS or your systems inet_aton.

fh_nonblocking $fh, $nonblocking

Sets the blocking state of the given filehandle (true == nonblocking, false == blocking). Uses fcntl on anything sensible and ioctl FIONBIO on broken (i.e. windows) platforms.

$guard = guard { CODE }

This function creates a special object that, when called, will execute the code block.

This is often handy in continuation-passing style code to clean up some resource regardless of where you break out of a process.

my $guard = AnyEvent::Util::tcp_connect $host, $port, $connect_cb[, $prepare_cb]

This function is experimental.

This is a convenience function that creates a tcp socket and makes a 100% non-blocking connect to the given $host (which can be a hostname or a textual IP address) and $port.

Unless called in void context, it returns a guard object that will automatically abort connecting when it gets destroyed (it does not do anything to the socket after the conenct was successful).

If the connect is successful, then the $connect_cb will be invoked with the socket filehandle (in non-blocking mode) as first and the peer host (as a textual IP address) and peer port as second and third arguments, respectively.

If the connect is unsuccessful, then the $connect_cb will be invoked without any arguments and $! will be set appropriately (with ENXIO indicating a dns resolution failure).

The filehandle is suitable to be plugged into AnyEvent::Handle, but can be used as a normal perl file handle as well.

Sometimes you need to "prepare" the socket before connecting, for example, to bind it to some port, or you want a specific connect timeout that is lower than your kernel's default timeout. In this case you can specify a second callback, $prepare_cb. It will be called with the file handle in not-yet-connected state as only argument and must return the connection timeout value (or 0, undef or the empty list to indicate the default timeout is to be used).

Note that the socket could be either a IPv4 TCP socket or an IPv6 tcp socket (although only IPv4 is currently supported by this module).

Simple Example: connect to localhost on port 22.

AnyEvent::Util::tcp_connect localhost => 22, sub {
   my $fh = shift
      or die "unable to connect: $!";
   # do something
};

Complex Example: connect to www.google.com on port 80 and make a simple GET request without much error handling. Also limit the connection timeout to 15 seconds.

AnyEvent::Util::tcp_connect "www.google.com", 80,
   sub {
      my ($fh) = @_
         or die "unable to connect: $!";

      my $handle; # avoid direct assignment so on_eof has it in scope.
      $handle = new AnyEvent::Handle
         fh     => $fh,
         on_eof => sub {
            undef $handle; # keep it alive till eof
            warn "done.\n";
         };

      $handle->push_write ("GET / HTTP/1.0\015\012\015\012");

      $handle->push_read_line ("\015\012\015\012", sub {
         my ($handle, $line) = @_;

         # print response header
         print "HEADER\n$line\n\nBODY\n";

         $handle->on_read (sub {
            # print response body
            print $_[0]->rbuf;
            $_[0]->rbuf = "";
         });
      });
   }, sub {
      my ($fh) = @_;
      # could call $fh->bind etc. here

      15
   };

$guard = AnyEvent::Util::tcp_server $host, $port, $accept_cb[, $prepare_cb]

This function is experimental.

Create and bind a tcp socket to the given host (any IPv4 host if undef, otherwise it must be an IPv4 or IPv6 address) and port (or an ephemeral port if given as zero or undef), set the SO_REUSEADDR flag and call listen.

For each new connection that could be accepted, call the $accept_cb with the filehandle (in non-blocking mode) as first and the peer host and port as second and third arguments (see tcp_connect for details).

Croaks on any errors.

If called in non-void context, then this function returns a guard object whose lifetime it tied to the tcp server: If the object gets destroyed, the server will be stopped (but existing accepted connections will continue).

If you need more control over the listening socket, you can provide a $prepare_cb, which is called just before the listen () call, with the listen file handle as first argument.

It should return the length of the listen queue (or 0 for the default).

Example: bind on tcp port 8888 on the local machine and tell each client to go away.

AnyEvent::Util::tcp_server undef, 8888, sub {
   my ($fh, $host, $port) = @_;

   syswrite $fh, "The internet is full, $host:$port. Go away!\015\012";
};

AUTHOR

Marc Lehmann <schmorp@schmorp.de>
http://home.schmorp.de/