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