mirror of https://github.com/nodejs/node.git
110 lines
4.8 KiB
Groff
110 lines
4.8 KiB
Groff
.\"
|
|
.\" Copyright 1998 by the Massachusetts Institute of Technology.
|
|
.\" SPDX-License-Identifier: MIT
|
|
.\"
|
|
.TH ARES_PROCESS 3 "25 July 1998"
|
|
.SH NAME
|
|
ares_process_fds, ares_process_fd, ares_process \- Process events for name resolution
|
|
.SH SYNOPSIS
|
|
.nf
|
|
#include <ares.h>
|
|
|
|
/*! Events used by ares_fd_events_t */
|
|
typedef enum {
|
|
ARES_FD_EVENT_NONE = 0, /*!< No events */
|
|
ARES_FD_EVENT_READ = 1 << 0, /*!< Read event (including disconnect/error) */
|
|
ARES_FD_EVENT_WRITE = 1 << 1 /*!< Write event */
|
|
} ares_fd_eventflag_t;
|
|
|
|
/*! Type holding a file descriptor and mask of events, used by
|
|
* ares_process_fds() */
|
|
typedef struct {
|
|
ares_socket_t fd; /*!< File descriptor */
|
|
unsigned int events; /*!< Mask of ares_fd_event_t */
|
|
} ares_fd_events_t;
|
|
|
|
typedef enum {
|
|
ARES_PROCESS_FLAG_NONE = 0,
|
|
ARES_PROCESS_FLAG_SKIP_NON_FD = 1 << 0
|
|
} ares_process_flag_t;
|
|
|
|
|
|
ares_status_t ares_process_fds(ares_channel_t *\fIchannel\fP,
|
|
const ares_fd_events_t *\fIevents\fP,
|
|
size_t \fInevents\fP,
|
|
unsigned int \fIflags\fP)
|
|
|
|
void ares_process_fd(ares_channel_t *\fIchannel\fP,
|
|
ares_socket_t \fIread_fd\fP,
|
|
ares_socket_t \fIwrite_fd\fP)
|
|
|
|
void ares_process(ares_channel_t *\fIchannel\fP,
|
|
fd_set *\fIread_fds\fP,
|
|
fd_set *\fIwrite_fds\fP)
|
|
|
|
.fi
|
|
.SH DESCRIPTION
|
|
These functions must be used by integrators choosing not to use the
|
|
EventThread enabled via \fBARES_OPT_EVENT_THREAD\fP passed to
|
|
\fBares_init_options\fP. This assumes integrators already have their own
|
|
event loop handling event notifications for various file descriptors and
|
|
wish to do the same with their integration with c-ares.
|
|
|
|
The \fBares_process_fds(3)\fP function handles input/output events on file
|
|
descriptors and timeouts associated with queries pending on the channel
|
|
identified by \fIchannel\fP. The file descriptors to be processed are passed
|
|
in an array of \fIares_fd_events_t\fP data structures in the \fIfd\fP member,
|
|
and events are a bitwise mask of \fIares_fd_eventflag_t\fP in the \fIevent\fP
|
|
member. This function can also be used to process timeouts by passing NULL
|
|
to the \fIevents\fP member with \fInevents\fP value of 0. Flags may also be
|
|
specified in the \fIflags\fP field and are defined in \fBares_process_flag_t\fP.
|
|
|
|
\fBARES_PROCESS_FLAG_SKIP_NON_FD\fP can be specified to specifically skip any
|
|
processing unrelated to the file descriptor events passed in, examples include
|
|
timeout processing and cleanup handling. This is useful if an integrator
|
|
knows they will be sending multiple \fIares_process_fds(3)\fP requests and
|
|
wants to skip that extra processing. However, the integrator must send the
|
|
final request with the flag so that timeout and other processing gets performed
|
|
before their event loop waits on additional events.
|
|
|
|
It is allowable to use an \fIares_fd_events_t\fP with \fIevents\fP member of
|
|
value \fIARES_FD_EVENT_NONE\fP (0) if there are no events for a given file
|
|
descriptor if an integrator wishes to simply maintain an array with all
|
|
possible file descriptors and update readiness via the \fIevent\fP member.
|
|
|
|
This function will return \fIARES_ENOMEM\fP in out of memory conditions,
|
|
otherwise will return \fIARES_SUCCESS\fP.
|
|
|
|
This function is recommended over \fBares_process_fd(3)\fP since it can
|
|
handle processing of multiple file descriptors at once, thus skipping repeating
|
|
additional logic such as timeout processing which would be required if calling
|
|
\fBares_process_fd(3)\fP for multiple file descriptors notified at the same
|
|
time.
|
|
|
|
This function is typically used with the \fIARES_OPT_SOCK_STATE_CB\fP option.
|
|
|
|
\fBares_timeout(3)\fP should be used to retrieve the desired timeout, and when
|
|
the timeout expires, the integrator must call \fBares_process_fds(3)\fP with
|
|
a NULL \fIevents\fP array. (or \fBares_process_fd(3)\fP with both sockets set
|
|
to \fIARES_SOCKET_BAD\fP). There is no need to do this if events are also
|
|
delivered for any file descriptors as timeout processing will automatically be
|
|
handled by any call to \fBares_process_fds(3)\fP or \fBares_process_fd(3)\fP.
|
|
|
|
The \fBares_process_fd(3)\fP function is the same as \fBares_process_fds(3)\fP
|
|
except can only process a single read and write file descriptor at a time.
|
|
New integrators should use \fBares_process_fds(3)\fP if possible.
|
|
|
|
The \fBares_process(3)\fP function works in the same manner, except it works
|
|
on \fIfd_sets\fP as is used by \fBselect(3)\fP and retrieved by
|
|
\fBares_fds(3)\fP. This method is deprecated and should not be used in modern
|
|
applications due to known limitations to the \fBselect(3)\fP implementation.
|
|
|
|
.SH AVAILABILITY
|
|
\fBares_process_fds(3)\fP was introduced in c-ares 1.34.0.
|
|
|
|
.SH SEE ALSO
|
|
.BR ares_fds (3),
|
|
.BR ares_timeout (3),
|
|
.BR ares_init_options (3)
|
|
with \fIARES_OPT_EVENT_THREAD\fP or \fIARES_OPT_SOCK_STATE_CB\fP
|