src/core/lib/iomgr/ev_posix.h

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