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