• NAME
• SYNOPSIS
• DESCRIPTION
• CONSTRUCTOR
  • new
• METHODS
  • fd
  • new_handle_for_fd
  • wait
  • getnqueries
  • getaddrinfo
  • getaddrinfo_done
  • getnameinfo
  • getnameinfo_done
  • res_query
  • res_search
  • res_done
  • isdone
  • getnext
  • cancel
  • setuserdata
  • getuserdata
• CONSTANTS
• QUERY OBJECTS
  • asyncns
  • isdone
  • setuserdata
  • getuserdata
• EXAMPLES
  • Multiple Queries
  • Non-blocking IO
• SEE ALSO
• AUTHOR

NAME

Net::LibAsyncNS - a Perl wrapper around libasyncns

SYNOPSIS

   use Net::LibAsyncNS;
   use Socket qw( SOCK_RAW );

   my $asyncns = Net::LibAsyncNS->new( 1 );

   # By specifying this socktype hint, we only get one result per address family
   my %hints = ( socktype => SOCK_RAW );

   my $query = $asyncns->getaddrinfo( "localhost", undef, \%hints );

   while( $asyncns->getnqueries ) {
      $asyncns->wait( 1 );

      if( $query->isdone ) {
         my ( $err, @res ) = $asyncns->getaddrinfo_done( $query );
         die "getaddrinfo - $err" if $err;

         foreach my $res ( @res ) {
            printf "family=%d, addr=%v02x\n", $res->{family}, $res->{addr};
         }
      }
   }

DESCRIPTION

The name resolver functions getaddrinfo and getnameinfo as provided by most C libraries are blocking functions; they will perform their work and return an answer when it is ready. This makes it hard to use these name resolvers in asynchronous or non-blocking code.

The libasyncns library provides a way to invoke these library functions from within an asynchronous or non-blocking program. Individual resolver queries are made by calling a function which returns an object representing an outstanding query (a kind of future). A filehandle is provided by the resolver to watch for readability; when it is readable, a function should be called to collect completed queries. The example in the SYNOPSIS above does not demonstrate this; see the EXAMPLES section below for one that does.

CONSTRUCTOR

new

   $asyncns = Net::LibAsyncNS->new( $n_proc )

Construct a new Net::LibAsyncNS object. It will be initialised with $n_proc processes or threads to handle nameserver lookups.

METHODS

fd

   $fd = $asyncns->fd

Returns a file descriptor number to poll for readability on.

new_handle_for_fd

   $handle = $asyncns->new_handle_for_fd

Returns a new IO::Handle object wrapping the underlying file descriptor. Note that the handle is not cached; a new object is created each time this method is called. For well-behaved results, this should only be called once.

wait

   $success = $asyncns->wait( $block )

Wait for more queries to be ready. If $block is true, this method will block until at least one query is ready, if false it will process any pending IO without blocking. It returns true if the operation was successful or false if an IO error happened; $! will be set in this case.

getnqueries

   $n = $asyncns->getnqueries

Return the number of outstanding queries.

getaddrinfo

   $q = $asyncns->getaddrinfo( $host, $service, $hints )

Starts an asynchronous getaddrinfo resolution on the given $host and $service names. If provided, $hints should be a HASH reference where the following keys are recognised:

flags => INT

family => INT

socktype => INT

protocol => INT

getaddrinfo_done

   ( $err, @res ) = $asyncns->getaddrinfo_done( $q )

Finishes a getaddrinfo resolution, returning an error code, and a list of results. Each result will be a HASH reference containing the following keys:

family => INT

socktype => INT

protocol => INT

Socket type values to pass to socket

addr => STRING

Address to pass to connect

canonname => STRING

If requested, the canonical hostname for this address

getnameinfo

   $q = $asyncns->getnameinfo( $addr, $flags, $wanthost, $wantserv )

Starts an asynchronous getnameinfo resolution on the given address. The $wanthost and $wantserv booleans indicate if the hostname or service name are required.

getnameinfo_done

   ( $err, $host, $service ) = $asyncns->getnameinfo_done( $q )

Finishes a getnameinfo resolution, returning an error code, the hostname and service name, if requested.

res_query

res_search

   $q = $asyncns->res_query( $dname, $class, $type )

   $q = $asyncns->res_search( $dname, $class, $type )

Starts an asynchronous res_query or res_search resolution on the given domain name, class and type.

res_done

   $answer = $asyncns->res_done( $q )

Finishes a res_query or res_search resolution, returning the answer in a packed string, or undef if it fails. If it fails $! will contain the error details.

isdone

   $done = $asyncns->isdone( $q )

Returns true if the given query is ready.

getnext

   $q = $asyncns->getnext

Returns the next query object that is completed, or undef if none are ready yet. This will only yet be valid after calling the wait method at least once.

