Net::DNS::Async(3pm)

💖 Net::DNS::Async(3pm) 💖

okay bestie, gather round, because this is the manual page for Net::DNS::Async — the Perl module for asynchronous DNS in high volume applications — and it is genuinely iconic. no cap. it's a fire-and-forget DNS helper and it wants you to have a good time. let's get into it 🦋

---

✨ NAME ✨

Net::DNS::Async — Asynchronous DNS helper for high volume applications 💅

---

✨ SYNOPSIS ✨

like, here's the whole vibe in one go:

        use Net::DNS::Async;

        my $c = new Net::DNS::Async(QueueSize => 20, Retries => 3);

        for (...) {
                $c->add(\&callback, @query);
        }
        $c->await();

        sub callback {
                my $response = shift;
                ...
        }

slay. that's it. that's the whole flow 🌸

---

✨ DESCRIPTION ✨

so. Net::DNS::Async is a fire-and-forget asynchronous DNS helper. what that means in bestie terms: your application drops DNS questions into the helper, and then the callback gets called at some point in the future — without your application having to do literally anything else. no selects. no timeouts. no sitting around waiting for a response. none of that. the module handles all of it, you just vibe 😌

the combining thing, and why it matters: if you add the same query to the queue more than once, the module may combine the queries — meaning it will perform that query only once, and then call each callback registered for that query in turn, handing the same Net::DNS::Response object to each one.

⚠️ bestie, listen: because of that shared object, you should not modify the Net::DNS::Response object in any way — lest you break things horribly for a subsequent callback. and we mean horribly. like, main-character-of-a-disaster-movie horribly 😭

this module is similar in principle to POE::Component::Client::DNS, but it does not require POE. so that's a whole dependency you don't have to deal with. obsessed 🫶

---

✨ CONSTRUCTOR ✨

the class method new(...) constructs a new helper object. every single argument is optional (we love a low-pressure situation). these are the parameters recognised as arguments to new():

• QueueSize — the size of the query queue. if you exceed it, further calls to add() will block until some responses come in or time out. it's giving backpressure, honestly.
• Retries — how many times to retry a query before giving up. quitting is valid but let's try a few times first 💪
• Timeout — the timeout for an individual query. one query, one clock ⏰

---

✨ METHODS ✨

💫 $c->add($callback, @query)

adds a new query for asynchronous handling. the @query arguments are those to Net::DNS::Resolver->bgsend(), q.v. — go read that one, iykyk 📖

this call will block if the queue is full. when some pending responses are received, or timeout events occur, the call will unblock. so it's not stuck forever, it's just waiting its turn 🧚

your user callback will be called at some point in the future, with a Net::DNS::Packet object representing the response. and if the query timed out after the specified number of retries? the callback will be called with undef. yes, undef. plan for it 💀

💫 $c->await()

flushes the queue — that is, it waits for and handles all remaining responses. this is the "okay we're done here, wrap it up" button 🎀

---

✨ BUGS ✨

the test suite does not test query timeouts. that's it. that's the bug. noted, documented, moving on 🙈

---

✨ SEE ALSO ✨

• Net::DNS
• POE::Component::Client::DNS

---

✨ COPYRIGHT ✨

Copyright (c) 2005-2006 Shevek. All rights reserved. 👑

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

---

and that's the whole page, bestie 💖 this was Net::DNS::Async(3pm) from the User Contributed Perl Documentation section, generated by perl v5.36.0 on 2022-11-19. go forth and send your queries asynchronously, you absolute icon 🌈✨👑