ares_set_pending_write_cb.3 (2644B)
1 .\" 2 .\" Copyright 2024 by the c-ares project and its contributors 3 .\" SPDX-License-Identifier: MIT 4 .\" 5 .TH ARES_SET_NOTIFY_PENDING_WRITE_CALLBACK 3 "13 Aug 2024" 6 .SH NAME 7 ares_set_pending_write_cb, ares_process_pending_write \- Function 8 for setting a callback which is triggered when there is potential pending data 9 which needs to be written. 10 .SH SYNOPSIS 11 .nf 12 #include <ares.h> 13 14 typedef void (*ares_pending_write_cb)(void *\fIdata\fP); 15 16 void ares_set_pending_write_cb( 17 ares_channel_t *\fIchannel\fP, 18 ares_pending_write_cb \fIcallback\fP, 19 void *\fIuser_data\fP); 20 21 void ares_process_pending_write(ares_channel_t *\fIchannel\fP); 22 23 .fi 24 25 .SH DESCRIPTION 26 The \fBares_set_pending_write_cb(3)\fP function sets a callback 27 function \fIcallback\fP in the given ares channel handle \fIchannel\fP that 28 is invoked whenever there is new pending TCP data to be written. Since TCP 29 is stream based, if there are multiple queries being enqueued back to back they 30 can be sent as one large buffer. Normally a \fBsend(2)\fP syscall operation 31 would be triggered for each query. 32 33 When setting this callback, an event will be triggered when data is buffered, 34 but not written. This event is used to wake the caller's event loop which 35 should call \fBares_process_pending_write(3)\fP using the channel associated 36 with the callback. Each time the callback is triggered must result in a call 37 to \fBares_process_pending_write(3)\fP from the caller's event loop otherwise 38 stalls and timeouts may occur. The callback \fBmust not\fP call 39 \fBares_process_pending_write(3)\fP directly as otherwise it would invalidate 40 any advantage of this use-case. 41 42 This is considered an optimization, especially when using TLS-based connections 43 which add additional overhead to the data stream. Due to the asyncronous nature 44 of c-ares, there is no way to identify when a caller may be finished enqueuing 45 queries via any of the possible public API calls such as 46 \fBares_getaddrinfo(3)\fP or \fBares_search_dnsrec(3)\fP, so this is an 47 enhancement to try to group query send operations together and will rely on the 48 singaling latency involved in waking the user's event loop. 49 50 If no callback is set, data will be written immediately to the socket, thus 51 bypassing this optimization. 52 53 This option cannot be used with \fIARES_OPT_EVENT_THREAD\fP passed to 54 \fBares_init_options(3)\fP since the user has no event loop. This optimization 55 is automatically enabled when using the Event Thread as it sets the callback 56 for its own internal signaling. 57 58 .SH AVAILABILITY 59 This function was first introduced in c-ares version 1.34.0. 60 61 .SH SEE ALSO 62 .BR ares_init_options (3)