1 // 2 // 3 // Copyright 2015 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_SRC_CORE_LIB_IOMGR_EV_POSIX_H 20 #define GRPC_SRC_CORE_LIB_IOMGR_EV_POSIX_H 21 22 #include "src/core/lib/iomgr/port.h" 23 24 #ifdef GRPC_POSIX_SOCKET_EV 25 26 #include <grpc/support/port_platform.h> 27 #include <poll.h> 28 29 #include "src/core/lib/debug/trace.h" 30 #include "src/core/lib/iomgr/exec_ctx.h" 31 #include "src/core/lib/iomgr/pollset.h" 32 #include "src/core/lib/iomgr/pollset_set.h" 33 #include "src/core/lib/iomgr/wakeup_fd_posix.h" 34 35 typedef struct grpc_fd grpc_fd; 36 37 typedef struct grpc_event_engine_vtable { 38 size_t pollset_size; 39 bool can_track_err; 40 bool run_in_background; 41 42 grpc_fd* (*fd_create)(int fd, const char* name, bool track_err); 43 int (*fd_wrapped_fd)(grpc_fd* fd); 44 void (*fd_orphan)(grpc_fd* fd, grpc_closure* on_done, int* release_fd, 45 const char* reason); 46 void (*fd_shutdown)(grpc_fd* fd, grpc_error_handle why); 47 void (*fd_notify_on_read)(grpc_fd* fd, grpc_closure* closure); 48 void (*fd_notify_on_write)(grpc_fd* fd, grpc_closure* closure); 49 void (*fd_notify_on_error)(grpc_fd* fd, grpc_closure* closure); 50 void (*fd_set_readable)(grpc_fd* fd); 51 void (*fd_set_writable)(grpc_fd* fd); 52 void (*fd_set_error)(grpc_fd* fd); 53 bool (*fd_is_shutdown)(grpc_fd* fd); 54 55 void (*pollset_init)(grpc_pollset* pollset, gpr_mu** mu); 56 void (*pollset_shutdown)(grpc_pollset* pollset, grpc_closure* closure); 57 void (*pollset_destroy)(grpc_pollset* pollset); 58 grpc_error_handle (*pollset_work)(grpc_pollset* pollset, 59 grpc_pollset_worker** worker, 60 grpc_core::Timestamp deadline); 61 grpc_error_handle (*pollset_kick)(grpc_pollset* pollset, 62 grpc_pollset_worker* specific_worker); 63 void (*pollset_add_fd)(grpc_pollset* pollset, struct grpc_fd* fd); 64 65 grpc_pollset_set* (*pollset_set_create)(void); 66 void (*pollset_set_destroy)(grpc_pollset_set* pollset_set); 67 void (*pollset_set_add_pollset)(grpc_pollset_set* pollset_set, 68 grpc_pollset* pollset); 69 void (*pollset_set_del_pollset)(grpc_pollset_set* pollset_set, 70 grpc_pollset* pollset); 71 void (*pollset_set_add_pollset_set)(grpc_pollset_set* bag, 72 grpc_pollset_set* item); 73 void (*pollset_set_del_pollset_set)(grpc_pollset_set* bag, 74 grpc_pollset_set* item); 75 void (*pollset_set_add_fd)(grpc_pollset_set* pollset_set, grpc_fd* fd); 76 void (*pollset_set_del_fd)(grpc_pollset_set* pollset_set, grpc_fd* fd); 77 78 bool (*is_any_background_poller_thread)(void); 79 const char* name; 80 bool (*check_engine_available)(bool explicit_request); 81 void (*init_engine)(); 82 void (*shutdown_background_closure)(void); 83 void (*shutdown_engine)(void); 84 bool (*add_closure_to_background_poller)(grpc_closure* closure, 85 grpc_error_handle error); 86 87 void (*fd_set_pre_allocated)(grpc_fd* fd); 88 } grpc_event_engine_vtable; 89 90 // register a new event engine factory 91 void grpc_register_event_engine_factory(const grpc_event_engine_vtable* vtable, 92 bool add_at_head); 93 94 void grpc_event_engine_init(void); 95 void grpc_event_engine_shutdown(void); 96 97 // Returns true if polling engine can track errors separately, false otherwise. 98 // If this is true, fd can be created with track_err set. After this, error 99 // events will be reported using fd_notify_on_error. If it is not set, errors 100 // will continue to be reported through fd_notify_on_read and 101 // fd_notify_on_write. 102 // 103 bool grpc_event_engine_can_track_errors(); 104 105 // Returns true if polling engine runs in the background, false otherwise. 106 // Currently only 'epollbg' runs in the background. 107 // 108 bool grpc_event_engine_run_in_background(); 109 110 // Create a wrapped file descriptor. 111 // Requires fd is a non-blocking file descriptor. 112 // \a track_err if true means that error events would be tracked separately 113 // using grpc_fd_notify_on_error. Currently, valid only for linux systems. 114 // This takes ownership of closing fd. 115 grpc_fd* grpc_fd_create(int fd, const char* name, bool track_err); 116 117 // Return the wrapped fd, or -1 if it has been released or closed. 118 int grpc_fd_wrapped_fd(grpc_fd* fd); 119 120 // Releases fd to be asynchronously destroyed. 121 // on_done is called when the underlying file descriptor is definitely close()d. 122 // If on_done is NULL, no callback will be made. 123 // If release_fd is not NULL, it's set to fd and fd will not be closed. 124 // Requires: *fd initialized; no outstanding notify_on_read or 125 // notify_on_write. 126 // MUST NOT be called with a pollset lock taken 127 void grpc_fd_orphan(grpc_fd* fd, grpc_closure* on_done, int* release_fd, 128 const char* reason); 129 130 // Has grpc_fd_shutdown been called on an fd? 131 bool grpc_fd_is_shutdown(grpc_fd* fd); 132 133 // Cause any current and future callbacks to fail. 134 void grpc_fd_shutdown(grpc_fd* fd, grpc_error_handle why); 135 136 // Register read interest, causing read_cb to be called once when fd becomes 137 // readable, on deadline specified by deadline, or on shutdown triggered by 138 // grpc_fd_shutdown. 139 // read_cb will be called with read_cb_arg when *fd becomes readable. 140 // read_cb is Called with status of GRPC_CALLBACK_SUCCESS if readable, 141 // GRPC_CALLBACK_TIMED_OUT if the call timed out, 142 // and CANCELLED if the call was cancelled. 143 144 // Requires:This method must not be called before the read_cb for any previous 145 // call runs. Edge triggered events are used whenever they are supported by the 146 // underlying platform. This means that users must drain fd in read_cb before 147 // calling notify_on_read again. Users are also expected to handle spurious 148 // events, i.e read_cb is called while nothing can be readable from fd 149 void grpc_fd_notify_on_read(grpc_fd* fd, grpc_closure* closure); 150 151 // Exactly the same semantics as above, except based on writable events. 152 void grpc_fd_notify_on_write(grpc_fd* fd, grpc_closure* closure); 153 154 // Exactly the same semantics as above, except based on error events. track_err 155 // needs to have been set on grpc_fd_create 156 void grpc_fd_notify_on_error(grpc_fd* fd, grpc_closure* closure); 157 158 // Forcibly set the fd to be readable, resulting in the closure registered with 159 // grpc_fd_notify_on_read being invoked. 160 // 161 void grpc_fd_set_readable(grpc_fd* fd); 162 163 // Forcibly set the fd to be writable, resulting in the closure registered with 164 // grpc_fd_notify_on_write being invoked. 165 // 166 void grpc_fd_set_writable(grpc_fd* fd); 167 168 // Forcibly set the fd to have errored, resulting in the closure registered with 169 // grpc_fd_notify_on_error being invoked. 170 // 171 void grpc_fd_set_error(grpc_fd* fd); 172 173 // Set the fd to be preallocated 174 void grpc_fd_set_pre_allocated(grpc_fd* fd); 175 176 // pollset_posix functions 177 178 // Add an fd to a pollset 179 void grpc_pollset_add_fd(grpc_pollset* pollset, struct grpc_fd* fd); 180 181 // pollset_set_posix functions 182 183 void grpc_pollset_set_add_fd(grpc_pollset_set* pollset_set, grpc_fd* fd); 184 void grpc_pollset_set_del_fd(grpc_pollset_set* pollset_set, grpc_fd* fd); 185 186 // Returns true if the caller is a worker thread for any background poller. 187 bool grpc_is_any_background_poller_thread(); 188 189 // Returns true if the closure is registered into the background poller. Note 190 // that the closure may or may not run yet when this function returns, and the 191 // closure should not be blocking or long-running. 192 bool grpc_add_closure_to_background_poller(grpc_closure* closure, 193 grpc_error_handle error); 194 195 // Shut down all the closures registered in the background poller. 196 void grpc_shutdown_background_closure(); 197 198 // override to allow tests to hook poll() usage 199 typedef int (*grpc_poll_function_type)(struct pollfd*, nfds_t, int); 200 extern grpc_poll_function_type grpc_poll_function; 201 202 #endif // GRPC_POSIX_SOCKET_EV 203 204 // Return the name of the poll strategy 205 const char* grpc_get_poll_strategy_name(); 206 207 #endif // GRPC_SRC_CORE_LIB_IOMGR_EV_POSIX_H 208