"Fossies" - the Fresh Open Source Software Archive

Member "bind-9.16.7/lib/isc/include/isc/netmgr.h" (4 Sep 2020, 11158 Bytes) of package /linux/misc/dns/bind9/9.16.7/bind-9.16.7.tar.xz:


As a special service "Fossies" has tried to format the requested source page into HTML format using (guessed) C and C++ source code syntax highlighting (style: standard) with prefixed line numbers and code folding option. Alternatively you can here view or download the uninterpreted source code file. For more information about "netmgr.h" see the Fossies "Dox" file reference documentation and the last Fossies "Diffs" side-by-side code changes report: 9.17.3_vs_9.17.4.

    1 /*
    2  * Copyright (C) Internet Systems Consortium, Inc. ("ISC")
    3  *
    4  * This Source Code Form is subject to the terms of the Mozilla Public
    5  * License, v. 2.0. If a copy of the MPL was not distributed with this
    6  * file, You can obtain one at http://mozilla.org/MPL/2.0/.
    7  *
    8  * See the COPYRIGHT file distributed with this work for additional
    9  * information regarding copyright ownership.
   10  */
   11 
   12 #pragma once
   13 
   14 #include <isc/mem.h>
   15 #include <isc/result.h>
   16 #include <isc/types.h>
   17 
   18 typedef enum {
   19     NMEV_READ,
   20     NMEV_WRITE,
   21     NMEV_ACCEPT,
   22     NMEV_CONNECTED,
   23     NMEV_CANCELLED,
   24     NMEV_SHUTDOWN
   25 } isc_nm_eventtype;
   26 
   27 typedef void (*isc_nm_recv_cb_t)(isc_nmhandle_t *handle, isc_region_t *region,
   28                  void *cbarg);
   29 /*%<
   30  * Callback function to be used when receiving a packet.
   31  *
   32  * 'handle' the handle that can be used to send back the answer.
   33  * 'region' contains the received data. It will be freed after
   34  *          return by caller.
   35  * 'cbarg'  the callback argument passed to isc_nm_listenudp(),
   36  *          isc_nm_listentcpdns(), or isc_nm_read().
   37  */
   38 
   39 typedef isc_result_t (*isc_nm_accept_cb_t)(isc_nmhandle_t *handle,
   40                        isc_result_t result, void *cbarg);
   41 /*%<
   42  * Callback function to be used when accepting a connection. (This differs
   43  * from isc_nm_cb_t below in that it returns a result code.)
   44  *
   45  * 'handle' the handle that can be used to send back the answer.
   46  * 'eresult' the result of the event.
   47  * 'cbarg'  the callback argument passed to isc_nm_listentcp() or
   48  * isc_nm_listentcpdns().
   49  */
   50 
   51 typedef void (*isc_nm_cb_t)(isc_nmhandle_t *handle, isc_result_t result,
   52                 void *cbarg);
   53 /*%<
   54  * Callback function for other network completion events (send, connect).
   55  *
   56  * 'handle' the handle on which the event took place.
   57  * 'eresult' the result of the event.
   58  * 'cbarg'  the callback argument passed to isc_nm_send(),
   59  *          isc_nm_tcp_connect(), or isc_nm_listentcp()
   60  */
   61 
   62 typedef void (*isc_nm_opaquecb_t)(void *arg);
   63 /*%<
   64  * Opaque callback function, used for isc_nmhandle 'reset' and 'free'
   65  * callbacks.
   66  */
   67 
   68 isc_nm_t *
   69 isc_nm_start(isc_mem_t *mctx, uint32_t workers);
   70 /*%<
   71  * Creates a new network manager with 'workers' worker threads,
   72  * and starts it running.
   73  */
   74 
   75 void
   76 isc_nm_attach(isc_nm_t *mgr, isc_nm_t **dst);
   77 void
   78 isc_nm_detach(isc_nm_t **mgr0);
   79 void
   80 isc_nm_destroy(isc_nm_t **mgr0);
   81 /*%<
   82  * Attach/detach a network manager. When all references have been
   83  * released, the network manager is shut down, freeing all resources.
   84  * Destroy is working the same way as detach, but it actively waits
   85  * for all other references to be gone.
   86  */
   87 
   88 void
   89 isc_nm_closedown(isc_nm_t *mgr);
   90 /*%<
   91  * Close down all active connections, freeing associated resources;
   92  * prevent new connections from being established. This can optionally
   93  * be called prior to shutting down the netmgr, to stop all processing
   94  * before shutting down the task manager.
   95  */
   96 
   97 /* Return thread ID of current thread, or ISC_NETMGR_TID_UNKNOWN */
   98 int
   99 isc_nm_tid(void);
  100 
  101 /*
  102  * isc_nm_freehandle frees a handle, releasing resources
  103  */
  104 void
  105 isc_nm_freehandle(isc_nmhandle_t *handle);
  106 
  107 void
  108 isc_nmsocket_attach(isc_nmsocket_t *sock, isc_nmsocket_t **target);
  109 /*%<
  110  * isc_nmsocket_attach attaches to a socket, increasing refcount
  111  */
  112 
  113 void
  114 isc_nmsocket_close(isc_nmsocket_t *sock);
  115 
  116 void
  117 isc_nmsocket_detach(isc_nmsocket_t **socketp);
  118 /*%<
  119  * isc_nmsocket_detach detaches from socket, decreasing refcount
  120  * and possibly destroying the socket if it's no longer referenced.
  121  */
  122 
  123 void
  124 isc_nmhandle_ref(isc_nmhandle_t *handle);
  125 void
  126 isc_nmhandle_unref(isc_nmhandle_t *handle);
  127 /*%<
  128  * Increment/decrement the reference counter in a netmgr handle,
  129  * but (unlike the attach/detach functions) do not change the pointer
  130  * value. If reference counters drop to zero, the handle can be
  131  * marked inactive, possibly triggering deletion of its associated
  132  * socket.
  133  *
  134  * (This will be used to prevent a client from being cleaned up when
  135  * it's passed to an isc_task event handler. The libuv code would not
  136  * otherwise know that the handle was in use and might free it, along
  137  * with the client.)
  138  */
  139 
  140 void *
  141 isc_nmhandle_getdata(isc_nmhandle_t *handle);
  142 
  143 void *
  144 isc_nmhandle_getextra(isc_nmhandle_t *handle);
  145 
  146 bool
  147 isc_nmhandle_is_stream(isc_nmhandle_t *handle);
  148 
  149 /*
  150  * isc_nmhandle_t has a void * opaque field (usually - ns_client_t).
  151  * We reuse handle and `opaque` can also be reused between calls.
  152  * This function sets this field and two callbacks:
  153  * - doreset resets the `opaque` to initial state
  154  * - dofree frees everything associated with `opaque`
  155  */
  156 void
  157 isc_nmhandle_setdata(isc_nmhandle_t *handle, void *arg,
  158              isc_nm_opaquecb_t doreset, isc_nm_opaquecb_t dofree);
  159 
  160 isc_sockaddr_t
  161 isc_nmhandle_peeraddr(isc_nmhandle_t *handle);
  162 /*%<
  163  * Return the peer address for the given handle.
  164  */
  165 isc_sockaddr_t
  166 isc_nmhandle_localaddr(isc_nmhandle_t *handle);
  167 /*%<
  168  * Return the local address for the given handle.
  169  */
  170 
  171 isc_nm_t *
  172 isc_nmhandle_netmgr(isc_nmhandle_t *handle);
  173 /*%<
  174  * Return a pointer to the netmgr object for the given handle.
  175  */
  176 
  177 isc_result_t
  178 isc_nm_listenudp(isc_nm_t *mgr, isc_nmiface_t *iface, isc_nm_recv_cb_t cb,
  179          void *cbarg, size_t extrasize, isc_nmsocket_t **sockp);
  180 /*%<
  181  * Start listening for UDP packets on interface 'iface' using net manager
  182  * 'mgr'.
  183  *
  184  * On success, 'sockp' will be updated to contain a new listening UDP socket.
  185  *
  186  * When a packet is received on the socket, 'cb' will be called with 'cbarg'
  187  * as its argument.
  188  *
  189  * When handles are allocated for the socket, 'extrasize' additional bytes
  190  * will be allocated along with the handle for an associated object
  191  * (typically ns_client).
  192  */
  193 
  194 void
  195 isc_nm_stoplistening(isc_nmsocket_t *sock);
  196 /*%<
  197  * Stop listening on socket 'sock'.
  198  */
  199 
  200 void
  201 isc_nm_pause(isc_nm_t *mgr);
  202 /*%<
  203  * Pause all processing, equivalent to taskmgr exclusive tasks.
  204  * It won't return until all workers have been paused.
  205  */
  206 
  207 void
  208 isc_nm_resume(isc_nm_t *mgr);
  209 /*%<
  210  * Resume paused processing. It will return immediately
  211  * after signalling workers to resume.
  212  */
  213 
  214 isc_result_t
  215 isc_nm_read(isc_nmhandle_t *handle, isc_nm_recv_cb_t cb, void *cbarg);
  216 
  217 isc_result_t
  218 isc_nm_pauseread(isc_nmsocket_t *sock);
  219 /*%<
  220  * Pause reading on this socket, while still remembering the callback.
  221  */
  222 
  223 isc_result_t
  224 isc_nm_resumeread(isc_nmsocket_t *sock);
  225 /*%<
  226  * Resume reading from socket.
  227  *
  228  * Requires:
  229  * \li  'sock' is a valid netmgr socket
  230  * \li  ...for which a read/recv callback has been defined.
  231  */
  232 
  233 isc_result_t
  234 isc_nm_send(isc_nmhandle_t *handle, isc_region_t *region, isc_nm_cb_t cb,
  235         void *cbarg);
  236 /*%<
  237  * Send the data in 'region' via 'handle'. Afterward, the callback 'cb' is
  238  * called with the argument 'cbarg'.
  239  *
  240  * 'region' is not copied; it has to be allocated beforehand and freed
  241  * in 'cb'.
  242  */
  243 
  244 isc_result_t
  245 isc_nm_listentcp(isc_nm_t *mgr, isc_nmiface_t *iface,
  246          isc_nm_accept_cb_t accept_cb, void *accept_cbarg,
  247          size_t extrahandlesize, int backlog, isc_quota_t *quota,
  248          isc_nmsocket_t **sockp);
  249 /*%<
  250  * Start listening for raw messages over the TCP interface 'iface', using
  251  * net manager 'mgr'.
  252  *
  253  * On success, 'sockp' will be updated to contain a new listening TCP
  254  * socket.
  255  *
  256  * When connection is accepted on the socket, 'accept_cb' will be called with
  257  * 'accept_cbarg' as its argument. The callback is expected to start a read.
  258  *
  259  * When handles are allocated for the socket, 'extrasize' additional bytes
  260  * will be allocated along with the handle for an associated object.
  261  *
  262  * If 'quota' is not NULL, then the socket is attached to the specified
  263  * quota. This allows us to enforce TCP client quota limits.
  264  *
  265  * NOTE: This is currently only called inside isc_nm_listentcpdns(), which
  266  * creates a 'wrapper' socket that sends and receives DNS messages
  267  * prepended with a two-byte length field, and handles buffering.
  268  */
  269 
  270 isc_result_t
  271 isc_nm_listentcpdns(isc_nm_t *mgr, isc_nmiface_t *iface, isc_nm_recv_cb_t cb,
  272             void *cbarg, isc_nm_accept_cb_t accept_cb,
  273             void *accept_cbarg, size_t extrahandlesize, int backlog,
  274             isc_quota_t *quota, isc_nmsocket_t **sockp);
  275 /*%<
  276  * Start listening for DNS messages over the TCP interface 'iface', using
  277  * net manager 'mgr'.
  278  *
  279  * On success, 'sockp' will be updated to contain a new listening TCPDNS
  280  * socket. This is a wrapper around a raw TCP socket, which sends and
  281  * receives DNS messages via that socket. It handles message buffering
  282  * and pipelining, and automatically prepends messages with a two-byte
  283  * length field.
  284  *
  285  * When a complete DNS message is received on the socket, 'cb' will be
  286  * called with 'cbarg' as its argument.
  287  *
  288  * When a new TCPDNS connection is accepted, 'accept_cb' will be called
  289  * with 'accept_cbarg' as its argument.
  290  *
  291  * When handles are allocated for the socket, 'extrasize' additional bytes
  292  * will be allocated along with the handle for an associated object
  293  * (typically ns_client).
  294  *
  295  * 'quota' is passed to isc_nm_listentcp() when opening the raw TCP socket.
  296  */
  297 
  298 void
  299 isc_nm_tcpdns_sequential(isc_nmhandle_t *handle);
  300 /*%<
  301  * Disable pipelining on this connection. Each DNS packet will be only
  302  * processed after the previous completes.
  303  *
  304  * The socket must be unpaused after the query is processed.  This is done
  305  * the response is sent, or if we're dropping the query, it will be done
  306  * when a handle is fully dereferenced by calling the socket's
  307  * closehandle_cb callback.
  308  *
  309  * Note: This can only be run while a message is being processed; if it is
  310  * run before any messages are read, no messages will be read.
  311  *
  312  * Also note: once this has been set, it cannot be reversed for a given
  313  * connection.
  314  */
  315 
  316 void
  317 isc_nm_tcpdns_keepalive(isc_nmhandle_t *handle);
  318 /*%<
  319  * Enable keepalive on this connection.
  320  *
  321  * When keepalive is active, we switch to using the keepalive timeout
  322  * to determine when to close a connection, rather than the idle timeout.
  323  */
  324 
  325 void
  326 isc_nm_tcp_settimeouts(isc_nm_t *mgr, uint32_t init, uint32_t idle,
  327                uint32_t keepalive, uint32_t advertised);
  328 /*%<
  329  * Sets the initial, idle, and keepalive timeout values to use for
  330  * TCP connections, and the timeout value to advertise in responses using
  331  * the EDNS TCP Keepalive option (which should ordinarily be the same
  332  * as 'keepalive'), in tenths of seconds.
  333  *
  334  * Requires:
  335  * \li  'mgr' is a valid netmgr.
  336  */
  337 
  338 void
  339 isc_nm_tcp_gettimeouts(isc_nm_t *mgr, uint32_t *initial, uint32_t *idle,
  340                uint32_t *keepalive, uint32_t *advertised);
  341 /*%<
  342  * Gets the initial, idle, keepalive, or advertised timeout values,
  343  * in tenths of seconds.
  344  *
  345  * Any integer pointer parameter not set to NULL will be updated to
  346  * contain the corresponding timeout value.
  347  *
  348  * Requires:
  349  * \li  'mgr' is a valid netmgr.
  350  */
  351 
  352 void
  353 isc_nm_maxudp(isc_nm_t *mgr, uint32_t maxudp);
  354 /*%<
  355  * Simulate a broken firewall that blocks UDP messages larger than a given
  356  * size.
  357  */
  358 
  359 void
  360 isc_nm_setstats(isc_nm_t *mgr, isc_stats_t *stats);
  361 /*%<
  362  * Set a socket statistics counter set 'stats' for 'mgr'.
  363  *
  364  * Requires:
  365  *\li   'mgr' is valid and doesn't have stats already set.
  366  *
  367  *\li   stats is a valid set of statistics counters supporting the
  368  *  full range of socket-related stats counter numbers.
  369  */