ARES_QUEUE(3)

💖 ARES_QUEUE — bestie's guide to checking ur c-ares queue 💖

okay so this is ARES_QUEUE(3), from the Library Functions Manual, and it's literally the "are we there yet" of the c-ares world 🚗✨. Two functions, both about knowing whether ur queries are still out there doing their thing. Let's get into it.

✨ NAME ✨

ares_queue_wait_empty, ares_queue_active_queries — functions for checking the c-ares queue status 👑

🦋 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) 💅

she tells u the total number of active queries that are still pending answers from servers. no cap. and here's the tea: some c-ares requests lowkey spawn multiple queries — like ares_getaddrinfo(3) when it's using AF_UNSPEC — and all of those will be reflected in this number. so don't be shocked if the count is bigger than u expected, it's not a bug, it's just multitasking main character energy. 🌈

the channel parameter must be set to an initialized channel. no half-baked channels here, bestie.

ares_queue_wait_empty(3) 🎀

this one blocks until it gets notified that there are no longer any queries in queue, OR the timeout u gave it has expired. whichever comes first, girl. ⏳

the channel parameter must be set to an initialized channel (same rule as above, it's giving consistent).

the timeout_ms parameter is the number of milliseconds to wait for the queue to be empty — or -1 for Infinite. yes, infinite. she'll wait forever for u. obsessed. 💖

💀 RETURN VALUES 💀

ares_queue_active_queries(3) returns the active query count. simple. iconic. no drama. ✨

ares_queue_wait_empty(3) can return any of the following values:

• ARES_ENOTIMP — if it wasn't built with threading support 😭 (the library, not u, ur perfect)
• ARES_ETIMEOUT — if the requested timeout expired ⏰
• ARES_SUCCESS — when the queue is empty 🎉 periodt.

🌟 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. so if ur build is threadless, this whole page is giving window shopping 🛍️💔

👑 SEE ALSO 👑

• ares_init_options(3)
• ares_threadsafety(3)

that's the whole page bestie, go forth and check ur queues responsibly 🫶

with love, ur fave — ARES_QUEUE(3), 16 February 2024, from the Library Functions Manual 💅✨