mirror of https://github.com/c-ares/c-ares.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
62 lines
2.6 KiB
62 lines
2.6 KiB
.\" |
|
.\" Copyright 2024 by the c-ares project and its contributors |
|
.\" SPDX-License-Identifier: MIT |
|
.\" |
|
.TH ARES_SET_NOTIFY_PENDING_WRITE_CALLBACK 3 "13 Aug 2024" |
|
.SH NAME |
|
ares_set_pending_write_cb, ares_process_pending_write \- Function |
|
for setting a callback which is triggered when there is potential pending data |
|
which needs to be written. |
|
.SH SYNOPSIS |
|
.nf |
|
#include <ares.h> |
|
|
|
typedef void (*ares_pending_write_cb)(void *\fIdata\fP); |
|
|
|
void ares_set_pending_write_cb( |
|
ares_channel_t *\fIchannel\fP, |
|
ares_pending_write_cb \fIcallback\fP, |
|
void *\fIuser_data\fP); |
|
|
|
void ares_process_pending_write(ares_channel_t *\fIchannel\fP); |
|
|
|
.fi |
|
|
|
.SH DESCRIPTION |
|
The \fBares_set_pending_write_cb(3)\fP function sets a callback |
|
function \fIcallback\fP in the given ares channel handle \fIchannel\fP that |
|
is invoked whenever there is new pending TCP data to be written. Since TCP |
|
is stream based, if there are multiple queries being enqueued back to back they |
|
can be sent as one large buffer. Normally a \fBsend(2)\fP syscall operation |
|
would be triggered for each query. |
|
|
|
When setting this callback, an event will be triggered when data is buffered, |
|
but not written. This event is used to wake the caller's event loop which |
|
should call \fBares_process_pending_write(3)\fP using the channel associated |
|
with the callback. Each time the callback is triggered must result in a call |
|
to \fBares_process_pending_write(3)\fP from the caller's event loop otherwise |
|
stalls and timeouts may occur. The callback \fBmust not\fP call |
|
\fBares_process_pending_write(3)\fP directly as otherwise it would invalidate |
|
any advantage of this use-case. |
|
|
|
This is considered an optimization, especially when using TLS-based connections |
|
which add additional overhead to the data stream. Due to the asyncronous nature |
|
of c-ares, there is no way to identify when a caller may be finished enqueuing |
|
queries via any of the possible public API calls such as |
|
\fBares_getaddrinfo(3)\fP or \fBares_search_dnsrec(3)\fP, so this is an |
|
enhancement to try to group query send operations together and will rely on the |
|
singaling latency involved in waking the user's event loop. |
|
|
|
If no callback is set, data will be written immediately to the socket, thus |
|
bypassing this optimization. |
|
|
|
This option cannot be used with \fIARES_OPT_EVENT_THREAD\fP passed to |
|
\fBares_init_options(3)\fP since the user has no event loop. This optimization |
|
is automatically enabled when using the Event Thread as it sets the callback |
|
for its own internal signaling. |
|
|
|
.SH AVAILABILITY |
|
This function was first introduced in c-ares version 1.34.0. |
|
|
|
.SH SEE ALSO |
|
.BR ares_init_options (3)
|
|
|