docs/ares_process.3 - main - githubmirror/c-ares

docs/ares_process.3
109 строк5 KB
Brad House
More modularization for sockets/connections (#876)
08 сен 2024, 03:20
08 сен 2024, 03:20e0ef6a8
.\"
.\" 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