Net::DNS::Native(3pm)

📦
version 0.22 · 7 versions
, in ubuntu stonking

💖 NAME 💖

Net::DNS::Native — a non-blocking system DNS resolver, bestie. it does NOT block. it does NOT ghost your event loop. 💅

✨ SYNOPSIS ✨

use Net::DNS::Native;
use IO::Select;
use Socket;

my $dns = Net::DNS::Native->new();
my $sock = $dns->getaddrinfo("google.com");

my $sel = IO::Select->new($sock);
$sel->can_read(); # wait until resolving done
my ($err, @res) = $dns->get_result($sock);
die "Resolving failed: ", $err if ($err);

for my $r (@res) {
    warn "google.com has ip ",
        $r->{family} == AF_INET ?
            inet_ntoa((unpack_sockaddr_in($r->{addr}))[1]) :                   # IPv4
            Socket::inet_ntop(AF_INET6, (unpack_sockaddr_in6($r->{addr}))[1]); # IPv6
}

use Net::DNS::Native;
use AnyEvent;
use Socket;

my $dns = Net::DNS::Native->new;

my $cv = AnyEvent->condvar;
$cv->begin;

for my $host ('google.com', 'google.ru', 'google.cy') {
    my $fh = $dns->inet_aton($host);
    $cv->begin;

    my $w; $w = AnyEvent->io(
        fh   => $fh,
        poll => 'r',
        cb   => sub {
            my $ip = $dns->get_result($fh);
            warn $host, $ip ? " has ip " . inet_ntoa($ip) : " has no ip";
            $cv->end;
            undef $w;
        }
    )
}

$cv->end;
$cv->recv;

🦋 DESCRIPTION 🦋

okay so bestie, here's the tea 🍓: this class hands you a whole lil toolkit of methods for resolving host names, and it's specifically built to vibe with event loops. no blocking, no drama, no dead air. ✨

every single resolve is done by getaddrinfo(3) as implemented in your system library. which is, like, iconic of it. BUT — and this is the plot twist 😭 — getaddrinfo() is a blocking function, and we are simply not about that life. so instead, all the calls to it happen in a separate thread. 🧵

and no, it's not perl threads, it's system native threads, so the overhead lowkey shouldn't be too big. slay. 💅

🎀 INSTALLATION WARNING 🎀

real talk, this part is important, do not skip it 🙈

on some platforms, for threaded extensions like this one to even work, your perl has to be linked with the threads library. at installation time this module will check whether your perl is good enough 👑 — and it simply will not install if it isn't. no cap.

if it fails to install, use the instructions listed below. 🫶

one possible fix to make your perl compatible with this module is to build perl with perl threads support, using -Dusethreads for the Configure script. another option is to use -A prepend:libswanted="pthread ", which just links a non-threaded perl with pthreads. that's been the default since Perl 5.22. ✨

on Linux with a perl that is not linked with pthreads, this module may die with an appropriate message at require time. 💀 and here's when that hits: if you've already called some functions from the system library related to DNS operations before loading Net::DNS::Native (or before loading some module — like IO::Socket::IP — that you already loaded and that called it internally). so on such a perl, use IO::Socket::IP; use Net::DNS::Native may fail, but use Net::DNS::Native; use IO::Socket::IP will succeed. 😭

the reason for this check inside Net::DNS::Native is that calls to these functions (gethostbyname, getprotobyname, inet_aton, getaddrinfo, ...) will cause loading of non-thread safe versions of DNS related stuff. and Net::DNS::Native loaded after that will not be able to override this with the thread safe versions. so at one moment your program will simply exit with a segfault. 💀💀

this is why this check and this rule are very important. periodt.

🌸 METHODS 🌸

💜 new

