1 // Copyright 2022 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_POSIX_ENGINE_EVENT_POLLER_H 16 #define GRPC_SRC_CORE_LIB_EVENT_ENGINE_POSIX_ENGINE_EVENT_POLLER_H 17 #include <grpc/event_engine/event_engine.h> 18 #include <grpc/support/port_platform.h> 19 20 #include <string> 21 22 #include "absl/functional/any_invocable.h" 23 #include "absl/status/status.h" 24 #include "absl/strings/string_view.h" 25 #include "src/core/lib/event_engine/forkable.h" 26 #include "src/core/lib/event_engine/poller.h" 27 #include "src/core/lib/event_engine/posix_engine/posix_engine_closure.h" 28 29 namespace grpc_event_engine { 30 namespace experimental { 31 32 class Scheduler { 33 public: 34 virtual void Run(experimental::EventEngine::Closure* closure) = 0; 35 virtual void Run(absl::AnyInvocable<void()>) = 0; 36 virtual ~Scheduler() = default; 37 }; 38 39 class PosixEventPoller; 40 41 class EventHandle { 42 public: 43 virtual int WrappedFd() = 0; 44 // Delete the handle and optionally close the underlying file descriptor if 45 // release_fd != nullptr. The on_done closure is scheduled to be invoked 46 // after the operation is complete. After this operation, NotifyXXX and SetXXX 47 // operations cannot be performed on the handle. In general, this method 48 // should only be called after ShutdownHandle and after all existing NotifyXXX 49 // closures have run and there is no waiting NotifyXXX closure. 50 virtual void OrphanHandle(PosixEngineClosure* on_done, int* release_fd, 51 absl::string_view reason) = 0; 52 // Shutdown a handle. If there is an attempt to call NotifyXXX operations 53 // after Shutdown handle, those closures will be run immediately with the 54 // absl::Status provided here being passed to the callbacks enclosed within 55 // the PosixEngineClosure object. 56 virtual void ShutdownHandle(absl::Status why) = 0; 57 // Schedule on_read to be invoked when the underlying file descriptor 58 // becomes readable. When the on_read closure is run, it may check 59 // if the handle is shutdown using the IsHandleShutdown method and take 60 // appropriate actions (for instance it should not try to invoke another 61 // recursive NotifyOnRead if the handle is shutdown). 62 virtual void NotifyOnRead(PosixEngineClosure* on_read) = 0; 63 // Schedule on_write to be invoked when the underlying file descriptor 64 // becomes writable. When the on_write closure is run, it may check 65 // if the handle is shutdown using the IsHandleShutdown method and take 66 // appropriate actions (for instance it should not try to invoke another 67 // recursive NotifyOnWrite if the handle is shutdown). 68 virtual void NotifyOnWrite(PosixEngineClosure* on_write) = 0; 69 // Schedule on_error to be invoked when the underlying file descriptor 70 // encounters errors. When the on_error closure is run, it may check 71 // if the handle is shutdown using the IsHandleShutdown method and take 72 // appropriate actions (for instance it should not try to invoke another 73 // recursive NotifyOnError if the handle is shutdown). 74 virtual void NotifyOnError(PosixEngineClosure* on_error) = 0; 75 // Force set a readable event on the underlying file descriptor. 76 virtual void SetReadable() = 0; 77 // Force set a writable event on the underlying file descriptor. 78 virtual void SetWritable() = 0; 79 // Force set a error event on the underlying file descriptor. 80 virtual void SetHasError() = 0; 81 // Returns true if the handle has been shutdown. 82 virtual bool IsHandleShutdown() = 0; 83 // Returns the poller which was used to create this handle. 84 virtual PosixEventPoller* Poller() = 0; 85 virtual ~EventHandle() = default; 86 }; 87 88 class PosixEventPoller : public grpc_event_engine::experimental::Poller, 89 public Forkable { 90 public: 91 // Return an opaque handle to perform actions on the provided file descriptor. 92 virtual EventHandle* CreateHandle(int fd, absl::string_view name, 93 bool track_err) = 0; 94 virtual bool CanTrackErrors() const = 0; 95 virtual std::string Name() = 0; 96 // Shuts down and deletes the poller. It is legal to call this function 97 // only when no other poller method is in progress. For instance, it is 98 // not safe to call this method, while a thread is blocked on Work(...). 99 // A graceful way to terminate the poller could be to: 100 // 1. First orphan all created handles. 101 // 2. Send a Kick() to the thread executing Work(...) and wait for the 102 // thread to return. 103 // 3. Call Shutdown() on the poller. 104 virtual void Shutdown() = 0; 105 ~PosixEventPoller() override = default; 106 }; 107 108 } // namespace experimental 109 } // namespace grpc_event_engine 110 111 #endif // GRPC_SRC_CORE_LIB_EVENT_ENGINE_POSIX_ENGINE_EVENT_POLLER_H 112