2 Unix SMB/CIFS implementation.
4 generalised event loop handling
6 INTERNAL STRUCTS. THERE ARE NO API GUARANTEES.
7 External users should only ever have to include this header when
8 implementing new tevent backends.
10 Copyright (C) Stefan Metzmacher 2005-2009
12 ** NOTE! The following LGPL license applies to the tevent
13 ** library. This does NOT imply that all of Samba is released
16 This library is free software; you can redistribute it and/or
17 modify it under the terms of the GNU Lesser General Public
18 License as published by the Free Software Foundation; either
19 version 3 of the License, or (at your option) any later version.
21 This library is distributed in the hope that it will be useful,
22 but WITHOUT ANY WARRANTY; without even the implied warranty of
23 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
24 Lesser General Public License for more details.
26 You should have received a copy of the GNU Lesser General Public
27 License along with this library; if not, see <http://www.gnu.org/licenses/>.
32 * @brief What to do on completion
34 * This is used for the user of an async request, fn is called when
35 * the request completes, either successfully or with an error.
39 * @brief Completion function
40 * Completion function, to be filled by the API user
44 * @brief Private data for the completion function
50 * @brief Private state pointer for the actual implementation
52 * The implementation doing the work for the async request needs to
53 * keep around current data like for example a fd event. The user of
54 * an async request should not touch this.
59 * @brief A function to overwrite the default print function
61 * The implementation doing the work may want to implement a
62 * custom function to print the text representation of the async
65 tevent_req_print_fn private_print;
68 * @brief A function to cancel the request
70 * The implementation might want to set a function
71 * that is called when the tevent_req_cancel() function
74 tevent_req_cancel_fn private_cancel;
77 * @brief A function to cleanup the request
79 * The implementation might want to set a function
80 * that is called before the tevent_req_done() and tevent_req_error()
81 * trigger the callers callback function.
84 tevent_req_cleanup_fn fn;
85 enum tevent_req_state state;
89 * @brief Internal state of the request
91 * Callers should only access this via functions and never directly.
95 * @brief The talloc type of the data pointer
97 * This is filled by the tevent_req_create() macro.
99 * This for debugging only.
101 const char *private_type;
104 * @brief The location where the request was created
106 * This uses the __location__ macro via the tevent_req_create()
109 * This for debugging only.
111 const char *create_location;
114 * @brief The location where the request was finished
116 * This uses the __location__ macro via the tevent_req_done(),
117 * tevent_req_error() or tevent_req_nomem() macro.
119 * This for debugging only.
121 const char *finish_location;
124 * @brief The location where the request was canceled
126 * This uses the __location__ macro via the
127 * tevent_req_cancel() macro.
129 * This for debugging only.
131 const char *cancel_location;
134 * @brief The external state - will be queried by the caller
136 * While the async request is being processed, state will remain in
137 * TEVENT_REQ_IN_PROGRESS. A request is finished if
138 * req->state>=TEVENT_REQ_DONE.
140 enum tevent_req_state state;
143 * @brief status code when finished
145 * This status can be queried in the async completion function. It
146 * will be set to 0 when everything went fine.
151 * @brief the immediate event used by tevent_req_post
154 struct tevent_immediate *trigger;
157 * @brief An event context which will be used to
158 * defer the _tevent_req_notify_callback().
160 struct tevent_context *defer_callback_ev;
163 * @brief the timer event if tevent_req_set_endtime was used
166 struct tevent_timer *timer;
171 struct tevent_fd *prev, *next;
172 struct tevent_context *event_ctx;
173 struct tevent_wrapper_glue *wrapper;
177 uint16_t flags; /* see TEVENT_FD_* flags */
178 tevent_fd_handler_t handler;
179 tevent_fd_close_fn_t close_fn;
180 /* this is private for the specific handler */
182 /* this is for debugging only! */
183 const char *handler_name;
184 const char *location;
185 /* this is private for the events_ops implementation */
186 uint64_t additional_flags;
187 void *additional_data;
190 struct tevent_timer {
191 struct tevent_timer *prev, *next;
192 struct tevent_context *event_ctx;
193 struct tevent_wrapper_glue *wrapper;
196 struct timeval next_event;
197 tevent_timer_handler_t handler;
198 /* this is private for the specific handler */
200 /* this is for debugging only! */
201 const char *handler_name;
202 const char *location;
203 /* this is private for the events_ops implementation */
204 void *additional_data;
207 struct tevent_immediate {
208 struct tevent_immediate *prev, *next;
209 struct tevent_context *event_ctx;
210 struct tevent_wrapper_glue *wrapper;
213 tevent_immediate_handler_t handler;
214 /* this is private for the specific handler */
216 /* this is for debugging only! */
217 const char *handler_name;
218 const char *create_location;
219 const char *schedule_location;
220 /* this is private for the events_ops implementation */
221 void (*cancel_fn)(struct tevent_immediate *im);
222 void *additional_data;
225 struct tevent_signal {
226 struct tevent_signal *prev, *next;
227 struct tevent_context *event_ctx;
228 struct tevent_wrapper_glue *wrapper;
233 tevent_signal_handler_t handler;
234 /* this is private for the specific handler */
236 /* this is for debugging only! */
237 const char *handler_name;
238 const char *location;
239 /* this is private for the events_ops implementation */
240 void *additional_data;
243 struct tevent_threaded_context {
244 struct tevent_threaded_context *next, *prev;
247 pthread_mutex_t event_ctx_mutex;
249 struct tevent_context *event_ctx;
252 struct tevent_debug_ops {
253 void (*debug)(void *context, enum tevent_debug_level level,
254 const char *fmt, va_list ap) PRINTF_ATTRIBUTE(3,0);
258 void tevent_debug(struct tevent_context *ev, enum tevent_debug_level level,
259 const char *fmt, ...) PRINTF_ATTRIBUTE(3,4);
261 void tevent_abort(struct tevent_context *ev, const char *reason);
263 void tevent_common_check_double_free(TALLOC_CTX *ptr, const char *reason);
265 struct tevent_context {
266 /* the specific events implementation */
267 const struct tevent_ops *ops;
270 * The following three pointers are queried on every loop_once
271 * in the order in which they appear here. Not measured, but
272 * hopefully putting them at the top together with "ops"
273 * should make tevent a *bit* more cache-friendly than before.
276 /* list of signal events - used by common code */
277 struct tevent_signal *signal_events;
279 /* List of threaded job indicators */
280 struct tevent_threaded_context *threaded_contexts;
282 /* list of immediate events - used by common code */
283 struct tevent_immediate *immediate_events;
285 /* list of fd events - used by common code */
286 struct tevent_fd *fd_events;
288 /* list of timed events - used by common code */
289 struct tevent_timer *timer_events;
291 /* List of scheduled immediates */
292 pthread_mutex_t scheduled_mutex;
293 struct tevent_immediate *scheduled_immediates;
295 /* this is private for the events_ops implementation */
296 void *additional_data;
298 /* pipe hack used with signal handlers */
299 struct tevent_fd *wakeup_fde;
300 int wakeup_fd; /* fd to write into */
301 #ifndef HAVE_EVENT_FD
305 /* debugging operations */
306 struct tevent_debug_ops debug_ops;
308 /* info about the nesting status */
312 tevent_nesting_hook hook_fn;
317 tevent_trace_callback_t callback;
323 * This is used on the main event context
325 struct tevent_wrapper_glue *list;
328 * This is used on the wrapper event context
330 struct tevent_wrapper_glue *glue;
334 * an optimization pointer into timer_events
335 * used by used by common code via
336 * tevent_common_add_timer_v2()
338 struct tevent_timer *last_zero_timer;
341 struct tevent_context *prev, *next;
345 const struct tevent_ops *tevent_find_ops_byname(const char *name);
347 int tevent_common_context_destructor(struct tevent_context *ev);
348 int tevent_common_loop_wait(struct tevent_context *ev,
349 const char *location);
351 int tevent_common_fd_destructor(struct tevent_fd *fde);
352 struct tevent_fd *tevent_common_add_fd(struct tevent_context *ev,
356 tevent_fd_handler_t handler,
358 const char *handler_name,
359 const char *location);
360 void tevent_common_fd_set_close_fn(struct tevent_fd *fde,
361 tevent_fd_close_fn_t close_fn);
362 uint16_t tevent_common_fd_get_flags(struct tevent_fd *fde);
363 void tevent_common_fd_set_flags(struct tevent_fd *fde, uint16_t flags);
364 int tevent_common_invoke_fd_handler(struct tevent_fd *fde, uint16_t flags,
367 struct tevent_timer *tevent_common_add_timer(struct tevent_context *ev,
369 struct timeval next_event,
370 tevent_timer_handler_t handler,
372 const char *handler_name,
373 const char *location);
374 struct tevent_timer *tevent_common_add_timer_v2(struct tevent_context *ev,
376 struct timeval next_event,
377 tevent_timer_handler_t handler,
379 const char *handler_name,
380 const char *location);
381 struct timeval tevent_common_loop_timer_delay(struct tevent_context *);
382 int tevent_common_invoke_timer_handler(struct tevent_timer *te,
383 struct timeval current_time,
386 void tevent_common_schedule_immediate(struct tevent_immediate *im,
387 struct tevent_context *ev,
388 tevent_immediate_handler_t handler,
390 const char *handler_name,
391 const char *location);
392 int tevent_common_invoke_immediate_handler(struct tevent_immediate *im,
394 bool tevent_common_loop_immediate(struct tevent_context *ev);
395 void tevent_common_threaded_activate_immediate(struct tevent_context *ev);
397 bool tevent_common_have_events(struct tevent_context *ev);
398 int tevent_common_wakeup_init(struct tevent_context *ev);
399 int tevent_common_wakeup_fd(int fd);
400 int tevent_common_wakeup(struct tevent_context *ev);
402 struct tevent_signal *tevent_common_add_signal(struct tevent_context *ev,
406 tevent_signal_handler_t handler,
408 const char *handler_name,
409 const char *location);
410 int tevent_common_check_signal(struct tevent_context *ev);
411 void tevent_cleanup_pending_signal_handlers(struct tevent_signal *se);
412 int tevent_common_invoke_signal_handler(struct tevent_signal *se,
413 int signum, int count, void *siginfo,
416 struct tevent_context *tevent_wrapper_main_ev(struct tevent_context *ev);
418 struct tevent_wrapper_ops;
420 struct tevent_wrapper_glue {
421 struct tevent_wrapper_glue *prev, *next;
422 struct tevent_context *wrap_ev;
423 struct tevent_context *main_ev;
426 const struct tevent_wrapper_ops *ops;
430 void tevent_wrapper_push_use_internal(struct tevent_context *ev,
431 struct tevent_wrapper_glue *wrapper);
432 void tevent_wrapper_pop_use_internal(const struct tevent_context *__ev_ptr,
433 struct tevent_wrapper_glue *wrapper);
435 bool tevent_standard_init(void);
436 bool tevent_poll_init(void);
437 bool tevent_poll_event_add_fd_internal(struct tevent_context *ev,
438 struct tevent_fd *fde);
439 bool tevent_poll_mt_init(void);
441 bool tevent_epoll_init(void);
442 void tevent_epoll_set_panic_fallback(struct tevent_context *ev,
443 bool (*panic_fallback)(struct tevent_context *ev,
446 #ifdef HAVE_SOLARIS_PORTS
447 bool tevent_port_init(void);
451 void tevent_trace_point_callback(struct tevent_context *ev,
452 enum tevent_trace_point);