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