NAME

EV::cares - high-performance async DNS resolver using c-ares and EV

SYNOPSIS

use EV;
use EV::cares qw(:status :types);

my $r = EV::cares->new(
    servers => ['8.8.8.8', '1.1.1.1'],
    timeout => 5,
    tries   => 3,
);

# simple A + AAAA resolve
$r->resolve('example.com', sub {
    my ($status, @addrs) = @_;
    if ($status == ARES_SUCCESS) {
        print "resolved: @addrs\n";
    } else {
        warn "failed: " . EV::cares::strerror($status) . "\n";
    }
});

# auto-parsed DNS search
$r->search('example.com', T_MX, sub {
    my ($status, @mx) = @_;
    printf "MX %d %s\n", $_->{priority}, $_->{host} for @mx;
});

# raw DNS query
$r->query('example.com', C_IN, T_A, sub {
    my ($status, $buf) = @_;
    # $buf is the raw DNS response packet
});

EV::run;

DESCRIPTION

EV::cares integrates the c-ares asynchronous DNS library directly with the EV event loop at the C level. Socket I/O and timer management happen entirely in XS with zero Perl-level event processing overhead.

Multiple queries run concurrently. c-ares handles server rotation, retries, timeouts, and search-domain appending.

Requires c-ares >= 1.22.0 (provided automatically by Alien::cares).

CONSTRUCTOR

new

my $r = EV::cares->new(%opts);

All options are optional.

servers => \@addrs | "addr1,addr2,...": DNS server addresses. Default: system resolv.conf servers.
timeout => $seconds: Per-try timeout (fractional seconds).
maxtimeout => $seconds: Maximum total timeout across all tries.
tries => $n: Number of query attempts.
ndots => $n: Threshold for treating a name as absolute (skip search suffixes).
flags => $flags: Bitmask of ARES_FLAG_* constants.
lookups => $string: Lookup order: "b" for DNS, "f" for /etc/hosts.
rotate => 1: Round-robin among servers.
tcp_port => $port
udp_port => $port: Non-standard DNS port.
ednspsz => $bytes: EDNS0 UDP payload size.
resolvconf => $path: Path to an alternative resolv.conf.
hosts_file => $path: Path to an alternative hosts file.
udp_max_queries => $n: Max queries per UDP connection before reconnect.
qcache => $max_ttl: Enable query result cache; $max_ttl is the upper TTL bound in seconds. 0 disables the cache.

QUERY METHODS

Every query method takes a callback as the last argument. The first argument to the callback is always a status code (ARES_SUCCESS on success).

resolve

$r->resolve($name, sub { my ($status, @addrs) = @_ });

Resolves $name via ares_getaddrinfo with AF_UNSPEC, returning both IPv4 and IPv6 address strings.

getaddrinfo

$r->getaddrinfo($node, $service, \%hints, $cb);

Full getaddrinfo. $service and \%hints may be undef. Hint keys: family, socktype, protocol, flags (ARES_AI_*). Callback receives ($status, @ip_strings).

search

$r->search($name, $type, sub { my ($status, @records) = @_ });

DNS search (appends search domains from resolv.conf), always using C_IN class. Results are auto-parsed based on $type:

T_A, T_AAAA    ($status, @ip_strings)
T_MX           ($status, @{ {priority, host} })
T_SRV          ($status, @{ {priority, weight, port, target} })
T_TXT          ($status, @strings)
T_NS           ($status, @hostnames)
T_SOA          ($status, {mname, rname, serial, refresh,
                          retry, expire, minttl})
T_PTR          ($status, @hostnames)
T_NAPTR        ($status, @{ {order, preference, flags,
                             service, regexp, replacement} })
T_CAA          ($status, @{ {critical, property, value} })
T_CNAME etc.   ($status, $raw_buffer)

query

$r->query($name, $class, $type, sub { my ($status, $buf) = @_ });

Raw DNS query without search-domain appending. Returns the unmodified DNS response packet.

gethostbyname

$r->gethostbyname($name, $family, sub { my ($status, @addrs) = @_ });

Legacy resolver. $family is AF_INET or AF_INET6.

reverse

$r->reverse($ip, sub { my ($status, @hostnames) = @_ });

Reverse DNS (PTR) lookup for an IPv4 or IPv6 address string.

getnameinfo

$r->getnameinfo($packed_sockaddr, $flags, sub {
    my ($status, $node, $service) = @_;
});

Full getnameinfo. $packed_sockaddr comes from "pack_sockaddr_in" in Socket or "pack_sockaddr_in6" in Socket. $flags is a bitmask of ARES_NI_* constants.

CHANNEL METHODS

cancel

Cancel all pending queries. Each outstanding callback fires with ARES_ECANCELLED.

set_servers

$r->set_servers('8.8.8.8', '1.1.1.1');

Replace the DNS server list.

servers

my $csv = $r->servers;   # "8.8.8.8,1.1.1.1"

Returns the current server list as a comma-separated string.

set_local_dev

$r->set_local_dev('eth0');

Bind outgoing queries to a network device.

set_local_ip4

$r->set_local_ip4('192.168.1.100');

Bind outgoing queries to a local IPv4 address.

set_local_ip6

$r->set_local_ip6('::1');

Bind outgoing queries to a local IPv6 address.

active_queries

my $n = $r->active_queries;

Returns the number of outstanding queries.

reinit

$r->reinit;

Re-read system DNS configuration (resolv.conf, hosts file) without destroying the channel. Useful for long-running daemons where the resolver configuration may change at runtime.

destroy

$r->destroy;

Explicitly release the c-ares channel and stop all watchers. Pending callbacks fire with ARES_ECANCELLED or ARES_EDESTRUCTION. Safe to call from within a callback. Also called automatically when the object is garbage-collected.

FUNCTIONS

strerror

my $msg = EV::cares::strerror($status);
my $msg = EV::cares->strerror($status);   # also works

Returns a human-readable string for a status code.

lib_version

my $ver = EV::cares::lib_version();   # e.g. "1.34.6"

Returns the c-ares library version string.

CALLBACK SAFETY

Callbacks are invoked from within ares_process_fd, called from EV I/O and timer watchers. Exceptions thrown inside callbacks are caught (G_EVAL) and emitted as warnings; they do not propagate to the caller.

It is safe to call cancel, destroy, or undef the resolver from within a callback. Remaining pending queries will receive ARES_ECANCELLED.

Lookups that use only local sources (lookups => 'f') may complete synchronously during the initiating method call.

EXPORT TAGS

:status    ARES_SUCCESS  ARES_ENODATA  ARES_ETIMEOUT  ...
:types     T_A  T_AAAA  T_MX  T_SRV  T_TXT  T_NS  T_SOA  ...
:classes   C_IN  C_CHAOS  C_HS  C_ANY
:flags     ARES_FLAG_USEVC  ARES_FLAG_EDNS  ARES_FLAG_DNS0x20  ...
:ai        ARES_AI_CANONNAME  ARES_AI_ADDRCONFIG  ARES_AI_NOSORT  ...
:ni        ARES_NI_NOFQDN  ARES_NI_NUMERICHOST  ...
:families  AF_INET  AF_INET6  AF_UNSPEC
:all       all of the above

AUTHOR

vividsnow

LICENSE

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

To install EV::cares, copy and paste the appropriate command in to your terminal.

cpanm

cpanm EV::cares

CPAN shell

perl -MCPAN -e shell
install EV::cares

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	Go to GitHub issues (only if GitHub is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)