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/support/port_platform.h> 19 20 #include <memory> 21 22 #include <grpc/event_engine/event_engine.h> 23 24 #if GRPC_ARES == 1 25 26 #include <ares.h> 27 28 #include "absl/functional/any_invocable.h" 29 #include "absl/status/status.h" 30 31 #include "src/core/lib/gprpp/sync.h" 32 33 namespace grpc_event_engine { 34 namespace experimental { 35 36 // A wrapped fd that integrates with the EventEngine poller of the current 37 // platform. A GrpcPolledFd knows how to create grpc platform-specific poller 38 // handle from "ares_socket_t" sockets, and then sign up for 39 // readability/writeability with that poller handle, and do shutdown and 40 // destruction. 41 class GrpcPolledFd { 42 public: ~GrpcPolledFd()43 virtual ~GrpcPolledFd() {} 44 // Called when c-ares library is interested and there's no pending callback 45 virtual void RegisterForOnReadableLocked( 46 absl::AnyInvocable<void(absl::Status)> read_closure) = 0; 47 // Called when c-ares library is interested and there's no pending callback 48 virtual void RegisterForOnWriteableLocked( 49 absl::AnyInvocable<void(absl::Status)> write_closure) = 0; 50 // Indicates if there is data left even after just being read from 51 virtual bool IsFdStillReadableLocked() = 0; 52 // Called once and only once. Must cause cancellation of any pending 53 // read/write callbacks. Return true when the Shutdown is confirmed, false 54 // otherwise. 55 // 56 // TODO(yijiem): On Posix, ShutdownLocked will always succeed. On Windows, 57 // ShutdownLocked only succeeds when error is Cancelled. We could remove these 58 // requirements if we changed the FdNode lifetime model so that: 59 // 1. FdNodes and their underlying socket handles remain alive for 60 // the lifetime of the resolver. 61 // 2. Orphaning the resolver triggers shutdown and subsequent cleanup for 62 // all FdNodes and socket handles. 63 GRPC_MUST_USE_RESULT virtual bool ShutdownLocked(absl::Status error) = 0; 64 // Get the underlying ares_socket_t that this was created from 65 virtual ares_socket_t GetWrappedAresSocketLocked() = 0; 66 // A unique name, for logging 67 virtual const char* GetName() const = 0; 68 }; 69 70 // A GrpcPolledFdFactory is 1-to-1 with and owned by a GrpcAresRequest. It knows 71 // how to create GrpcPolledFd's for the current platform, and the 72 // GrpcAresRequest uses it for all of its fd's. 73 class GrpcPolledFdFactory { 74 public: ~GrpcPolledFdFactory()75 virtual ~GrpcPolledFdFactory() {} 76 // Optionally initializes the GrpcPolledFdFactory with a grpc_core::Mutex* 77 // for synchronization between the AresResolver and the GrpcPolledFds. The 78 // Windows implementation overrides this. 79 virtual void Initialize(grpc_core::Mutex* mutex, 80 EventEngine* event_engine) = 0; 81 // Creates a new wrapped fd for the current platform 82 virtual std::unique_ptr<GrpcPolledFd> NewGrpcPolledFdLocked( 83 ares_socket_t as) = 0; 84 // Optionally configures the ares channel after creation 85 virtual void ConfigureAresChannelLocked(ares_channel channel) = 0; 86 }; 87 88 } // namespace experimental 89 } // namespace grpc_event_engine 90 91 #endif // GRPC_ARES == 1 92 #endif // GRPC_SRC_CORE_LIB_EVENT_ENGINE_GRPC_POLLED_FD_H 93