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
48 * @brief The completion function name, for flow tracing.
54 * @brief Private state pointer for the actual implementation
56 * The implementation doing the work for the async request needs to
57 * keep around current data like for example a fd event. The user of
58 * an async request should not touch this.
63 * @brief A function to overwrite the default print function
65 * The implementation doing the work may want to implement a
66 * custom function to print the text representation of the async
69 tevent_req_print_fn private_print
;
72 * @brief A function to cancel the request
74 * The implementation might want to set a function
75 * that is called when the tevent_req_cancel() function
79 tevent_req_cancel_fn fn
;
84 * @brief A function to cleanup the request
86 * The implementation might want to set a function
87 * that is called before the tevent_req_done() and tevent_req_error()
88 * trigger the callers callback function.
91 tevent_req_cleanup_fn fn
;
93 enum tevent_req_state state
;
97 * @brief Internal state of the request
99 * Callers should only access this via functions and never directly.
103 * @brief The talloc type of the data pointer
105 * This is filled by the tevent_req_create() macro.
107 * This for debugging only.
109 const char *private_type
;
112 * @brief The location where the request was created
114 * This uses the __location__ macro via the tevent_req_create()
117 * This for debugging only.
119 const char *create_location
;
122 * @brief The location where the request was finished
124 * This uses the __location__ macro via the tevent_req_done(),
125 * tevent_req_error() or tevent_req_nomem() macro.
127 * This for debugging only.
129 const char *finish_location
;
132 * @brief The location where the request was canceled
134 * This uses the __location__ macro via the
135 * tevent_req_cancel() macro.
137 * This for debugging only.
139 const char *cancel_location
;
142 * @brief The external state - will be queried by the caller
144 * While the async request is being processed, state will remain in
145 * TEVENT_REQ_IN_PROGRESS. A request is finished if
146 * req->state>=TEVENT_REQ_DONE.
148 enum tevent_req_state state
;
151 * @brief status code when finished
153 * This status can be queried in the async completion function. It
154 * will be set to 0 when everything went fine.
159 * @brief the immediate event used by tevent_req_post
162 struct tevent_immediate
*trigger
;
165 * @brief An event context which will be used to
166 * defer the _tevent_req_notify_callback().
168 struct tevent_context
*defer_callback_ev
;
171 * @brief the timer event if tevent_req_set_endtime was used
174 struct tevent_timer
*timer
;
177 * @brief The place where profiling data is kept
179 struct tevent_req_profile
*profile
;
185 struct tevent_req_profile
{
186 struct tevent_req_profile
*prev
, *next
;
187 struct tevent_req_profile
*parent
;
188 const char *req_name
;
190 const char *start_location
;
191 struct timeval start_time
;
192 const char *stop_location
;
193 struct timeval stop_time
;
194 enum tevent_req_state state
;
196 struct tevent_req_profile
*subprofiles
;
200 struct tevent_fd
*prev
, *next
;
201 struct tevent_context
*event_ctx
;
202 struct tevent_wrapper_glue
*wrapper
;
206 uint16_t flags
; /* see TEVENT_FD_* flags */
207 tevent_fd_handler_t handler
;
208 tevent_fd_close_fn_t close_fn
;
209 /* this is private for the specific handler */
211 /* this is for debugging only! */
212 const char *handler_name
;
213 const char *location
;
214 /* this is private for the events_ops implementation */
215 uint64_t additional_flags
;
216 void *additional_data
;
217 /* custom tag that can be set by caller */
221 struct tevent_timer
{
222 struct tevent_timer
*prev
, *next
;
223 struct tevent_context
*event_ctx
;
224 struct tevent_wrapper_glue
*wrapper
;
227 struct timeval next_event
;
228 tevent_timer_handler_t handler
;
229 /* this is private for the specific handler */
231 /* this is for debugging only! */
232 const char *handler_name
;
233 const char *location
;
234 /* this is private for the events_ops implementation */
235 void *additional_data
;
236 /* custom tag that can be set by caller */
240 struct tevent_immediate
{
241 struct tevent_immediate
*prev
, *next
;
242 struct tevent_context
*event_ctx
;
243 struct tevent_wrapper_glue
*wrapper
;
246 struct tevent_context
*detach_ev_ctx
;
247 tevent_immediate_handler_t handler
;
248 /* this is private for the specific handler */
250 /* this is for debugging only! */
251 const char *handler_name
;
252 const char *create_location
;
253 const char *schedule_location
;
254 /* this is private for the events_ops implementation */
255 void (*cancel_fn
)(struct tevent_immediate
*im
);
256 void *additional_data
;
257 /* custom tag that can be set by caller */
261 struct tevent_signal
{
262 struct tevent_signal
*prev
, *next
;
263 struct tevent_context
*event_ctx
;
264 struct tevent_wrapper_glue
*wrapper
;
269 tevent_signal_handler_t handler
;
270 /* this is private for the specific handler */
272 /* this is for debugging only! */
273 const char *handler_name
;
274 const char *location
;
275 /* this is private for the events_ops implementation */
276 void *additional_data
;
277 /* custom tag that can be set by caller */
281 struct tevent_threaded_context
{
282 struct tevent_threaded_context
*next
, *prev
;
285 pthread_mutex_t event_ctx_mutex
;
287 struct tevent_context
*event_ctx
;
290 struct tevent_debug_ops
{
291 enum tevent_debug_level max_level
;
292 void (*debug
)(void *context
, enum tevent_debug_level level
,
293 const char *fmt
, va_list ap
) PRINTF_ATTRIBUTE(3,0);
297 void tevent_debug(struct tevent_context
*ev
, enum tevent_debug_level level
,
298 const char *fmt
, ...) PRINTF_ATTRIBUTE(3,4);
299 #define TEVENT_DEBUG(__ev, __level, __fmt, ...) do { \
300 if (unlikely((__ev) != NULL && \
301 (__level) <= (__ev)->debug_ops.max_level)) \
303 tevent_debug((__ev), (__level), (__fmt), __VA_ARGS__); \
307 void tevent_abort(struct tevent_context
*ev
, const char *reason
);
309 void tevent_common_check_double_free(TALLOC_CTX
*ptr
, const char *reason
);
311 struct tevent_context
{
312 /* the specific events implementation */
313 const struct tevent_ops
*ops
;
316 * The following three pointers are queried on every loop_once
317 * in the order in which they appear here. Not measured, but
318 * hopefully putting them at the top together with "ops"
319 * should make tevent a *bit* more cache-friendly than before.
322 /* list of signal events - used by common code */
323 struct tevent_signal
*signal_events
;
325 /* List of threaded job indicators */
326 struct tevent_threaded_context
*threaded_contexts
;
328 /* list of immediate events - used by common code */
329 struct tevent_immediate
*immediate_events
;
331 /* list of fd events - used by common code */
332 struct tevent_fd
*fd_events
;
334 /* list of timed events - used by common code */
335 struct tevent_timer
*timer_events
;
337 /* List of scheduled immediates */
338 pthread_mutex_t scheduled_mutex
;
339 struct tevent_immediate
*scheduled_immediates
;
341 /* this is private for the events_ops implementation */
342 void *additional_data
;
344 /* pipe hack used with signal handlers */
345 struct tevent_fd
*wakeup_fde
;
346 int wakeup_fd
; /* fd to write into */
347 #ifndef HAVE_EVENT_FD
351 /* debugging operations */
352 struct tevent_debug_ops debug_ops
;
354 /* info about the nesting status */
358 tevent_nesting_hook hook_fn
;
364 tevent_trace_callback_t callback
;
369 tevent_trace_fd_callback_t callback
;
374 tevent_trace_signal_callback_t callback
;
379 tevent_trace_timer_callback_t callback
;
384 tevent_trace_immediate_callback_t callback
;
389 tevent_trace_queue_callback_t callback
;
396 * This is used on the main event context
398 struct tevent_wrapper_glue
*list
;
401 * This is used on the wrapper event context
403 struct tevent_wrapper_glue
*glue
;
407 * an optimization pointer into timer_events
408 * used by used by common code via
409 * tevent_common_add_timer_v2()
411 struct tevent_timer
*last_zero_timer
;
414 struct tevent_context
*prev
, *next
;
418 int tevent_common_context_destructor(struct tevent_context
*ev
);
419 int tevent_common_loop_wait(struct tevent_context
*ev
,
420 const char *location
);
422 struct tevent_common_fd_buf
{
426 const char *tevent_common_fd_str(struct tevent_common_fd_buf
*buf
,
427 const char *description
,
428 const struct tevent_fd
*fde
);
430 int tevent_common_fd_destructor(struct tevent_fd
*fde
);
431 struct tevent_fd
*tevent_common_add_fd(struct tevent_context
*ev
,
435 tevent_fd_handler_t handler
,
437 const char *handler_name
,
438 const char *location
);
439 void tevent_common_fd_set_close_fn(struct tevent_fd
*fde
,
440 tevent_fd_close_fn_t close_fn
);
441 uint16_t tevent_common_fd_get_flags(struct tevent_fd
*fde
);
442 void tevent_common_fd_set_flags(struct tevent_fd
*fde
, uint16_t flags
);
443 int tevent_common_invoke_fd_handler(struct tevent_fd
*fde
, uint16_t flags
,
446 struct tevent_timer
*tevent_common_add_timer(struct tevent_context
*ev
,
448 struct timeval next_event
,
449 tevent_timer_handler_t handler
,
451 const char *handler_name
,
452 const char *location
);
453 struct tevent_timer
*tevent_common_add_timer_v2(struct tevent_context
*ev
,
455 struct timeval next_event
,
456 tevent_timer_handler_t handler
,
458 const char *handler_name
,
459 const char *location
);
460 struct timeval
tevent_common_loop_timer_delay(struct tevent_context
*);
461 int tevent_common_invoke_timer_handler(struct tevent_timer
*te
,
462 struct timeval current_time
,
465 void tevent_common_schedule_immediate(struct tevent_immediate
*im
,
466 struct tevent_context
*ev
,
467 tevent_immediate_handler_t handler
,
469 const char *handler_name
,
470 const char *location
);
471 int tevent_common_invoke_immediate_handler(struct tevent_immediate
*im
,
473 bool tevent_common_loop_immediate(struct tevent_context
*ev
);
474 void tevent_common_threaded_activate_immediate(struct tevent_context
*ev
);
476 bool tevent_common_have_events(struct tevent_context
*ev
);
477 int tevent_common_wakeup_init(struct tevent_context
*ev
);
478 int tevent_common_wakeup_fd(int fd
);
479 int tevent_common_wakeup(struct tevent_context
*ev
);
481 struct tevent_signal
*tevent_common_add_signal(struct tevent_context
*ev
,
485 tevent_signal_handler_t handler
,
487 const char *handler_name
,
488 const char *location
);
489 int tevent_common_check_signal(struct tevent_context
*ev
);
490 void tevent_cleanup_pending_signal_handlers(struct tevent_signal
*se
);
491 int tevent_common_invoke_signal_handler(struct tevent_signal
*se
,
492 int signum
, int count
, void *siginfo
,
495 struct tevent_context
*tevent_wrapper_main_ev(struct tevent_context
*ev
);
497 struct tevent_wrapper_ops
;
499 struct tevent_wrapper_glue
{
500 struct tevent_wrapper_glue
*prev
, *next
;
501 struct tevent_context
*wrap_ev
;
502 struct tevent_context
*main_ev
;
505 const struct tevent_wrapper_ops
*ops
;
509 void tevent_wrapper_push_use_internal(struct tevent_context
*ev
,
510 struct tevent_wrapper_glue
*wrapper
);
511 void tevent_wrapper_pop_use_internal(const struct tevent_context
*__ev_ptr
,
512 struct tevent_wrapper_glue
*wrapper
);
514 bool tevent_standard_init(void);
515 bool tevent_poll_init(void);
516 bool tevent_poll_event_add_fd_internal(struct tevent_context
*ev
,
517 struct tevent_fd
*fde
);
518 bool tevent_poll_mt_init(void);
520 bool tevent_epoll_init(void);
521 void tevent_epoll_set_panic_fallback(struct tevent_context
*ev
,
522 bool (*panic_fallback
)(struct tevent_context
*ev
,
526 static inline void tevent_thread_call_depth_notify(
527 enum tevent_thread_call_depth_cmd cmd
,
528 struct tevent_req
*req
,
532 if (tevent_thread_call_depth_state_g
.cb
!= NULL
) {
533 tevent_thread_call_depth_state_g
.cb(
534 tevent_thread_call_depth_state_g
.cb_private
,
542 void tevent_trace_point_callback(struct tevent_context
*ev
,
543 enum tevent_trace_point
);
545 void tevent_trace_fd_callback(struct tevent_context
*ev
,
546 struct tevent_fd
*fde
,
547 enum tevent_event_trace_point
);
549 void tevent_trace_signal_callback(struct tevent_context
*ev
,
550 struct tevent_signal
*se
,
551 enum tevent_event_trace_point
);
553 void tevent_trace_timer_callback(struct tevent_context
*ev
,
554 struct tevent_timer
*te
,
555 enum tevent_event_trace_point
);
557 void tevent_trace_immediate_callback(struct tevent_context
*ev
,
558 struct tevent_immediate
*im
,
559 enum tevent_event_trace_point
);
561 void tevent_trace_queue_callback(struct tevent_context
*ev
,
562 struct tevent_queue_entry
*qe
,
563 enum tevent_event_trace_point
);