cancel

   $asyncns->cancel( $q )

Cancels a currently outstanding query. After this is called, the query in $q should not be further accessed, as memory associated with it will have been reclaimed.

setuserdata

   $asyncns->setuserdata( $q, $data )

Stores an arbitrary Perl scalar with the query. It can later be retrieved using getuserdata.

getuserdata

   $data = $asyncns->getuserdata( $q )

Returns the Perl scalar previously stored with the query, or undef if no value has yet been set.

CONSTANTS

The following constants are provided by Net::LibAsyncNS::Constants.

Flags for getaddrinfo:

   AI_PASSIVE
   AI_CANONNAME
   AI_NUMERICHOST
   AI_NUMERICSERV

Error values:

   EAI_BADFLAGS
   EAI_NONAME
   EAI_AGAIN
   EAI_FAIL
   EAI_NODATA
   EAI_FAMILY
   EAI_SERVICE
   EAI_SOCKTYPE
   EAI_ADDRFAMILY
   EAI_MEMORY

Flags for getnameinfo:

   NI_NUMERICHOST
   NI_NUMERICSERV
   NI_NAMEREQD
   NI_DGRAM

QUERY OBJECTS

The following methods are available on query objects, returned by getaddrinfo and getnameinfo.

asyncns

   $asyncns = $query->asyncns

Returns the underlying Net::LibAsyncNS object backing the query

isdone

   $done = $query->isdone

setuserdata

   $query->setuserdata( $data )

getuserdata

   $data = $query->getuserdata

Shortcuts to the equivalent method on the underlying Net::LibAsyncNS object

EXAMPLES

Multiple Queries

The SYNOPSIS example only has one outstanding query. To wait for multiple queries to complete, the getnext method can be used. Per-query context data can be stored in the query itself by using the setuserdata and getuserdata accessors.

   use Net::LibAsyncNS;
   use Socket qw( SOCK_RAW );

   my $asyncns = Net::LibAsyncNS->new( 1 );

   my %hints = ( socktype => SOCK_RAW );
   my @hosts = qw( some hostnames here );

   foreach my $host ( @hosts ) {
      my $query = $asyncns->getaddrinfo( $host, undef, \%hints );
      $query->setuserdata( $host );
   }

   while( $asyncns->getnqueries ) {
      $asyncns->wait( 1 ) or die "asyncns_wait: $!";

      while( my $query = $asyncns->getnext ) {
         my ( $err, @res ) = $asyncns->getaddrinfo_done( $query );
         my $host = $query->getuserdata;

         print "$host - $err\n" and next if $err;

         foreach my $res ( @res ) {
            printf "%s is: family=%d, addr=%v02x\n", 
               $host, $res->{family}, $res->{addr};
         }
      }
   }

In this example, the per-query data stored by setuserdata is just the hostname, but any Perl scalar may be stored, such as a HASH ref containing many keys, or CODE ref to a callback function of some kind.

Non-blocking IO

The examples above wait synchronously for the query/queries to complete, in the wait method. However, most of the point of this library is to allow asynchronous resolver calls to mix with other asynchronous and non-blocking code. This is achieved by the containing program waiting for a filehandle to become readable, and to call $asyncns->wait( 0 ) when it is.

The following example shows integration with a simple IO::Poll-based program.

   use IO::Poll;
   use Net::LibAsyncNS;
   use Socket qw( SOCK_RAW );

   my $asyncns = Net::LibAsyncNS->new( 1 );
   my %hints = ( socktype => SOCK_RAW );

   my @hosts = qw( some hostnames here );

   foreach my $host ( @hosts ) {
      my $query = $asyncns->getaddrinfo( $host, undef, \%hints );
      $query->setuserdata( $host );
   }

   my $asyncns_handle = $asyncns->new_handle_for_fd;

   my $poll = IO::Poll->new;
   $poll->mask( $asyncns_handle => POLLIN );

   while( $asyncns->getnqueries ) {
      defined $poll->poll or die "poll() - $!";

      if( $poll->events( $asyncns_handle ) ) {
         while( my $query = $asyncns->getnext ) {
            my ( $err, @res ) = $asyncns->getaddrinfo_done( $query );
            my $host = $query->getuserdata;

            print "$host - $err\n" and next if $err;

            foreach my $res ( @res ) {
               printf "%s is: family=%d, addr=%v02x\n", 
                  $host, $res->{family}, $res->{addr};
            }
         }
      }
   }

SEE ALSO

• http://0pointer.de/lennart/projects/libasyncns is a C library for Linux/Unix for executing name service queries asynchronously. It is an asynchronous wrapper around getaddrinfo(3), getnameinfo(3), res_query(3) and res_search(3) from libc and libresolv.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>