ARES_QUEUE(3)

💖 ARES_QUEUE(3) 💖

okay bestie, so this is the ARES_QUEUE page from the Library Functions Manual — it's giving "how do I even know if my DNS stuff is done yet" and honestly? iconic question. come sit with me 🫶

✨ NAME ✨

ares_queue_wait_empty, ares_queue_active_queries — functions for checking the c-ares queue status. literally just vibes-checking your queue, no cap 💅

🌸 SYNOPSIS 🌸

#include <ares.h>

size_t ares_queue_active_queries(const ares_channel_t *channel);

ares_status_t ares_queue_wait_empty(ares_channel_t *channel,
                                    int timeout_ms);

🦋 DESCRIPTION 🦋

ares_queue_active_queries(3) 💫

so this one retrieves the total number of active queries pending answers from servers. that's it, that's the function, she's simple and she's thriving.

and bestie, important lore: some c-ares requests may spawn multiple queries — like ares_getaddrinfo(3) when using AF_UNSPEC — and that will be reflected in this number. so don't be gagged when the count is higher than you expected, it's not a bug, it's just her being thorough 🎀

the channel parameter must be set to an initialized channel. no initialized channel? no results. periodt.

ares_queue_wait_empty(3) 💫

this one blocks until notified that there are no longer any queries in queue, or the specified timeout has expired. so she'll just sit there, patiently, like a bestie waiting outside the changing room 💖

the channel parameter must be set to an initialized channel (again, we mean it).

the timeout_ms parameter is the number of milliseconds to wait for the queue to be empty — or -1 for Infinite. yes, Infinite. capital I. main character energy 🌈

⭐ RETURN VALUES ⭐

• ares_queue_active_queries(3) returns the active query count.
• ares_queue_wait_empty(3) can return any of the following values:
  • ARES_ENOTIMP — if not built with threading support 🙈
  • ARES_ETIMEOUT — if requested timeout expired 😭
  • ARES_SUCCESS — when queue is empty. slay 👑

🎀 AVAILABILITY 🎀

this function was first introduced in c-ares version 1.27.0, and it requires the c-ares library to be built with threading support.

ngl bestie, if you're not built with threading support, ares_queue_wait_empty(3) is gonna hand you an ARES_ENOTIMP and there is nothing anyone can do about it. know your build 💀

🔥 SEE ALSO 🔥

• ares_init_options(3)
• ares_threadsafety(3)

okay that's the whole page, you ate it, I'm obsessed 💜 this was the ARES_QUEUE(3) page, 16 February 2024 edition — go forth and queue responsibly, bestie 🧚✨