2 Unix SMB/CIFS implementation.
4 generalised event loop handling
6 Copyright (C) Andrew Tridgell 2005
7 Copyright (C) Stefan Metzmacher 2005-2009
8 Copyright (C) Volker Lendecke 2008
10 ** NOTE! The following LGPL license applies to the tevent
11 ** library. This does NOT imply that all of Samba is released
14 This library is free software; you can redistribute it and/or
15 modify it under the terms of the GNU Lesser General Public
16 License as published by the Free Software Foundation; either
17 version 3 of the License, or (at your option) any later version.
19 This library is distributed in the hope that it will be useful,
20 but WITHOUT ANY WARRANTY; without even the implied warranty of
21 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
22 Lesser General Public License for more details.
24 You should have received a copy of the GNU Lesser General Public
25 License along with this library; if not, see <http://www.gnu.org/licenses/>.
36 struct tevent_context
;
40 struct tevent_immediate
;
42 struct tevent_thread_proxy
;
43 struct tevent_threaded_context
;
46 * @defgroup tevent The tevent API
48 * The tevent low-level API
50 * This API provides the public interface to manage events in the tevent
51 * mainloop. Functions are provided for managing low-level events such
52 * as timer events, fd events and signal handling.
57 /* event handler types */
59 * Called when a file descriptor monitored by tevent has
60 * data to be read or written on it.
62 typedef void (*tevent_fd_handler_t
)(struct tevent_context
*ev
,
63 struct tevent_fd
*fde
,
68 * Called when tevent is ceasing the monitoring of a file descriptor.
70 typedef void (*tevent_fd_close_fn_t
)(struct tevent_context
*ev
,
71 struct tevent_fd
*fde
,
76 * Called when a tevent timer has fired.
78 typedef void (*tevent_timer_handler_t
)(struct tevent_context
*ev
,
79 struct tevent_timer
*te
,
80 struct timeval current_time
,
84 * Called when a tevent immediate event is invoked.
86 typedef void (*tevent_immediate_handler_t
)(struct tevent_context
*ctx
,
87 struct tevent_immediate
*im
,
91 * Called after tevent detects the specified signal.
93 typedef void (*tevent_signal_handler_t
)(struct tevent_context
*ev
,
94 struct tevent_signal
*se
,
101 * @brief Create a event_context structure.
103 * This must be the first events call, and all subsequent calls pass this
104 * event_context as the first element. Event handlers also receive this as
105 * their first argument.
107 * @param[in] mem_ctx The memory context to use.
109 * @return An allocated tevent context, NULL on error.
111 * @see tevent_context_init()
113 struct tevent_context
*tevent_context_init(TALLOC_CTX
*mem_ctx
);
116 * @brief Create a event_context structure and select a specific backend.
118 * This must be the first events call, and all subsequent calls pass this
119 * event_context as the first element. Event handlers also receive this as
120 * their first argument.
122 * @param[in] mem_ctx The memory context to use.
124 * @param[in] name The name of the backend to use.
126 * @return An allocated tevent context, NULL on error.
128 struct tevent_context
*tevent_context_init_byname(TALLOC_CTX
*mem_ctx
, const char *name
);
131 * @brief Create a custom event context
133 * @param[in] mem_ctx The memory context to use.
134 * @param[in] ops The function pointer table of the backend.
135 * @param[in] additional_data The additional/private data to this instance
137 * @return An allocated tevent context, NULL on error.
140 struct tevent_context
*tevent_context_init_ops(TALLOC_CTX
*mem_ctx
,
141 const struct tevent_ops
*ops
,
142 void *additional_data
);
145 * @brief List available backends.
147 * @param[in] mem_ctx The memory context to use.
149 * @return A string vector with a terminating NULL element, NULL
152 const char **tevent_backend_list(TALLOC_CTX
*mem_ctx
);
155 * @brief Set the default tevent backend.
157 * @param[in] backend The name of the backend to set.
159 void tevent_set_default_backend(const char *backend
);
163 * @brief Add a file descriptor based event.
165 * @param[in] ev The event context to work on.
167 * @param[in] mem_ctx The talloc memory context to use.
169 * @param[in] fd The file descriptor to base the event on.
171 * @param[in] flags #TEVENT_FD_READ or #TEVENT_FD_WRITE
173 * @param[in] handler The callback handler for the event.
175 * @param[in] private_data The private data passed to the callback handler.
177 * @return The file descriptor based event, NULL on error.
179 * @note To cancel the monitoring of a file descriptor, call talloc_free()
180 * on the object returned by this function.
182 * @note The caller should avoid closing the file descriptor before
183 * calling talloc_free()! Otherwise the behaviour is undefined which
184 * might result in crashes. See https://bugzilla.samba.org/show_bug.cgi?id=11141
187 struct tevent_fd
*tevent_add_fd(struct tevent_context
*ev
,
191 tevent_fd_handler_t handler
,
194 struct tevent_fd
*_tevent_add_fd(struct tevent_context
*ev
,
198 tevent_fd_handler_t handler
,
200 const char *handler_name
,
201 const char *location
);
202 #define tevent_add_fd(ev, mem_ctx, fd, flags, handler, private_data) \
203 _tevent_add_fd(ev, mem_ctx, fd, flags, handler, private_data, \
204 #handler, __location__)
209 * @brief Add a timed event
211 * @param[in] ev The event context to work on.
213 * @param[in] mem_ctx The talloc memory context to use.
215 * @param[in] next_event Timeval specifying the absolute time to fire this
216 * event. This is not an offset.
218 * @param[in] handler The callback handler for the event.
220 * @param[in] private_data The private data passed to the callback handler.
222 * @return The newly-created timer event, or NULL on error.
224 * @note To cancel a timer event before it fires, call talloc_free() on the
225 * event returned from this function. This event is automatically
226 * talloc_free()-ed after its event handler files, if it hasn't been freed yet.
228 * @note Unlike some mainloops, tevent timers are one-time events. To set up
229 * a recurring event, it is necessary to call tevent_add_timer() again during
230 * the handler processing.
232 * @note Due to the internal mainloop processing, a timer set to run
233 * immediately will do so after any other pending timers fire, but before
234 * any further file descriptor or signal handling events fire. Callers should
235 * not rely on this behavior!
237 struct tevent_timer
*tevent_add_timer(struct tevent_context
*ev
,
239 struct timeval next_event
,
240 tevent_timer_handler_t handler
,
243 struct tevent_timer
*_tevent_add_timer(struct tevent_context
*ev
,
245 struct timeval next_event
,
246 tevent_timer_handler_t handler
,
248 const char *handler_name
,
249 const char *location
);
250 #define tevent_add_timer(ev, mem_ctx, next_event, handler, private_data) \
251 _tevent_add_timer(ev, mem_ctx, next_event, handler, private_data, \
252 #handler, __location__)
256 * @brief Set the time a tevent_timer fires
258 * @param[in] te The timer event to reset
260 * @param[in] next_event Timeval specifying the absolute time to fire this
261 * event. This is not an offset.
263 void tevent_update_timer(struct tevent_timer
*te
, struct timeval next_event
);
267 * Initialize an immediate event object
269 * This object can be used to trigger an event to occur immediately after
270 * returning from the current event (before any other event occurs)
272 * @param[in] mem_ctx The talloc memory context to use as the parent
274 * @return An empty tevent_immediate object. Use tevent_schedule_immediate
275 * to populate and use it.
277 * @note Available as of tevent 0.9.8
279 struct tevent_immediate
*tevent_create_immediate(TALLOC_CTX
*mem_ctx
);
281 struct tevent_immediate
*_tevent_create_immediate(TALLOC_CTX
*mem_ctx
,
282 const char *location
);
283 #define tevent_create_immediate(mem_ctx) \
284 _tevent_create_immediate(mem_ctx, __location__)
290 * Schedule an event for immediate execution. This event will occur
291 * immediately after returning from the current event (before any other
294 * @param[in] im The tevent_immediate object to populate and use
295 * @param[in] ctx The tevent_context to run this event
296 * @param[in] handler The event handler to run when this event fires
297 * @param[in] private_data Data to pass to the event handler
299 void tevent_schedule_immediate(struct tevent_immediate
*im
,
300 struct tevent_context
*ctx
,
301 tevent_immediate_handler_t handler
,
304 void _tevent_schedule_immediate(struct tevent_immediate
*im
,
305 struct tevent_context
*ctx
,
306 tevent_immediate_handler_t handler
,
308 const char *handler_name
,
309 const char *location
);
310 #define tevent_schedule_immediate(im, ctx, handler, private_data) \
311 _tevent_schedule_immediate(im, ctx, handler, private_data, \
312 #handler, __location__);
317 * @brief Add a tevent signal handler
319 * tevent_add_signal() creates a new event for handling a signal the next
320 * time through the mainloop. It implements a very simple traditional signal
321 * handler whose only purpose is to add the handler event into the mainloop.
323 * @param[in] ev The event context to work on.
325 * @param[in] mem_ctx The talloc memory context to use.
327 * @param[in] signum The signal to trap
329 * @param[in] handler The callback handler for the signal.
331 * @param[in] sa_flags sigaction flags for this signal handler.
333 * @param[in] private_data The private data passed to the callback handler.
335 * @return The newly-created signal handler event, or NULL on error.
337 * @note To cancel a signal handler, call talloc_free() on the event returned
338 * from this function.
340 * @see tevent_num_signals, tevent_sa_info_queue_count
342 struct tevent_signal
*tevent_add_signal(struct tevent_context
*ev
,
346 tevent_signal_handler_t handler
,
349 struct tevent_signal
*_tevent_add_signal(struct tevent_context
*ev
,
353 tevent_signal_handler_t handler
,
355 const char *handler_name
,
356 const char *location
);
357 #define tevent_add_signal(ev, mem_ctx, signum, sa_flags, handler, private_data) \
358 _tevent_add_signal(ev, mem_ctx, signum, sa_flags, handler, private_data, \
359 #handler, __location__)
363 * @brief the number of supported signals
365 * This returns value of the configure time TEVENT_NUM_SIGNALS constant.
367 * The 'signum' argument of tevent_add_signal() must be less than
368 * TEVENT_NUM_SIGNALS.
370 * @see tevent_add_signal
372 size_t tevent_num_signals(void);
375 * @brief the number of pending realtime signals
377 * This returns value of TEVENT_SA_INFO_QUEUE_COUNT.
379 * The tevent internals remember the last TEVENT_SA_INFO_QUEUE_COUNT
380 * siginfo_t structures for SA_SIGINFO signals. If the system generates
381 * more some signals get lost.
383 * @see tevent_add_signal
385 size_t tevent_sa_info_queue_count(void);
389 * @brief Pass a single time through the mainloop
391 * This will process any appropriate signal, immediate, fd and timer events
393 * @param[in] ev The event context to process
395 * @return Zero on success, nonzero if an internal error occurred
397 int tevent_loop_once(struct tevent_context
*ev
);
399 int _tevent_loop_once(struct tevent_context
*ev
, const char *location
);
400 #define tevent_loop_once(ev) \
401 _tevent_loop_once(ev, __location__)
406 * @brief Run the mainloop
408 * The mainloop will run until there are no events remaining to be processed
410 * @param[in] ev The event context to process
412 * @return Zero if all events have been processed. Nonzero if an internal
415 int tevent_loop_wait(struct tevent_context
*ev
);
417 int _tevent_loop_wait(struct tevent_context
*ev
, const char *location
);
418 #define tevent_loop_wait(ev) \
419 _tevent_loop_wait(ev, __location__)
424 * Assign a function to run when a tevent_fd is freed
426 * This function is a destructor for the tevent_fd. It does not automatically
427 * close the file descriptor. If this is the desired behavior, then it must be
428 * performed by the close_fn.
430 * @param[in] fde File descriptor event on which to set the destructor
431 * @param[in] close_fn Destructor to execute when fde is freed
433 void tevent_fd_set_close_fn(struct tevent_fd
*fde
,
434 tevent_fd_close_fn_t close_fn
);
437 * Automatically close the file descriptor when the tevent_fd is freed
439 * This function calls close(fd) internally.
441 * @param[in] fde File descriptor event to auto-close
443 void tevent_fd_set_auto_close(struct tevent_fd
*fde
);
446 * Return the flags set on this file descriptor event
448 * @param[in] fde File descriptor event to query
450 * @return The flags set on the event. See #TEVENT_FD_READ and
453 uint16_t tevent_fd_get_flags(struct tevent_fd
*fde
);
456 * Set flags on a file descriptor event
458 * @param[in] fde File descriptor event to set
459 * @param[in] flags Flags to set on the event. See #TEVENT_FD_READ and
462 void tevent_fd_set_flags(struct tevent_fd
*fde
, uint16_t flags
);
465 * Query whether tevent supports signal handling
467 * @param[in] ev An initialized tevent context
469 * @return True if this platform and tevent context support signal handling
471 bool tevent_signal_support(struct tevent_context
*ev
);
473 void tevent_set_abort_fn(void (*abort_fn
)(const char *reason
));
475 /* bits for file descriptor event flags */
478 * Monitor a file descriptor for data to be read
480 #define TEVENT_FD_READ 1
482 * Monitor a file descriptor for writeability
484 #define TEVENT_FD_WRITE 2
487 * Convenience function for declaring a tevent_fd writable
489 #define TEVENT_FD_WRITEABLE(fde) \
490 tevent_fd_set_flags(fde, tevent_fd_get_flags(fde) | TEVENT_FD_WRITE)
493 * Convenience function for declaring a tevent_fd readable
495 #define TEVENT_FD_READABLE(fde) \
496 tevent_fd_set_flags(fde, tevent_fd_get_flags(fde) | TEVENT_FD_READ)
499 * Convenience function for declaring a tevent_fd non-writable
501 #define TEVENT_FD_NOT_WRITEABLE(fde) \
502 tevent_fd_set_flags(fde, tevent_fd_get_flags(fde) & ~TEVENT_FD_WRITE)
505 * Convenience function for declaring a tevent_fd non-readable
507 #define TEVENT_FD_NOT_READABLE(fde) \
508 tevent_fd_set_flags(fde, tevent_fd_get_flags(fde) & ~TEVENT_FD_READ)
511 * Debug level of tevent
513 enum tevent_debug_level
{
516 TEVENT_DEBUG_WARNING
,
521 * @brief The tevent debug callbac.
523 * @param[in] context The memory context to use.
525 * @param[in] level The debug level.
527 * @param[in] fmt The format string.
529 * @param[in] ap The arguments for the format string.
531 typedef void (*tevent_debug_fn
)(void *context
,
532 enum tevent_debug_level level
,
534 va_list ap
) PRINTF_ATTRIBUTE(3,0);
537 * Set destination for tevent debug messages
539 * @param[in] ev Event context to debug
540 * @param[in] debug Function to handle output printing
541 * @param[in] context The context to pass to the debug function.
543 * @return Always returns 0 as of version 0.9.8
545 * @note Default is to emit no debug messages
547 int tevent_set_debug(struct tevent_context
*ev
,
548 tevent_debug_fn debug
,
552 * Designate stderr for debug message output
554 * @param[in] ev Event context to debug
556 * @note This function will only output TEVENT_DEBUG_FATAL, TEVENT_DEBUG_ERROR
557 * and TEVENT_DEBUG_WARNING messages. For TEVENT_DEBUG_TRACE, please define a
558 * function for tevent_set_debug()
560 int tevent_set_debug_stderr(struct tevent_context
*ev
);
562 enum tevent_trace_point
{
564 * Corresponds to a trace point just before waiting
566 TEVENT_TRACE_BEFORE_WAIT
,
568 * Corresponds to a trace point just after waiting
570 TEVENT_TRACE_AFTER_WAIT
,
571 #define TEVENT_HAS_LOOP_ONCE_TRACE_POINTS 1
573 * Corresponds to a trace point just before calling
574 * the loop_once() backend function.
576 TEVENT_TRACE_BEFORE_LOOP_ONCE
,
578 * Corresponds to a trace point right after the
579 * loop_once() backend function has returned.
581 TEVENT_TRACE_AFTER_LOOP_ONCE
,
584 typedef void (*tevent_trace_callback_t
)(enum tevent_trace_point
,
588 * Register a callback to be called at certain trace points
590 * @param[in] ev Event context
591 * @param[in] cb Trace callback
592 * @param[in] private_data Data to be passed to callback
594 * @note The callback will be called at trace points defined by
595 * tevent_trace_point. Call with NULL to reset.
597 void tevent_set_trace_callback(struct tevent_context
*ev
,
598 tevent_trace_callback_t cb
,
602 * Retrieve the current trace callback
604 * @param[in] ev Event context
605 * @param[out] cb Registered trace callback
606 * @param[out] private_data Registered data to be passed to callback
608 * @note This can be used to allow one component that wants to
609 * register a callback to respect the callback that another component
610 * has already registered.
612 void tevent_get_trace_callback(struct tevent_context
*ev
,
613 tevent_trace_callback_t
*cb
,
621 * @defgroup tevent_request The tevent request functions.
624 * A tevent_req represents an asynchronous computation.
626 * The tevent_req group of API calls is the recommended way of
627 * programming async computations within tevent. In particular the
628 * file descriptor (tevent_add_fd) and timer (tevent_add_timed) events
629 * are considered too low-level to be used in larger computations. To
630 * read and write from and to sockets, Samba provides two calls on top
631 * of tevent_add_fd: tstream_read_packet_send/recv and tstream_writev_send/recv.
632 * These requests are much easier to compose than the low-level event
633 * handlers called from tevent_add_fd.
635 * A lot of the simplicity tevent_req has brought to the notoriously
636 * hairy async programming came via a set of conventions that every
637 * async computation programmed should follow. One central piece of
638 * these conventions is the naming of routines and variables.
640 * Every async computation needs a name (sensibly called "computation"
641 * down from here). From this name quite a few naming conventions are
644 * Every computation that requires local state needs a
646 * struct computation_state {
650 * Even if no local variables are required, such a state struct should
651 * be created containing a dummy variable. Quite a few helper
652 * functions and macros (for example tevent_req_create()) assume such
655 * An async computation is started by a computation_send
656 * function. When it is finished, its result can be received by a
657 * computation_recv function. For an example how to set up an async
658 * computation, see the code example in the documentation for
659 * tevent_req_create() and tevent_req_post(). The prototypes for _send
660 * and _recv functions should follow some conventions:
663 * struct tevent_req *computation_send(TALLOC_CTX *mem_ctx,
664 * struct tevent_req *ev,
666 * int computation_recv(struct tevent_req *req, ... further output args);
669 * The "int" result of computation_recv() depends on the result the
670 * sync version of the function would have, "int" is just an example
673 * Another important piece of the conventions is that the program flow
674 * is interrupted as little as possible. Because a blocking
675 * sub-computation requires that the flow needs to continue in a
676 * separate function that is the logical sequel of some computation,
677 * it should lexically follow sending off the blocking
678 * sub-computation. Setting the callback function via
679 * tevent_req_set_callback() requires referencing a function lexically
680 * below the call to tevent_req_set_callback(), forward declarations
681 * are required. A lot of the async computations thus begin with a
682 * sequence of declarations such as
685 * static void computation_step1_done(struct tevent_req *subreq);
686 * static void computation_step2_done(struct tevent_req *subreq);
687 * static void computation_step3_done(struct tevent_req *subreq);
690 * It really helps readability a lot to do these forward declarations,
691 * because the lexically sequential program flow makes the async
692 * computations almost as clear to read as a normal, sync program
695 * It is up to the user of the async computation to talloc_free it
696 * after it has finished. If an async computation should be aborted,
697 * the tevent_req structure can be talloc_free'ed. After it has
698 * finished, it should talloc_free'ed by the API user.
704 * An async request moves from TEVENT_REQ_INIT to
705 * TEVENT_REQ_IN_PROGRESS. All other states are valid after a request
708 enum tevent_req_state
{
710 * We are creating the request
714 * We are waiting the request to complete
716 TEVENT_REQ_IN_PROGRESS
,
718 * The request is finished successfully
722 * A user error has occurred. The user error has been
723 * indicated by tevent_req_error(), it can be retrieved via
724 * tevent_req_is_error().
726 TEVENT_REQ_USER_ERROR
,
728 * Request timed out after the timeout set by tevent_req_set_endtime.
730 TEVENT_REQ_TIMED_OUT
,
732 * An internal allocation has failed, or tevent_req_nomem has
733 * been given a NULL pointer as the first argument.
735 TEVENT_REQ_NO_MEMORY
,
737 * The request has been received by the caller. No further
744 * @brief An async request
749 * @brief A tevent request callback function.
751 * @param[in] req The tevent async request which executed this callback.
753 typedef void (*tevent_req_fn
)(struct tevent_req
*req
);
756 * @brief Set an async request callback.
758 * See the documentation of tevent_req_post() for an example how this
759 * is supposed to be used.
761 * @param[in] req The async request to set the callback.
763 * @param[in] fn The callback function to set.
765 * @param[in] pvt A pointer to private data to pass to the async request
768 void tevent_req_set_callback(struct tevent_req
*req
, tevent_req_fn fn
, void *pvt
);
772 * @brief Get the private data cast to the given type for a callback from
773 * a tevent request structure.
776 * static void computation_done(struct tevent_req *subreq) {
777 * struct tevent_req *req = tevent_req_callback_data(subreq, struct tevent_req);
778 * struct computation_state *state = tevent_req_data(req, struct computation_state);
779 * .... more things, eventually maybe call tevent_req_done(req);
783 * @param[in] req The structure to get the callback data from.
785 * @param[in] type The type of the private callback data to get.
787 * @return The type casted private data set NULL if not set.
789 void *tevent_req_callback_data(struct tevent_req
*req
, #type);
791 void *_tevent_req_callback_data(struct tevent_req
*req
);
792 #define tevent_req_callback_data(_req, _type) \
793 talloc_get_type_abort(_tevent_req_callback_data(_req), _type)
798 * @brief Get the private data for a callback from a tevent request structure.
800 * @param[in] req The structure to get the callback data from.
802 * @param[in] req The structure to get the data from.
804 * @return The private data or NULL if not set.
806 void *tevent_req_callback_data_void(struct tevent_req
*req
);
808 #define tevent_req_callback_data_void(_req) \
809 _tevent_req_callback_data(_req)
814 * @brief Get the private data from a tevent request structure.
816 * When the tevent_req has been created by tevent_req_create, the
817 * result of tevent_req_data() is the state variable created by
818 * tevent_req_create() as a child of the req.
820 * @param[in] req The structure to get the private data from.
822 * @param[in] type The type of the private data
824 * @return The private data or NULL if not set.
826 void *tevent_req_data(struct tevent_req
*req
, #type);
828 void *_tevent_req_data(struct tevent_req
*req
);
829 #define tevent_req_data(_req, _type) \
830 talloc_get_type_abort(_tevent_req_data(_req), _type)
834 * @brief The print function which can be set for a tevent async request.
836 * @param[in] req The tevent async request.
838 * @param[in] ctx A talloc memory context which can be uses to allocate
841 * @return An allocated string buffer to print.
845 * static char *my_print(struct tevent_req *req, TALLOC_CTX *mem_ctx)
847 * struct my_data *data = tevent_req_data(req, struct my_data);
850 * result = tevent_req_default_print(mem_ctx, req);
851 * if (result == NULL) {
855 * return talloc_asprintf_append_buffer(result, "foo=%d, bar=%d",
856 * data->foo, data->bar);
860 typedef char *(*tevent_req_print_fn
)(struct tevent_req
*req
, TALLOC_CTX
*ctx
);
863 * @brief This function sets a print function for the given request.
865 * This function can be used to setup a print function for the given request.
866 * This will be triggered if the tevent_req_print() function was
867 * called on the given request.
869 * @param[in] req The request to use.
871 * @param[in] fn A pointer to the print function
873 * @note This function should only be used for debugging.
875 void tevent_req_set_print_fn(struct tevent_req
*req
, tevent_req_print_fn fn
);
878 * @brief The default print function for creating debug messages.
880 * The function should not be used by users of the async API,
881 * but custom print function can use it and append custom text
884 * @param[in] req The request to be printed.
886 * @param[in] mem_ctx The memory context for the result.
888 * @return Text representation of request.
891 char *tevent_req_default_print(struct tevent_req
*req
, TALLOC_CTX
*mem_ctx
);
894 * @brief Print an tevent_req structure in debug messages.
896 * This function should be used by callers of the async API.
898 * @param[in] mem_ctx The memory context for the result.
900 * @param[in] req The request to be printed.
902 * @return Text representation of request.
904 char *tevent_req_print(TALLOC_CTX
*mem_ctx
, struct tevent_req
*req
);
907 * @brief A typedef for a cancel function for a tevent request.
909 * @param[in] req The tevent request calling this function.
911 * @return True if the request could be canceled, false if not.
913 typedef bool (*tevent_req_cancel_fn
)(struct tevent_req
*req
);
916 * @brief This function sets a cancel function for the given tevent request.
918 * This function can be used to setup a cancel function for the given request.
919 * This will be triggered if the tevent_req_cancel() function was
920 * called on the given request.
922 * @param[in] req The request to use.
924 * @param[in] fn A pointer to the cancel function.
926 void tevent_req_set_cancel_fn(struct tevent_req
*req
, tevent_req_cancel_fn fn
);
930 * @brief Try to cancel the given tevent request.
932 * This function can be used to cancel the given request.
934 * It is only possible to cancel a request when the implementation
935 * has registered a cancel function via the tevent_req_set_cancel_fn().
937 * @param[in] req The request to use.
939 * @return This function returns true if the request is
940 * cancelable, otherwise false is returned.
942 * @note Even if the function returns true, the caller need to wait
943 * for the function to complete normally.
944 * Only the _recv() function of the given request indicates
945 * if the request was really canceled.
947 bool tevent_req_cancel(struct tevent_req
*req
);
949 bool _tevent_req_cancel(struct tevent_req
*req
, const char *location
);
950 #define tevent_req_cancel(req) \
951 _tevent_req_cancel(req, __location__)
955 * @brief A typedef for a cleanup function for a tevent request.
957 * @param[in] req The tevent request calling this function.
959 * @param[in] req_state The current tevent_req_state.
962 typedef void (*tevent_req_cleanup_fn
)(struct tevent_req
*req
,
963 enum tevent_req_state req_state
);
966 * @brief This function sets a cleanup function for the given tevent request.
968 * This function can be used to setup a cleanup function for the given request.
969 * This will be triggered when the tevent_req_done() or tevent_req_error()
970 * function was called, before notifying the callers callback function,
971 * and also before scheduling the deferred trigger.
973 * This might be useful if more than one tevent_req belong together
974 * and need to finish both requests at the same time.
976 * The cleanup function is able to call tevent_req_done() or tevent_req_error()
977 * recursively, the cleanup function is only triggered the first time.
979 * The cleanup function is also called by tevent_req_received()
980 * (possibly triggered from tevent_req_destructor()) before destroying
981 * the private data of the tevent_req.
983 * @param[in] req The request to use.
985 * @param[in] fn A pointer to the cancel function.
987 void tevent_req_set_cleanup_fn(struct tevent_req
*req
, tevent_req_cleanup_fn fn
);
991 * @brief Create an async tevent request.
993 * The new async request will be initialized in state TEVENT_REQ_IN_PROGRESS.
996 * struct tevent_req *req;
997 * struct computation_state *state;
998 * req = tevent_req_create(mem_ctx, &state, struct computation_state);
1001 * Tevent_req_create() allocates and zeros the state variable as a talloc
1002 * child of its result. The state variable should be used as the talloc
1003 * parent for all temporary variables that are allocated during the async
1004 * computation. This way, when the user of the async computation frees
1005 * the request, the state as a talloc child will be free'd along with
1006 * all the temporary variables hanging off the state.
1008 * @param[in] mem_ctx The memory context for the result.
1009 * @param[in] pstate Pointer to the private request state.
1010 * @param[in] type The name of the request.
1012 * @return A new async request. NULL on error.
1014 struct tevent_req
*tevent_req_create(TALLOC_CTX
*mem_ctx
,
1015 void **pstate
, #type);
1017 struct tevent_req
*_tevent_req_create(TALLOC_CTX
*mem_ctx
,
1021 const char *location
);
1023 #define tevent_req_create(_mem_ctx, _pstate, _type) \
1024 _tevent_req_create((_mem_ctx), (_pstate), sizeof(_type), \
1025 #_type, __location__)
1029 * @brief Set a timeout for an async request.
1031 * @param[in] req The request to set the timeout for.
1033 * @param[in] ev The event context to use for the timer.
1035 * @param[in] endtime The endtime of the request.
1037 * @return True if succeeded, false if not.
1039 bool tevent_req_set_endtime(struct tevent_req
*req
,
1040 struct tevent_context
*ev
,
1041 struct timeval endtime
);
1044 * @brief Reset the timer set by tevent_req_set_endtime.
1046 * @param[in] req The request to reset the timeout for
1048 void tevent_req_reset_endtime(struct tevent_req
*req
);
1052 * @brief Call the notify callback of the given tevent request manually.
1054 * @param[in] req The tevent request to call the notify function from.
1056 * @see tevent_req_set_callback()
1058 void tevent_req_notify_callback(struct tevent_req
*req
);
1060 void _tevent_req_notify_callback(struct tevent_req
*req
, const char *location
);
1061 #define tevent_req_notify_callback(req) \
1062 _tevent_req_notify_callback(req, __location__)
1067 * @brief An async request has successfully finished.
1069 * This function is to be used by implementors of async requests. When a
1070 * request is successfully finished, this function calls the user's completion
1073 * @param[in] req The finished request.
1075 void tevent_req_done(struct tevent_req
*req
);
1077 void _tevent_req_done(struct tevent_req
*req
,
1078 const char *location
);
1079 #define tevent_req_done(req) \
1080 _tevent_req_done(req, __location__)
1085 * @brief An async request has seen an error.
1087 * This function is to be used by implementors of async requests. When a
1088 * request can not successfully completed, the implementation should call this
1089 * function with the appropriate status code.
1091 * If error is 0 the function returns false and does nothing more.
1093 * @param[in] req The request with an error.
1095 * @param[in] error The error code.
1097 * @return On success true is returned, false if error is 0.
1100 * int error = first_function();
1101 * if (tevent_req_error(req, error)) {
1105 * error = second_function();
1106 * if (tevent_req_error(req, error)) {
1110 * tevent_req_done(req);
1114 bool tevent_req_error(struct tevent_req
*req
,
1117 bool _tevent_req_error(struct tevent_req
*req
,
1119 const char *location
);
1120 #define tevent_req_error(req, error) \
1121 _tevent_req_error(req, error, __location__)
1126 * @brief Helper function for nomem check.
1128 * Convenience helper to easily check alloc failure within a callback
1129 * implementing the next step of an async request.
1131 * @param[in] p The pointer to be checked.
1133 * @param[in] req The request being processed.
1136 * p = talloc(mem_ctx, bla);
1137 * if (tevent_req_nomem(p, req)) {
1142 bool tevent_req_nomem(const void *p
,
1143 struct tevent_req
*req
);
1145 bool _tevent_req_nomem(const void *p
,
1146 struct tevent_req
*req
,
1147 const char *location
);
1148 #define tevent_req_nomem(p, req) \
1149 _tevent_req_nomem(p, req, __location__)
1154 * @brief Indicate out of memory to a request
1156 * @param[in] req The request being processed.
1158 void tevent_req_oom(struct tevent_req
*req
);
1160 void _tevent_req_oom(struct tevent_req
*req
,
1161 const char *location
);
1162 #define tevent_req_oom(req) \
1163 _tevent_req_oom(req, __location__)
1167 * @brief Finish a request before the caller had the change to set the callback.
1169 * An implementation of an async request might find that it can either finish
1170 * the request without waiting for an external event, or it can not even start
1171 * the engine. To present the illusion of a callback to the user of the API,
1172 * the implementation can call this helper function which triggers an
1173 * immediate event. This way the caller can use the same calling
1174 * conventions, independent of whether the request was actually deferred.
1177 * struct tevent_req *computation_send(TALLOC_CTX *mem_ctx,
1178 * struct tevent_context *ev)
1180 * struct tevent_req *req, *subreq;
1181 * struct computation_state *state;
1182 * req = tevent_req_create(mem_ctx, &state, struct computation_state);
1183 * if (req == NULL) {
1186 * subreq = subcomputation_send(state, ev);
1187 * if (tevent_req_nomem(subreq, req)) {
1188 * return tevent_req_post(req, ev);
1190 * tevent_req_set_callback(subreq, computation_done, req);
1195 * @param[in] req The finished request.
1197 * @param[in] ev The tevent_context for the immediate event.
1199 * @return The given request will be returned.
1201 struct tevent_req
*tevent_req_post(struct tevent_req
*req
,
1202 struct tevent_context
*ev
);
1205 * @brief Finish multiple requests within one function
1207 * Normally tevent_req_notify_callback() and all wrappers
1208 * (e.g. tevent_req_done() and tevent_req_error())
1209 * need to be the last thing an event handler should call.
1210 * This is because the callback is likely to destroy the
1211 * context of the current function.
1213 * If a function wants to notify more than one caller,
1214 * it is dangerous if it just triggers multiple callbacks
1215 * in a row. With tevent_req_defer_callback() it is possible
1216 * to set an event context that will be used to defer the callback
1217 * via an immediate event (similar to tevent_req_post()).
1220 * struct complete_state {
1221 * struct tevent_context *ev;
1223 * struct tevent_req **reqs;
1226 * void complete(struct complete_state *state)
1228 * size_t i, c = talloc_array_length(state->reqs);
1230 * for (i=0; i < c; i++) {
1231 * tevent_req_defer_callback(state->reqs[i], state->ev);
1232 * tevent_req_done(state->reqs[i]);
1237 * @param[in] req The finished request.
1239 * @param[in] ev The tevent_context for the immediate event.
1241 * @return The given request will be returned.
1243 void tevent_req_defer_callback(struct tevent_req
*req
,
1244 struct tevent_context
*ev
);
1247 * @brief Check if the given request is still in progress.
1249 * It is typically used by sync wrapper functions.
1251 * @param[in] req The request to poll.
1253 * @return The boolean form of "is in progress".
1255 bool tevent_req_is_in_progress(struct tevent_req
*req
);
1258 * @brief Actively poll for the given request to finish.
1260 * This function is typically used by sync wrapper functions.
1262 * @param[in] req The request to poll.
1264 * @param[in] ev The tevent_context to be used.
1266 * @return On success true is returned. If a critical error has
1267 * happened in the tevent loop layer false is returned.
1268 * This is not the return value of the given request!
1270 * @note This should only be used if the given tevent context was created by the
1271 * caller, to avoid event loop nesting.
1274 * req = tstream_writev_queue_send(mem_ctx,
1279 * ok = tevent_req_poll(req, tctx->ev);
1280 * rc = tstream_writev_queue_recv(req, &sys_errno);
1284 bool tevent_req_poll(struct tevent_req
*req
,
1285 struct tevent_context
*ev
);
1288 * @brief Get the tevent request state and the actual error set by
1292 * int computation_recv(struct tevent_req *req, uint64_t *perr)
1294 * enum tevent_req_state state;
1296 * if (tevent_req_is_error(req, &state, &err)) {
1304 * @param[in] req The tevent request to get the error from.
1306 * @param[out] state A pointer to store the tevent request error state.
1308 * @param[out] error A pointer to store the error set by tevent_req_error().
1310 * @return True if the function could set error and state, false
1313 * @see tevent_req_error()
1315 bool tevent_req_is_error(struct tevent_req
*req
,
1316 enum tevent_req_state
*state
,
1320 * @brief Use as the last action of a _recv() function.
1322 * This function destroys the attached private data.
1324 * @param[in] req The finished request.
1326 void tevent_req_received(struct tevent_req
*req
);
1329 * @brief Create a tevent subrequest at a given time.
1331 * The idea is that always the same syntax for tevent requests.
1333 * @param[in] mem_ctx The talloc memory context to use.
1335 * @param[in] ev The event handle to setup the request.
1337 * @param[in] wakeup_time The time to wakeup and execute the request.
1339 * @return The new subrequest, NULL on error.
1343 * static void my_callback_wakeup_done(tevent_req *subreq)
1345 * struct tevent_req *req = tevent_req_callback_data(subreq,
1346 * struct tevent_req);
1349 * ok = tevent_wakeup_recv(subreq);
1350 * TALLOC_FREE(subreq);
1352 * tevent_req_error(req, -1);
1360 * subreq = tevent_wakeup_send(mem_ctx, ev, wakeup_time);
1361 * if (tevent_req_nomem(subreq, req)) {
1364 * tevent_set_callback(subreq, my_callback_wakeup_done, req);
1367 * @see tevent_wakeup_recv()
1369 struct tevent_req
*tevent_wakeup_send(TALLOC_CTX
*mem_ctx
,
1370 struct tevent_context
*ev
,
1371 struct timeval wakeup_time
);
1374 * @brief Check if the wakeup has been correctly executed.
1376 * This function needs to be called in the callback function set after calling
1377 * tevent_wakeup_send().
1379 * @param[in] req The tevent request to check.
1381 * @return True on success, false otherwise.
1383 * @see tevent_wakeup_recv()
1385 bool tevent_wakeup_recv(struct tevent_req
*req
);
1390 * @defgroup tevent_helpers The tevent helper functions
1399 * @brief Compare two timeval values.
1401 * @param[in] tv1 The first timeval value to compare.
1403 * @param[in] tv2 The second timeval value to compare.
1405 * @return 0 if they are equal.
1406 * 1 if the first time is greater than the second.
1407 * -1 if the first time is smaller than the second.
1409 int tevent_timeval_compare(const struct timeval
*tv1
,
1410 const struct timeval
*tv2
);
1413 * @brief Get a zero timeval value.
1415 * @return A zero timeval value.
1417 struct timeval
tevent_timeval_zero(void);
1420 * @brief Get a timeval value for the current time.
1422 * @return A timeval value with the current time.
1424 struct timeval
tevent_timeval_current(void);
1427 * @brief Get a timeval structure with the given values.
1429 * @param[in] secs The seconds to set.
1431 * @param[in] usecs The microseconds to set.
1433 * @return A timeval structure with the given values.
1435 struct timeval
tevent_timeval_set(uint32_t secs
, uint32_t usecs
);
1438 * @brief Get the difference between two timeval values.
1440 * @param[in] tv1 The first timeval.
1442 * @param[in] tv2 The second timeval.
1444 * @return A timeval structure with the difference between the
1445 * first and the second value.
1447 struct timeval
tevent_timeval_until(const struct timeval
*tv1
,
1448 const struct timeval
*tv2
);
1451 * @brief Check if a given timeval structure is zero.
1453 * @param[in] tv The timeval to check if it is zero.
1455 * @return True if it is zero, false otherwise.
1457 bool tevent_timeval_is_zero(const struct timeval
*tv
);
1460 * @brief Add the given amount of time to a timeval structure.
1462 * @param[in] tv The timeval structure to add the time.
1464 * @param[in] secs The seconds to add to the timeval.
1466 * @param[in] usecs The microseconds to add to the timeval.
1468 * @return The timeval structure with the new time.
1470 struct timeval
tevent_timeval_add(const struct timeval
*tv
, uint32_t secs
,
1474 * @brief Get a timeval in the future with a specified offset from now.
1476 * @param[in] secs The seconds of the offset from now.
1478 * @param[in] usecs The microseconds of the offset from now.
1480 * @return A timval with the given offset in the future.
1482 struct timeval
tevent_timeval_current_ofs(uint32_t secs
, uint32_t usecs
);
1488 * @defgroup tevent_queue The tevent queue functions
1491 * A tevent_queue is used to queue up async requests that must be
1492 * serialized. For example writing buffers into a socket must be
1493 * serialized. Writing a large lump of data into a socket can require
1494 * multiple write(2) or send(2) system calls. If more than one async
1495 * request is outstanding to write large buffers into a socket, every
1496 * request must individually be completed before the next one begins,
1497 * even if multiple syscalls are required.
1499 * Take a look at @ref tevent_queue_tutorial for more details.
1503 struct tevent_queue
;
1504 struct tevent_queue_entry
;
1508 * @brief Create and start a tevent queue.
1510 * @param[in] mem_ctx The talloc memory context to allocate the queue.
1512 * @param[in] name The name to use to identify the queue.
1514 * @return An allocated tevent queue on success, NULL on error.
1516 * @see tevent_queue_start()
1517 * @see tevent_queue_stop()
1519 struct tevent_queue
*tevent_queue_create(TALLOC_CTX
*mem_ctx
,
1522 struct tevent_queue
*_tevent_queue_create(TALLOC_CTX
*mem_ctx
,
1524 const char *location
);
1526 #define tevent_queue_create(_mem_ctx, _name) \
1527 _tevent_queue_create((_mem_ctx), (_name), __location__)
1531 * @brief A callback trigger function run by the queue.
1533 * @param[in] req The tevent request the trigger function is executed on.
1535 * @param[in] private_data The private data pointer specified by
1536 * tevent_queue_add().
1538 * @see tevent_queue_add()
1539 * @see tevent_queue_add_entry()
1540 * @see tevent_queue_add_optimize_empty()
1542 typedef void (*tevent_queue_trigger_fn_t
)(struct tevent_req
*req
,
1543 void *private_data
);
1546 * @brief Add a tevent request to the queue.
1548 * @param[in] queue The queue to add the request.
1550 * @param[in] ev The event handle to use for the request.
1552 * @param[in] req The tevent request to add to the queue.
1554 * @param[in] trigger The function triggered by the queue when the request
1555 * is called. Since tevent 0.9.14 it's possible to
1556 * pass NULL, in order to just add a "blocker" to the
1559 * @param[in] private_data The private data passed to the trigger function.
1561 * @return True if the request has been successfully added, false
1564 bool tevent_queue_add(struct tevent_queue
*queue
,
1565 struct tevent_context
*ev
,
1566 struct tevent_req
*req
,
1567 tevent_queue_trigger_fn_t trigger
,
1568 void *private_data
);
1571 * @brief Add a tevent request to the queue.
1573 * The request can be removed from the queue by calling talloc_free()
1574 * (or a similar function) on the returned queue entry. This
1575 * is the only difference to tevent_queue_add().
1577 * @param[in] queue The queue to add the request.
1579 * @param[in] ev The event handle to use for the request.
1581 * @param[in] req The tevent request to add to the queue.
1583 * @param[in] trigger The function triggered by the queue when the request
1584 * is called. Since tevent 0.9.14 it's possible to
1585 * pass NULL, in order to just add a "blocker" to the
1588 * @param[in] private_data The private data passed to the trigger function.
1590 * @return a pointer to the tevent_queue_entry if the request
1591 * has been successfully added, NULL otherwise.
1593 * @see tevent_queue_add()
1594 * @see tevent_queue_add_optimize_empty()
1596 struct tevent_queue_entry
*tevent_queue_add_entry(
1597 struct tevent_queue
*queue
,
1598 struct tevent_context
*ev
,
1599 struct tevent_req
*req
,
1600 tevent_queue_trigger_fn_t trigger
,
1601 void *private_data
);
1604 * @brief Add a tevent request to the queue using a possible optimization.
1606 * This tries to optimize for the empty queue case and may calls
1607 * the trigger function directly. This is the only difference compared
1608 * to tevent_queue_add_entry().
1610 * The caller needs to be prepared that the trigger function has
1611 * already called tevent_req_notify_callback(), tevent_req_error(),
1612 * tevent_req_done() or a similar function.
1614 * The request can be removed from the queue by calling talloc_free()
1615 * (or a similar function) on the returned queue entry.
1617 * @param[in] queue The queue to add the request.
1619 * @param[in] ev The event handle to use for the request.
1621 * @param[in] req The tevent request to add to the queue.
1623 * @param[in] trigger The function triggered by the queue when the request
1624 * is called. Since tevent 0.9.14 it's possible to
1625 * pass NULL, in order to just add a "blocker" to the
1628 * @param[in] private_data The private data passed to the trigger function.
1630 * @return a pointer to the tevent_queue_entry if the request
1631 * has been successfully added, NULL otherwise.
1633 * @see tevent_queue_add()
1634 * @see tevent_queue_add_entry()
1636 struct tevent_queue_entry
*tevent_queue_add_optimize_empty(
1637 struct tevent_queue
*queue
,
1638 struct tevent_context
*ev
,
1639 struct tevent_req
*req
,
1640 tevent_queue_trigger_fn_t trigger
,
1641 void *private_data
);
1644 * @brief Start a tevent queue.
1646 * The queue is started by default.
1648 * @param[in] queue The queue to start.
1650 void tevent_queue_start(struct tevent_queue
*queue
);
1653 * @brief Stop a tevent queue.
1655 * The queue is started by default.
1657 * @param[in] queue The queue to stop.
1659 void tevent_queue_stop(struct tevent_queue
*queue
);
1662 * @brief Get the length of the queue.
1664 * @param[in] queue The queue to get the length from.
1666 * @return The number of elements.
1668 size_t tevent_queue_length(struct tevent_queue
*queue
);
1671 * @brief Is the tevent queue running.
1673 * The queue is started by default.
1675 * @param[in] queue The queue.
1677 * @return Wether the queue is running or not..
1679 bool tevent_queue_running(struct tevent_queue
*queue
);
1682 * @brief Create a tevent subrequest that waits in a tevent_queue
1684 * The idea is that always the same syntax for tevent requests.
1686 * @param[in] mem_ctx The talloc memory context to use.
1688 * @param[in] ev The event handle to setup the request.
1690 * @param[in] queue The queue to wait in.
1692 * @return The new subrequest, NULL on error.
1694 * @see tevent_queue_wait_recv()
1696 struct tevent_req
*tevent_queue_wait_send(TALLOC_CTX
*mem_ctx
,
1697 struct tevent_context
*ev
,
1698 struct tevent_queue
*queue
);
1701 * @brief Check if we no longer need to wait in the queue.
1703 * This function needs to be called in the callback function set after calling
1704 * tevent_queue_wait_send().
1706 * @param[in] req The tevent request to check.
1708 * @return True on success, false otherwise.
1710 * @see tevent_queue_wait_send()
1712 bool tevent_queue_wait_recv(struct tevent_req
*req
);
1714 typedef int (*tevent_nesting_hook
)(struct tevent_context
*ev
,
1719 const char *location
);
1722 * @brief Create a tevent_thread_proxy for message passing between threads.
1724 * The tevent_context must have been allocated on the NULL
1725 * talloc context, and talloc_disable_null_tracking() must
1728 * @param[in] dest_ev_ctx The tevent_context to receive events.
1730 * @return An allocated tevent_thread_proxy, NULL on error.
1731 * If tevent was compiled without PTHREAD support
1732 * NULL is always returned and errno set to ENOSYS.
1734 * @see tevent_thread_proxy_schedule()
1736 struct tevent_thread_proxy
*tevent_thread_proxy_create(
1737 struct tevent_context
*dest_ev_ctx
);
1740 * @brief Schedule an immediate event on an event context from another thread.
1742 * Causes dest_ev_ctx, being run by another thread, to receive an
1743 * immediate event calling the handler with the *pp_private parameter.
1745 * *pp_im must be a pointer to an immediate event talloced on a context owned
1746 * by the calling thread, or the NULL context. Ownership will
1747 * be transferred to the tevent_thread_proxy and *pp_im will be returned as NULL.
1749 * *pp_private_data must be a talloced area of memory with no destructors.
1750 * Ownership of this memory will be transferred to the tevent library and
1751 * *pp_private_data will be set to NULL on successful completion of
1752 * the call. Set pp_private to NULL if no parameter transfer
1753 * needed (a pure callback). This is an asynchronous request, caller
1754 * does not wait for callback to be completed before returning.
1756 * @param[in] tp The tevent_thread_proxy to use.
1758 * @param[in] pp_im Pointer to immediate event pointer.
1760 * @param[in] handler The function that will be called.
1762 * @param[in] pp_private_data The talloced memory to transfer.
1764 * @see tevent_thread_proxy_create()
1766 void tevent_thread_proxy_schedule(struct tevent_thread_proxy
*tp
,
1767 struct tevent_immediate
**pp_im
,
1768 tevent_immediate_handler_t handler
,
1769 void *pp_private_data
);
1772 * @brief Create a context for threaded activation of immediates
1774 * A tevent_treaded_context provides a link into an event
1775 * context. Using tevent_threaded_schedule_immediate, it is possible
1776 * to activate an immediate event from within a thread.
1778 * It is the duty of the caller of tevent_threaded_context_create() to
1779 * keep the event context around longer than any
1780 * tevent_threaded_context. tevent will abort if ev is talloc_free'ed
1781 * with an active tevent_threaded_context.
1783 * If tevent is build without pthread support, this always returns
1784 * NULL with errno=ENOSYS.
1786 * @param[in] mem_ctx The talloc memory context to use.
1787 * @param[in] ev The event context to link this to.
1788 * @return The threaded context, or NULL with errno set.
1790 * @see tevent_threaded_schedule_immediate()
1792 * @note Available as of tevent 0.9.30
1794 struct tevent_threaded_context
*tevent_threaded_context_create(
1795 TALLOC_CTX
*mem_ctx
, struct tevent_context
*ev
);
1799 * @brief Activate an immediate from a thread
1801 * Activate an immediate from within a thread.
1803 * This routine does not watch out for talloc hierarchies. This means
1804 * that it is highly recommended to create the tevent_immediate in the
1805 * thread owning tctx, allocate a threaded job description for the
1806 * thread, hand over both pointers to a helper thread and not touch it
1807 * in the main thread at all anymore.
1809 * tevent_threaded_schedule_immediate is intended as a job completion
1810 * indicator for simple threaded helpers.
1812 * Please be aware that tevent_threaded_schedule_immediate is very
1813 * picky about its arguments: An immediate may not already be
1814 * activated and the handler must exist. With
1815 * tevent_threaded_schedule_immediate memory ownership is transferred
1816 * to the main thread holding the tevent context behind tctx, the
1817 * helper thread can't access it anymore.
1819 * @param[in] tctx The threaded context to go through
1820 * @param[in] im The immediate event to activate
1821 * @param[in] handler The immediate handler to call in the main thread
1822 * @param[in] private_data Pointer for the immediate handler
1824 * @see tevent_threaded_context_create()
1826 * @note Available as of tevent 0.9.30
1828 void tevent_threaded_schedule_immediate(struct tevent_threaded_context
*tctx
,
1829 struct tevent_immediate
*im
,
1830 tevent_immediate_handler_t handler
,
1831 void *private_data
);
1833 void _tevent_threaded_schedule_immediate(struct tevent_threaded_context
*tctx
,
1834 struct tevent_immediate
*im
,
1835 tevent_immediate_handler_t handler
,
1837 const char *handler_name
,
1838 const char *location
);
1839 #define tevent_threaded_schedule_immediate(tctx, im, handler, private_data) \
1840 _tevent_threaded_schedule_immediate(tctx, im, handler, private_data, \
1841 #handler, __location__);
1844 #ifdef TEVENT_DEPRECATED
1845 #ifndef _DEPRECATED_
1846 #ifdef HAVE___ATTRIBUTE__
1847 #define _DEPRECATED_ __attribute__ ((deprecated))
1849 #define _DEPRECATED_
1852 void tevent_loop_allow_nesting(struct tevent_context
*ev
) _DEPRECATED_
;
1853 void tevent_loop_set_nesting_hook(struct tevent_context
*ev
,
1854 tevent_nesting_hook hook
,
1855 void *private_data
) _DEPRECATED_
;
1856 int _tevent_loop_until(struct tevent_context
*ev
,
1857 bool (*finished
)(void *private_data
),
1859 const char *location
) _DEPRECATED_
;
1860 #define tevent_loop_until(ev, finished, private_data) \
1861 _tevent_loop_until(ev, finished, private_data, __location__)
1864 int tevent_re_initialise(struct tevent_context
*ev
);
1869 * @defgroup tevent_ops The tevent operation functions
1872 * The following structure and registration functions are exclusively
1873 * needed for people writing and pluggin a different event engine.
1874 * There is nothing useful for normal tevent user in here.
1880 int (*context_init
)(struct tevent_context
*ev
);
1882 /* fd_event functions */
1883 struct tevent_fd
*(*add_fd
)(struct tevent_context
*ev
,
1884 TALLOC_CTX
*mem_ctx
,
1885 int fd
, uint16_t flags
,
1886 tevent_fd_handler_t handler
,
1888 const char *handler_name
,
1889 const char *location
);
1890 void (*set_fd_close_fn
)(struct tevent_fd
*fde
,
1891 tevent_fd_close_fn_t close_fn
);
1892 uint16_t (*get_fd_flags
)(struct tevent_fd
*fde
);
1893 void (*set_fd_flags
)(struct tevent_fd
*fde
, uint16_t flags
);
1895 /* timed_event functions */
1896 struct tevent_timer
*(*add_timer
)(struct tevent_context
*ev
,
1897 TALLOC_CTX
*mem_ctx
,
1898 struct timeval next_event
,
1899 tevent_timer_handler_t handler
,
1901 const char *handler_name
,
1902 const char *location
);
1904 /* immediate event functions */
1905 void (*schedule_immediate
)(struct tevent_immediate
*im
,
1906 struct tevent_context
*ev
,
1907 tevent_immediate_handler_t handler
,
1909 const char *handler_name
,
1910 const char *location
);
1912 /* signal functions */
1913 struct tevent_signal
*(*add_signal
)(struct tevent_context
*ev
,
1914 TALLOC_CTX
*mem_ctx
,
1915 int signum
, int sa_flags
,
1916 tevent_signal_handler_t handler
,
1918 const char *handler_name
,
1919 const char *location
);
1921 /* loop functions */
1922 int (*loop_once
)(struct tevent_context
*ev
, const char *location
);
1923 int (*loop_wait
)(struct tevent_context
*ev
, const char *location
);
1926 bool tevent_register_backend(const char *name
, const struct tevent_ops
*ops
);
1931 * @defgroup tevent_compat The tevent compatibility functions
1934 * The following definitions are usueful only for compatibility with the
1935 * implementation originally developed within the samba4 code and will be
1936 * soon removed. Please NEVER use in new code.
1943 #ifdef TEVENT_COMPAT_DEFINES
1945 #define event_context tevent_context
1946 #define event_ops tevent_ops
1947 #define fd_event tevent_fd
1948 #define timed_event tevent_timer
1949 #define signal_event tevent_signal
1951 #define event_fd_handler_t tevent_fd_handler_t
1952 #define event_timed_handler_t tevent_timer_handler_t
1953 #define event_signal_handler_t tevent_signal_handler_t
1955 #define event_context_init(mem_ctx) \
1956 tevent_context_init(mem_ctx)
1958 #define event_context_init_byname(mem_ctx, name) \
1959 tevent_context_init_byname(mem_ctx, name)
1961 #define event_backend_list(mem_ctx) \
1962 tevent_backend_list(mem_ctx)
1964 #define event_set_default_backend(backend) \
1965 tevent_set_default_backend(backend)
1967 #define event_add_fd(ev, mem_ctx, fd, flags, handler, private_data) \
1968 tevent_add_fd(ev, mem_ctx, fd, flags, handler, private_data)
1970 #define event_add_timed(ev, mem_ctx, next_event, handler, private_data) \
1971 tevent_add_timer(ev, mem_ctx, next_event, handler, private_data)
1973 #define event_add_signal(ev, mem_ctx, signum, sa_flags, handler, private_data) \
1974 tevent_add_signal(ev, mem_ctx, signum, sa_flags, handler, private_data)
1976 #define event_loop_once(ev) \
1977 tevent_loop_once(ev)
1979 #define event_loop_wait(ev) \
1980 tevent_loop_wait(ev)
1982 #define event_get_fd_flags(fde) \
1983 tevent_fd_get_flags(fde)
1985 #define event_set_fd_flags(fde, flags) \
1986 tevent_fd_set_flags(fde, flags)
1988 #define EVENT_FD_READ TEVENT_FD_READ
1989 #define EVENT_FD_WRITE TEVENT_FD_WRITE
1991 #define EVENT_FD_WRITEABLE(fde) \
1992 TEVENT_FD_WRITEABLE(fde)
1994 #define EVENT_FD_READABLE(fde) \
1995 TEVENT_FD_READABLE(fde)
1997 #define EVENT_FD_NOT_WRITEABLE(fde) \
1998 TEVENT_FD_NOT_WRITEABLE(fde)
2000 #define EVENT_FD_NOT_READABLE(fde) \
2001 TEVENT_FD_NOT_READABLE(fde)
2003 #define ev_debug_level tevent_debug_level
2005 #define EV_DEBUG_FATAL TEVENT_DEBUG_FATAL
2006 #define EV_DEBUG_ERROR TEVENT_DEBUG_ERROR
2007 #define EV_DEBUG_WARNING TEVENT_DEBUG_WARNING
2008 #define EV_DEBUG_TRACE TEVENT_DEBUG_TRACE
2010 #define ev_set_debug(ev, debug, context) \
2011 tevent_set_debug(ev, debug, context)
2013 #define ev_set_debug_stderr(_ev) tevent_set_debug_stderr(ev)
2015 #endif /* TEVENT_COMPAT_DEFINES */
2019 #endif /* __TEVENT_H__ */