1 // Copyright 2023 The gRPC Authors 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #ifndef GRPC_SRC_CORE_LIB_EVENT_ENGINE_GRPC_POLLED_FD_H 16 #define GRPC_SRC_CORE_LIB_EVENT_ENGINE_GRPC_POLLED_FD_H 17 18 #include <grpc/event_engine/event_engine.h> 19 #include <grpc/support/port_platform.h> 20 21 #include <memory> 22 23 #if GRPC_ARES == 1 24 25 #include <ares.h> 26 27 #include "absl/functional/any_invocable.h" 28 #include "absl/status/status.h" 29 #include "src/core/util/sync.h" 30 31 namespace grpc_event_engine { 32 namespace experimental { 33 34 // A wrapped fd that integrates with the EventEngine poller of the current 35 // platform. A GrpcPolledFd knows how to create grpc platform-specific poller 36 // handle from "ares_socket_t" sockets, and then sign up for 37 // readability/writeability with that poller handle, and do shutdown and 38 // destruction. 39 class GrpcPolledFd { 40 public: ~GrpcPolledFd()41 virtual ~GrpcPolledFd() {} 42 // Called when c-ares library is interested and there's no pending callback 43 virtual void RegisterForOnReadableLocked( 44 absl::AnyInvocable<void(absl::Status)> read_closure) = 0; 45 // Called when c-ares library is interested and there's no pending callback 46 virtual void RegisterForOnWriteableLocked( 47 absl::AnyInvocable<void(absl::Status)> write_closure) = 0; 48 // Indicates if there is data left even after just being read from 49 virtual bool IsFdStillReadableLocked() = 0; 50 // Called once and only once. Must cause cancellation of any pending 51 // read/write callbacks. Return true when the Shutdown is confirmed, false 52 // otherwise. 53 // 54 // TODO(yijiem): On Posix, ShutdownLocked will always succeed. On Windows, 55 // ShutdownLocked only succeeds when error is Cancelled. We could remove these 56 // requirements if we changed the FdNode lifetime model so that: 57 // 1. FdNodes and their underlying socket handles remain alive for 58 // the lifetime of the resolver. 59 // 2. Orphaning the resolver triggers shutdown and subsequent cleanup for 60 // all FdNodes and socket handles. 61 GRPC_MUST_USE_RESULT virtual bool ShutdownLocked(absl::Status error) = 0; 62 // Get the underlying ares_socket_t that this was created from 63 virtual ares_socket_t GetWrappedAresSocketLocked() = 0; 64 // A unique name, for logging 65 virtual const char* GetName() const = 0; 66 }; 67 68 // A GrpcPolledFdFactory is 1-to-1 with and owned by a GrpcAresRequest. It knows 69 // how to create GrpcPolledFd's for the current platform, and the 70 // GrpcAresRequest uses it for all of its fd's. 71 class GrpcPolledFdFactory { 72 public: ~GrpcPolledFdFactory()73 virtual ~GrpcPolledFdFactory() {} 74 // Optionally initializes the GrpcPolledFdFactory with a grpc_core::Mutex* 75 // for synchronization between the AresResolver and the GrpcPolledFds. The 76 // Windows implementation overrides this. 77 virtual void Initialize(grpc_core::Mutex* mutex, 78 EventEngine* event_engine) = 0; 79 // Creates a new wrapped fd for the current platform 80 virtual std::unique_ptr<GrpcPolledFd> NewGrpcPolledFdLocked( 81 ares_socket_t as) = 0; 82 // Optionally configures the ares channel after creation 83 virtual void ConfigureAresChannelLocked(ares_channel channel) = 0; 84 }; 85 86 } // namespace experimental 87 } // namespace grpc_event_engine 88 89 #endif // GRPC_ARES == 1 90 #endif // GRPC_SRC_CORE_LIB_EVENT_ENGINE_GRPC_POLLED_FD_H 91