NAME

ParaDNS - a DNS lookup class for the Danga::Socket framework

SYNOPSIS

  ParaDNS->new(
    callback => sub { print "Got result $_[0] for query $_[1]\n" },
    host     => 'google.com',
  );

DESCRIPTION

This module performs asynchronous DNS lookups, making use of a single UDP socket (unlike Net::DNS's bgsend/bgread combination). It uses the Danga::Socket framework for high performance.

Currently this module will only perform A or PTR lookups. A rDNS (PTR) lookup will be performed if the host matches the regexp: /^\d+\.\d+\.\d+.\d+$/.

The lookups time out after 15 seconds.

API

ParaDNS->new( %options )

Create a new DNS query. You do not need to store the resulting object as this class is all done with callbacks.

Example:

  ParaDNS->new(
    callback => sub { print "Got result: $_[0]\n" },
    host => 'google.com',
    );

[required] callback

The callback to call when results come in. This should be a reference to a subroutine. The callback receives two parameters - the result of the DNS lookup and the host that was looked up.

host

A host name to lookup. Note that if the hostname is a dotted quad of numbers then a reverse DNS (PTR) lookup is performend.

hosts

An array-ref list of hosts to lookup.

NOTE: One of either host or hosts is required.

client

It is possible to specify a client object which you wish to "pause" for reading until your DNS result returns. The client will be issued the ->pause_read method when the query is issued, and the ->continue_read method when the query returns.

This is used in Qpsmtpd where we want to wait until the DNS query returns before accepting more data from the client.

type

You can specify one of: "A", "AAAA", "PTR", "CNAME", "NS" or "TXT" here. Other types may be supported in the future. See %type_to_host in Resolver.pm for details, though more complex queries (e.g. SRV) may require a slightly more complex solution.

A PTR query is automatically issued if the host looks like an IP address.

Stand-alone Use

Normal usage of ParaDNS is within another application that already uses the Danga::Socket framework. However if you wish to use this as a script to just issue thousands of DNS queries then you need to add the following to exit the event loop when all the DNS queries are done:

    Danga::Socket->SetPostLoopCallback(
        sub {
            my $dmap = shift;
            for my $fd (keys %$dmap) {
                my $pob = $dmap->{$fd};
                if ($pob->isa('ParaDNS::Resolver')) {
                    return 1 if $pob->pending;
                }
            }
            return 0; # causes EventLoop to exit
        });

LICENSE

This module is licensed under the same terms as perl itself.

AUTHOR

Matt Sergeant, <matt@sergeant.org>.