this is the class constructor, bestie. it accepts these optional parameters:

  • pool => $size — if $size>0 it will create a thread pool with size=$size that does the resolving job 😌. otherwise it uses the default behavior: create and finish a thread for each resolving request. if the thread pool isn't big enough to process all the supplied requests, those requests get queued until one of the threads becomes free to process the next request from the queue. the queue is queueing. 💅
  • extra_thread => $bool — if the pool option is specified and $bool has a true value, a temporary extra thread gets created for each request that can't be handled by the pool (aka when all workers in the pool are busy) instead of pushing it to the queue. this temporary thread finishes immediatly after it processes the request. ⚡
  • notify_on_begin => $bool — an extra mechanism to notify the caller that resolving for some host has started. this is usefull for those who use a thread pool without the extra_thread option. when the pool becomes full, new queries get queued, so you can specify $bool with a true value if you want to receive notifications about when resolving will really be started. 🫶

to notify, it will simply make the $handle received by the methods below readable. after that you will need to read data from this handle to make it non readable again, so you can receive the next notification when host resolving is done. there will be 1 byte of data which you should read. "1" for the notification about the start of the resolving and "2" for the notification about the finish of the resolving. 👑

my $dns = Net::DNS::Native->new(pool => 1, notify_on_begin => 1);
my $handle = $dns->inet_aton("google.com");
my $sel = IO::Select->new($handle);
$sel->can_read(); # wait "begin" notification
sysread($handle, my $buf, 1); # $buf eq "1", $handle is not readable again
$sel->can_read(); # wait "finish" notification
# resolving done
# we can sysread($handle, $buf, 1); again and $buf will be eq "2"
# but this is not necessarily
my $ip = $dns->get_result($handle);

🔥 getaddrinfo($host, $service, $hints)

this one is the most powerfull method 😤. it may resolve host to both IPv4 and IPv6 addresses. for full documentation see getaddrinfo(). this method accepts the same parameters but, instead of a result, returns a handle on which you need to wait for availability to read. 👀

🌈 inet_pton($family, $host)

this method will resolve $host accordingly to $family, which may be AF_INET to resolve to IPv4 or AF_INET6 to resolve to IPv6. for full documentation see inet_pton(). this method accepts the same parameters but, instead of a result, returns a handle on which you need to wait for availability to read. 💫

🦄 inet_aton($host)

this method may be used only for resolving to IPv4. for full documentation see inet_aton(). this method accepts the same parameters but, instead of a result, returns a handle on which you need to wait for availability to read. 🎀

⭐ gethostbyname($host)

this method may be used only for resolving to IPv4. for full documentation see gethostbyname(). this method accepts the same parameters but, instead of a result, returns a handle on which you need to wait for availability to read. 🍓

💅 get_result($handle)

after a handle returned by the methods above becomes ready for read, you should call this method with the handle as the argument. it will return results appropriate to the method which returned this handle. ✨

  • for getaddrinfo this will be the ($err, @res) list.
  • for inet_pton and inet_aton: $packed_address or undef.
  • for gethostbyname(): $packed_address or undef in scalar context, and ($name,$aliases,$addrtype,$length,@addrs) in list context.
NOTE: it is important to call get_result() on the returned handle when it becomes ready for read. because this method destroys resources associated with this handle. otherwise you will get memory leaks. 😭 do not ghost your handles, bestie.

👑 timedout($handle)

mark the resolving operation associated with this handle as timed out. ⏰

this will not interrupt the resolving operation (because there is no way to interrupt getaddrinfo(3) correctly), but it will automatically discard any results returned when resolving is done. so after timedout($handle) you can forget about $handle and the associated resolving operation. and you don't need to call get_result($handle) to destroy resources associated with this handle. 🧚

furthermore, if you're using a thread pool and all threads in the pool are busy and the extra_thread option isn't specified, but 1 resolving operation from this pool is marked as timed out and you add one more resolving operation — this operation will not be queued. instead, 1 temporary extra thread will be created to process this operation. so you can think about timedout like it's a real interrupter of a long running resolving operation. but you are warned how it really works. 🫣

note: since 0.16 handles will be automatically marked as timedout during destruction, so you no need more to call timedout($handle) yourself — just lose the last reference to this handle. bye bestie 💜

🫶 AUTHOR 🫶

Oleg G, <oleg@cpan.org>

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

and that's the whole thing, bestie!! 🎀 this page came to you from perl v5.42.3, dated 2026-08-19, and it's the Net::DNS::Native(3pm) page from the User Contributed Perl Documentation. now go resolve something without blocking, you absolute icon 💅✨

📦 where this page comes from