legacy-libs/grpc-cloned/deps/grpc/src/core/ext/filters/client_channel/resolver/dns/c_ares/grpc_ares_ev_driver.h

   1 /*
   2  *
   3  * Copyright 2016 gRPC authors.
   4  *
   5  * Licensed under the Apache License, Version 2.0 (the "License");
   6  * you may not use this file except in compliance with the License.
   7  * You may obtain a copy of the License at
   8  *
   9  *     http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  * Unless required by applicable law or agreed to in writing, software
  12  * distributed under the License is distributed on an "AS IS" BASIS,
  13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  * See the License for the specific language governing permissions and
  15  * limitations under the License.
  16  *
  17  */
  18
  19 #ifndef GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_RESOLVER_DNS_C_ARES_GRPC_ARES_EV_DRIVER_H
  20 #define GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_RESOLVER_DNS_C_ARES_GRPC_ARES_EV_DRIVER_H
  21
  22 #include <grpc/support/port_platform.h>
  23
  24 #include <ares.h>
  25 #include "src/core/ext/filters/client_channel/resolver/dns/c_ares/grpc_ares_wrapper.h"
  26 #include "src/core/lib/gprpp/abstract.h"
  27 #include "src/core/lib/iomgr/pollset_set.h"
  28
  29 typedef struct grpc_ares_ev_driver grpc_ares_ev_driver;
  30
  31 /* Start \a ev_driver. It will keep working until all IO on its ares_channel is
  32    done, or grpc_ares_ev_driver_destroy() is called. It may notify the callbacks
  33    bound to its ares_channel when necessary. */
  34 void grpc_ares_ev_driver_start_locked(grpc_ares_ev_driver* ev_driver);
  35
  36 /* Returns the ares_channel owned by \a ev_driver. To bind a c-ares query to
  37    \a ev_driver, use the ares_channel owned by \a ev_driver as the arg of the
  38    query. */
  39 ares_channel* grpc_ares_ev_driver_get_channel_locked(
  40     grpc_ares_ev_driver* ev_driver);
  41
  42 /* Creates a new grpc_ares_ev_driver. Returns GRPC_ERROR_NONE if \a ev_driver is
  43    created successfully. */
  44 grpc_error* grpc_ares_ev_driver_create_locked(grpc_ares_ev_driver** ev_driver,
  45                                               grpc_pollset_set* pollset_set,
  46                                               int query_timeout_ms,
  47                                               grpc_combiner* combiner,
  48                                               grpc_ares_request* request);
  49
  50 /* Called back when all DNS lookups have completed. */
  51 void grpc_ares_ev_driver_on_queries_complete_locked(
  52     grpc_ares_ev_driver* ev_driver);
  53
  54 /* Shutdown all the grpc_fds used by \a ev_driver */
  55 void grpc_ares_ev_driver_shutdown_locked(grpc_ares_ev_driver* ev_driver);
  56
  57 /* Exposed in this header for C-core tests only */
  58 extern void (*grpc_ares_test_only_inject_config)(ares_channel channel);
  59
  60 namespace grpc_core {
  61
  62 /* A wrapped fd that integrates with the grpc iomgr of the current platform.
  63  * A GrpcPolledFd knows how to create grpc platform-specific iomgr endpoints
  64  * from "ares_socket_t" sockets, and then sign up for readability/writeability
  65  * with that poller, and do shutdown and destruction. */
  66 class GrpcPolledFd {
  67  public:
  68   virtual ~GrpcPolledFd() {}
  69   /* Called when c-ares library is interested and there's no pending callback */
  70   virtual void RegisterForOnReadableLocked(grpc_closure* read_closure)
  71       GRPC_ABSTRACT;
  72   /* Called when c-ares library is interested and there's no pending callback */
  73   virtual void RegisterForOnWriteableLocked(grpc_closure* write_closure)
  74       GRPC_ABSTRACT;
  75   /* Indicates if there is data left even after just being read from */
  76   virtual bool IsFdStillReadableLocked() GRPC_ABSTRACT;
  77   /* Called once and only once. Must cause cancellation of any pending
  78    * read/write callbacks. */
  79   virtual void ShutdownLocked(grpc_error* error) GRPC_ABSTRACT;
  80   /* Get the underlying ares_socket_t that this was created from */
  81   virtual ares_socket_t GetWrappedAresSocketLocked() GRPC_ABSTRACT;
  82   /* A unique name, for logging */
  83   virtual const char* GetName() GRPC_ABSTRACT;
  84
  85   GRPC_ABSTRACT_BASE_CLASS
  86 };
  87
  88 /* A GrpcPolledFdFactory is 1-to-1 with and owned by the
  89  * ares event driver. It knows how to create GrpcPolledFd's
  90  * for the current platform, and the ares driver uses it for all of
  91  * its fd's. */
  92 class GrpcPolledFdFactory {
  93  public:
  94   virtual ~GrpcPolledFdFactory() {}
  95   /* Creates a new wrapped fd for the current platform */
  96   virtual GrpcPolledFd* NewGrpcPolledFdLocked(
  97       ares_socket_t as, grpc_pollset_set* driver_pollset_set,
  98       grpc_combiner* combiner) GRPC_ABSTRACT;
  99   /* Optionally configures the ares channel after creation */
 100   virtual void ConfigureAresChannelLocked(ares_channel channel) GRPC_ABSTRACT;
 101
 102   GRPC_ABSTRACT_BASE_CLASS
 103 };
 104
 105 UniquePtr<GrpcPolledFdFactory> NewGrpcPolledFdFactory(grpc_combiner* combiner);
 106
 107 }  // namespace grpc_core
 108
 109 #endif /* GRPC_CORE_EXT_FILTERS_CLIENT_CHANNEL_RESOLVER_DNS_C_ARES_GRPC_ARES_EV_DRIVER_H \
 110         */