ares_queue.3 (1693B)
1 .\" 2 .\" Copyright 2024 by the c-ares project and its contributors 3 .\" SPDX-License-Identifier: MIT 4 .\" 5 .TH ARES_QUEUE 3 "16 February 2024" 6 .SH NAME 7 ares_queue_wait_empty, ares_queue_active_queries \- Functions for checking the 8 c-ares queue status 9 .SH SYNOPSIS 10 .nf 11 #include <ares.h> 12 13 size_t ares_queue_active_queries(const ares_channel_t *channel); 14 15 ares_status_t ares_queue_wait_empty(ares_channel_t *channel, 16 int timeout_ms); 17 .fi 18 .SH DESCRIPTION 19 The \fBares_queue_active_queries(3)\fP function retrieves the total number of 20 active queries pending answers from servers. Some c-ares requests may spawn 21 multiple queries, such as \fIares_getaddrinfo(3)\fP when using \fIAF_UNSPEC\fP, 22 which will be reflected in this number. The \fBchannel\fP parameter must be set 23 to an initialized channel. 24 25 The \fBares_queue_wait_empty(3)\fP function blocks until notified that there are 26 no longer any queries in queue, or the specified timeout has expired. The 27 \fBchannel\fP parameter must be set to an initialized channel. The 28 \fBtimeout_ms\fP parameter is the number of milliseconds to wait for the queue 29 to be empty or -1 for Infinite. 30 31 .SH RETURN VALUES 32 \fIares_queue_active_queries(3)\fP returns the active query count. 33 34 \fIares_queue_wait_empty(3)\fP can return any of the following values: 35 .TP 14 36 .B ARES_ENOTIMP 37 if not built with threading support 38 .TP 14 39 .B ARES_ETIMEOUT 40 if requested timeout expired 41 .TP 14 42 .B ARES_SUCCESS 43 when queue is empty. 44 .TP 14 45 46 .SH AVAILABILITY 47 This function was first introduced in c-ares version 1.27.0, and requires the 48 c-ares library to be built with threading support. 49 50 .SH SEE ALSO 51 .BR ares_init_options (3), 52 .BR ares_threadsafety (3)