talloc: use the system pytalloc-util for python3 as well
[sfrench/samba-autobuild/.git] / lib / tevent / tevent.h
1 /* 
2    Unix SMB/CIFS implementation.
3
4    generalised event loop handling
5
6    Copyright (C) Andrew Tridgell 2005
7    Copyright (C) Stefan Metzmacher 2005-2009
8    Copyright (C) Volker Lendecke 2008
9
10      ** NOTE! The following LGPL license applies to the tevent
11      ** library. This does NOT imply that all of Samba is released
12      ** under the LGPL
13
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.
18
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.
23
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/>.
26 */
27
28 #ifndef __TEVENT_H__
29 #define __TEVENT_H__
30
31 #include <stdint.h>
32 #include <talloc.h>
33 #include <sys/time.h>
34 #include <stdbool.h>
35
36 struct tevent_context;
37 struct tevent_ops;
38 struct tevent_fd;
39 struct tevent_timer;
40 struct tevent_immediate;
41 struct tevent_signal;
42 struct tevent_thread_proxy;
43 struct tevent_threaded_context;
44
45 /**
46  * @defgroup tevent The tevent API
47  *
48  * The tevent low-level API
49  *
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.
53  *
54  * @{
55  */
56
57 /* event handler types */
58 /**
59  * Called when a file descriptor monitored by tevent has
60  * data to be read or written on it.
61  */
62 typedef void (*tevent_fd_handler_t)(struct tevent_context *ev,
63                                     struct tevent_fd *fde,
64                                     uint16_t flags,
65                                     void *private_data);
66
67 /**
68  * Called when tevent is ceasing the monitoring of a file descriptor.
69  */
70 typedef void (*tevent_fd_close_fn_t)(struct tevent_context *ev,
71                                      struct tevent_fd *fde,
72                                      int fd,
73                                      void *private_data);
74
75 /**
76  * Called when a tevent timer has fired.
77  */
78 typedef void (*tevent_timer_handler_t)(struct tevent_context *ev,
79                                        struct tevent_timer *te,
80                                        struct timeval current_time,
81                                        void *private_data);
82
83 /**
84  * Called when a tevent immediate event is invoked.
85  */
86 typedef void (*tevent_immediate_handler_t)(struct tevent_context *ctx,
87                                            struct tevent_immediate *im,
88                                            void *private_data);
89
90 /**
91  * Called after tevent detects the specified signal.
92  */
93 typedef void (*tevent_signal_handler_t)(struct tevent_context *ev,
94                                         struct tevent_signal *se,
95                                         int signum,
96                                         int count,
97                                         void *siginfo,
98                                         void *private_data);
99
100 /**
101  * @brief Create a event_context structure.
102  *
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.
106  *
107  * @param[in]  mem_ctx  The memory context to use.
108  *
109  * @return              An allocated tevent context, NULL on error.
110  *
111  * @see tevent_context_init()
112  */
113 struct tevent_context *tevent_context_init(TALLOC_CTX *mem_ctx);
114
115 /**
116  * @brief Create a event_context structure and select a specific backend.
117  *
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.
121  *
122  * @param[in]  mem_ctx  The memory context to use.
123  *
124  * @param[in]  name     The name of the backend to use.
125  *
126  * @return              An allocated tevent context, NULL on error.
127  */
128 struct tevent_context *tevent_context_init_byname(TALLOC_CTX *mem_ctx, const char *name);
129
130 /**
131  * @brief Create a custom event context
132  *
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
136  *
137  * @return              An allocated tevent context, NULL on error.
138  *
139  */
140 struct tevent_context *tevent_context_init_ops(TALLOC_CTX *mem_ctx,
141                                                const struct tevent_ops *ops,
142                                                void *additional_data);
143
144 /**
145  * @brief List available backends.
146  *
147  * @param[in]  mem_ctx  The memory context to use.
148  *
149  * @return              A string vector with a terminating NULL element, NULL
150  *                      on error.
151  */
152 const char **tevent_backend_list(TALLOC_CTX *mem_ctx);
153
154 /**
155  * @brief Set the default tevent backend.
156  *
157  * @param[in]  backend  The name of the backend to set.
158  */
159 void tevent_set_default_backend(const char *backend);
160
161 #ifdef DOXYGEN
162 /**
163  * @brief Add a file descriptor based event.
164  *
165  * @param[in]  ev       The event context to work on.
166  *
167  * @param[in]  mem_ctx  The talloc memory context to use.
168  *
169  * @param[in]  fd       The file descriptor to base the event on.
170  *
171  * @param[in]  flags    #TEVENT_FD_READ or #TEVENT_FD_WRITE
172  *
173  * @param[in]  handler  The callback handler for the event.
174  *
175  * @param[in]  private_data  The private data passed to the callback handler.
176  *
177  * @return              The file descriptor based event, NULL on error.
178  *
179  * @note To cancel the monitoring of a file descriptor, call talloc_free()
180  * on the object returned by this function.
181  *
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
185  * for an example.
186  */
187 struct tevent_fd *tevent_add_fd(struct tevent_context *ev,
188                                 TALLOC_CTX *mem_ctx,
189                                 int fd,
190                                 uint16_t flags,
191                                 tevent_fd_handler_t handler,
192                                 void *private_data);
193 #else
194 struct tevent_fd *_tevent_add_fd(struct tevent_context *ev,
195                                  TALLOC_CTX *mem_ctx,
196                                  int fd,
197                                  uint16_t flags,
198                                  tevent_fd_handler_t handler,
199                                  void *private_data,
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__)
205 #endif
206
207 #ifdef DOXYGEN
208 /**
209  * @brief Add a timed event
210  *
211  * @param[in]  ev       The event context to work on.
212  *
213  * @param[in]  mem_ctx  The talloc memory context to use.
214  *
215  * @param[in]  next_event  Timeval specifying the absolute time to fire this
216  * event. This is not an offset.
217  *
218  * @param[in]  handler  The callback handler for the event.
219  *
220  * @param[in]  private_data  The private data passed to the callback handler.
221  *
222  * @return The newly-created timer event, or NULL on error.
223  *
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.
227  *
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.
231  *
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!
236  */
237 struct tevent_timer *tevent_add_timer(struct tevent_context *ev,
238                                       TALLOC_CTX *mem_ctx,
239                                       struct timeval next_event,
240                                       tevent_timer_handler_t handler,
241                                       void *private_data);
242 #else
243 struct tevent_timer *_tevent_add_timer(struct tevent_context *ev,
244                                        TALLOC_CTX *mem_ctx,
245                                        struct timeval next_event,
246                                        tevent_timer_handler_t handler,
247                                        void *private_data,
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__)
253 #endif
254
255 /**
256  * @brief Set the time a tevent_timer fires
257  *
258  * @param[in]  te       The timer event to reset
259  *
260  * @param[in]  next_event  Timeval specifying the absolute time to fire this
261  * event. This is not an offset.
262  */
263 void tevent_update_timer(struct tevent_timer *te, struct timeval next_event);
264
265 #ifdef DOXYGEN
266 /**
267  * Initialize an immediate event object
268  *
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)
271  *
272  * @param[in] mem_ctx  The talloc memory context to use as the parent
273  *
274  * @return An empty tevent_immediate object. Use tevent_schedule_immediate
275  * to populate and use it.
276  *
277  * @note Available as of tevent 0.9.8
278  */
279 struct tevent_immediate *tevent_create_immediate(TALLOC_CTX *mem_ctx);
280 #else
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__)
285 #endif
286
287 #ifdef DOXYGEN
288
289 /**
290  * Schedule an event for immediate execution. This event will occur
291  * immediately after returning from the current event (before any other
292  * event occurs)
293  *
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
298  */
299 void tevent_schedule_immediate(struct tevent_immediate *im,
300                 struct tevent_context *ctx,
301                 tevent_immediate_handler_t handler,
302                 void *private_data);
303 #else
304 void _tevent_schedule_immediate(struct tevent_immediate *im,
305                                 struct tevent_context *ctx,
306                                 tevent_immediate_handler_t handler,
307                                 void *private_data,
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__);
313 #endif
314
315 #ifdef DOXYGEN
316 /**
317  * @brief Add a tevent signal handler
318  *
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.
322  *
323  * @param[in]  ev       The event context to work on.
324  *
325  * @param[in]  mem_ctx  The talloc memory context to use.
326  *
327  * @param[in]  signum   The signal to trap
328  *
329  * @param[in]  handler  The callback handler for the signal.
330  *
331  * @param[in]  sa_flags sigaction flags for this signal handler.
332  *
333  * @param[in]  private_data  The private data passed to the callback handler.
334  *
335  * @return The newly-created signal handler event, or NULL on error.
336  *
337  * @note To cancel a signal handler, call talloc_free() on the event returned
338  * from this function.
339  *
340  * @see tevent_num_signals, tevent_sa_info_queue_count
341  */
342 struct tevent_signal *tevent_add_signal(struct tevent_context *ev,
343                      TALLOC_CTX *mem_ctx,
344                      int signum,
345                      int sa_flags,
346                      tevent_signal_handler_t handler,
347                      void *private_data);
348 #else
349 struct tevent_signal *_tevent_add_signal(struct tevent_context *ev,
350                                          TALLOC_CTX *mem_ctx,
351                                          int signum,
352                                          int sa_flags,
353                                          tevent_signal_handler_t handler,
354                                          void *private_data,
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__)
360 #endif
361
362 /**
363  * @brief the number of supported signals
364  *
365  * This returns value of the configure time TEVENT_NUM_SIGNALS constant.
366  *
367  * The 'signum' argument of tevent_add_signal() must be less than
368  * TEVENT_NUM_SIGNALS.
369  *
370  * @see tevent_add_signal
371  */
372 size_t tevent_num_signals(void);
373
374 /**
375  * @brief the number of pending realtime signals
376  *
377  * This returns value of TEVENT_SA_INFO_QUEUE_COUNT.
378  *
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.
382  *
383  * @see tevent_add_signal
384  */
385 size_t tevent_sa_info_queue_count(void);
386
387 #ifdef DOXYGEN
388 /**
389  * @brief Pass a single time through the mainloop
390  *
391  * This will process any appropriate signal, immediate, fd and timer events
392  *
393  * @param[in]  ev The event context to process
394  *
395  * @return Zero on success, nonzero if an internal error occurred
396  */
397 int tevent_loop_once(struct tevent_context *ev);
398 #else
399 int _tevent_loop_once(struct tevent_context *ev, const char *location);
400 #define tevent_loop_once(ev) \
401         _tevent_loop_once(ev, __location__)
402 #endif
403
404 #ifdef DOXYGEN
405 /**
406  * @brief Run the mainloop
407  *
408  * The mainloop will run until there are no events remaining to be processed
409  *
410  * @param[in]  ev The event context to process
411  *
412  * @return Zero if all events have been processed. Nonzero if an internal
413  * error occurred.
414  */
415 int tevent_loop_wait(struct tevent_context *ev);
416 #else
417 int _tevent_loop_wait(struct tevent_context *ev, const char *location);
418 #define tevent_loop_wait(ev) \
419         _tevent_loop_wait(ev, __location__)
420 #endif
421
422
423 /**
424  * Assign a function to run when a tevent_fd is freed
425  *
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.
429  *
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
432  */
433 void tevent_fd_set_close_fn(struct tevent_fd *fde,
434                             tevent_fd_close_fn_t close_fn);
435
436 /**
437  * Automatically close the file descriptor when the tevent_fd is freed
438  *
439  * This function calls close(fd) internally.
440  *
441  * @param[in] fde  File descriptor event to auto-close
442  */
443 void tevent_fd_set_auto_close(struct tevent_fd *fde);
444
445 /**
446  * Return the flags set on this file descriptor event
447  *
448  * @param[in] fde  File descriptor event to query
449  *
450  * @return The flags set on the event. See #TEVENT_FD_READ and
451  * #TEVENT_FD_WRITE
452  */
453 uint16_t tevent_fd_get_flags(struct tevent_fd *fde);
454
455 /**
456  * Set flags on a file descriptor event
457  *
458  * @param[in] fde    File descriptor event to set
459  * @param[in] flags  Flags to set on the event. See #TEVENT_FD_READ and
460  * #TEVENT_FD_WRITE
461  */
462 void tevent_fd_set_flags(struct tevent_fd *fde, uint16_t flags);
463
464 /**
465  * Query whether tevent supports signal handling
466  *
467  * @param[in] ev  An initialized tevent context
468  *
469  * @return True if this platform and tevent context support signal handling
470  */
471 bool tevent_signal_support(struct tevent_context *ev);
472
473 void tevent_set_abort_fn(void (*abort_fn)(const char *reason));
474
475 /* bits for file descriptor event flags */
476
477 /**
478  * Monitor a file descriptor for data to be read
479  */
480 #define TEVENT_FD_READ 1
481 /**
482  * Monitor a file descriptor for writeability
483  */
484 #define TEVENT_FD_WRITE 2
485
486 /**
487  * Convenience function for declaring a tevent_fd writable
488  */
489 #define TEVENT_FD_WRITEABLE(fde) \
490         tevent_fd_set_flags(fde, tevent_fd_get_flags(fde) | TEVENT_FD_WRITE)
491
492 /**
493  * Convenience function for declaring a tevent_fd readable
494  */
495 #define TEVENT_FD_READABLE(fde) \
496         tevent_fd_set_flags(fde, tevent_fd_get_flags(fde) | TEVENT_FD_READ)
497
498 /**
499  * Convenience function for declaring a tevent_fd non-writable
500  */
501 #define TEVENT_FD_NOT_WRITEABLE(fde) \
502         tevent_fd_set_flags(fde, tevent_fd_get_flags(fde) & ~TEVENT_FD_WRITE)
503
504 /**
505  * Convenience function for declaring a tevent_fd non-readable
506  */
507 #define TEVENT_FD_NOT_READABLE(fde) \
508         tevent_fd_set_flags(fde, tevent_fd_get_flags(fde) & ~TEVENT_FD_READ)
509
510 /**
511  * Debug level of tevent
512  */
513 enum tevent_debug_level {
514         TEVENT_DEBUG_FATAL,
515         TEVENT_DEBUG_ERROR,
516         TEVENT_DEBUG_WARNING,
517         TEVENT_DEBUG_TRACE
518 };
519
520 /**
521  * @brief The tevent debug callbac.
522  *
523  * @param[in]  context  The memory context to use.
524  *
525  * @param[in]  level    The debug level.
526  *
527  * @param[in]  fmt      The format string.
528  *
529  * @param[in]  ap       The arguments for the format string.
530  */
531 typedef void (*tevent_debug_fn)(void *context,
532                                 enum tevent_debug_level level,
533                                 const char *fmt,
534                                 va_list ap) PRINTF_ATTRIBUTE(3,0);
535
536 /**
537  * Set destination for tevent debug messages
538  *
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.
542  *
543  * @return Always returns 0 as of version 0.9.8
544  *
545  * @note Default is to emit no debug messages
546  */
547 int tevent_set_debug(struct tevent_context *ev,
548                      tevent_debug_fn debug,
549                      void *context);
550
551 /**
552  * Designate stderr for debug message output
553  *
554  * @param[in] ev     Event context to debug
555  *
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()
559  */
560 int tevent_set_debug_stderr(struct tevent_context *ev);
561
562 enum tevent_trace_point {
563         /**
564          * Corresponds to a trace point just before waiting
565          */
566         TEVENT_TRACE_BEFORE_WAIT,
567         /**
568          * Corresponds to a trace point just after waiting
569          */
570         TEVENT_TRACE_AFTER_WAIT,
571 #define TEVENT_HAS_LOOP_ONCE_TRACE_POINTS 1
572         /**
573          * Corresponds to a trace point just before calling
574          * the loop_once() backend function.
575          */
576         TEVENT_TRACE_BEFORE_LOOP_ONCE,
577         /**
578          * Corresponds to a trace point right after the
579          * loop_once() backend function has returned.
580          */
581         TEVENT_TRACE_AFTER_LOOP_ONCE,
582 };
583
584 typedef void (*tevent_trace_callback_t)(enum tevent_trace_point,
585                                         void *private_data);
586
587 /**
588  * Register a callback to be called at certain trace points
589  *
590  * @param[in] ev             Event context
591  * @param[in] cb             Trace callback
592  * @param[in] private_data   Data to be passed to callback
593  *
594  * @note The callback will be called at trace points defined by
595  * tevent_trace_point.  Call with NULL to reset.
596  */
597 void tevent_set_trace_callback(struct tevent_context *ev,
598                                tevent_trace_callback_t cb,
599                                void *private_data);
600
601 /**
602  * Retrieve the current trace callback
603  *
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
607  *
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.
611  */
612 void tevent_get_trace_callback(struct tevent_context *ev,
613                                tevent_trace_callback_t *cb,
614                                void *private_data);
615
616 /**
617  * @}
618  */
619
620 /**
621  * @defgroup tevent_request The tevent request functions.
622  * @ingroup tevent
623  *
624  * A tevent_req represents an asynchronous computation.
625  *
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.
634  *
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.
639  *
640  * Every async computation needs a name (sensibly called "computation"
641  * down from here). From this name quite a few naming conventions are
642  * derived.
643  *
644  * Every computation that requires local state needs a
645  * @code
646  * struct computation_state {
647  *     int local_var;
648  * };
649  * @endcode
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
653  * a state struct.
654  *
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:
661  *
662  * @code
663  * struct tevent_req *computation_send(TALLOC_CTX *mem_ctx,
664  *                                     struct tevent_req *ev,
665  *                                     ... further args);
666  * int computation_recv(struct tevent_req *req, ... further output args);
667  * @endcode
668  *
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
671  * here.
672  *
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
683  *
684  * @code
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);
688  * @endcode
689  *
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
693  * flow.
694  *
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.
699  *
700  * @{
701  */
702
703 /**
704  * An async request moves from TEVENT_REQ_INIT to
705  * TEVENT_REQ_IN_PROGRESS. All other states are valid after a request
706  * has finished.
707  */
708 enum tevent_req_state {
709         /**
710          * We are creating the request
711          */
712         TEVENT_REQ_INIT,
713         /**
714          * We are waiting the request to complete
715          */
716         TEVENT_REQ_IN_PROGRESS,
717         /**
718          * The request is finished successfully
719          */
720         TEVENT_REQ_DONE,
721         /**
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().
725          */
726         TEVENT_REQ_USER_ERROR,
727         /**
728          * Request timed out after the timeout set by tevent_req_set_endtime.
729          */
730         TEVENT_REQ_TIMED_OUT,
731         /**
732          * An internal allocation has failed, or tevent_req_nomem has
733          * been given a NULL pointer as the first argument.
734          */
735         TEVENT_REQ_NO_MEMORY,
736         /**
737          * The request has been received by the caller. No further
738          * action is valid.
739          */
740         TEVENT_REQ_RECEIVED
741 };
742
743 /**
744  * @brief An async request
745  */
746 struct tevent_req;
747
748 /**
749  * @brief A tevent request callback function.
750  *
751  * @param[in]  req      The tevent async request which executed this callback.
752  */
753 typedef void (*tevent_req_fn)(struct tevent_req *req);
754
755 /**
756  * @brief Set an async request callback.
757  *
758  * See the documentation of tevent_req_post() for an example how this
759  * is supposed to be used.
760  *
761  * @param[in]  req      The async request to set the callback.
762  *
763  * @param[in]  fn       The callback function to set.
764  *
765  * @param[in]  pvt      A pointer to private data to pass to the async request
766  *                      callback.
767  */
768 void tevent_req_set_callback(struct tevent_req *req, tevent_req_fn fn, void *pvt);
769
770 #ifdef DOXYGEN
771 /**
772  * @brief Get the private data cast to the given type for a callback from
773  *        a tevent request structure.
774  *
775  * @code
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);
780  * }
781  * @endcode
782  *
783  * @param[in]  req      The structure to get the callback data from.
784  *
785  * @param[in]  type     The type of the private callback data to get.
786  *
787  * @return              The type casted private data set NULL if not set.
788  */
789 void *tevent_req_callback_data(struct tevent_req *req, #type);
790 #else
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)
794 #endif
795
796 #ifdef DOXYGEN
797 /**
798  * @brief Get the private data for a callback from a tevent request structure.
799  *
800  * @param[in]  req      The structure to get the callback data from.
801  *
802  * @param[in]  req      The structure to get the data from.
803  *
804  * @return              The private data or NULL if not set.
805  */
806 void *tevent_req_callback_data_void(struct tevent_req *req);
807 #else
808 #define tevent_req_callback_data_void(_req) \
809         _tevent_req_callback_data(_req)
810 #endif
811
812 #ifdef DOXYGEN
813 /**
814  * @brief Get the private data from a tevent request structure.
815  *
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.
819  *
820  * @param[in]  req      The structure to get the private data from.
821  *
822  * @param[in]  type     The type of the private data
823  *
824  * @return              The private data or NULL if not set.
825  */
826 void *tevent_req_data(struct tevent_req *req, #type);
827 #else
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)
831 #endif
832
833 /**
834  * @brief The print function which can be set for a tevent async request.
835  *
836  * @param[in]  req      The tevent async request.
837  *
838  * @param[in]  ctx      A talloc memory context which can be uses to allocate
839  *                      memory.
840  *
841  * @return              An allocated string buffer to print.
842  *
843  * Example:
844  * @code
845  *   static char *my_print(struct tevent_req *req, TALLOC_CTX *mem_ctx)
846  *   {
847  *     struct my_data *data = tevent_req_data(req, struct my_data);
848  *     char *result;
849  *
850  *     result = tevent_req_default_print(mem_ctx, req);
851  *     if (result == NULL) {
852  *       return NULL;
853  *     }
854  *
855  *     return talloc_asprintf_append_buffer(result, "foo=%d, bar=%d",
856  *       data->foo, data->bar);
857  *   }
858  * @endcode
859  */
860 typedef char *(*tevent_req_print_fn)(struct tevent_req *req, TALLOC_CTX *ctx);
861
862 /**
863  * @brief This function sets a print function for the given request.
864  *
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.
868  *
869  * @param[in]  req      The request to use.
870  *
871  * @param[in]  fn       A pointer to the print function
872  *
873  * @note This function should only be used for debugging.
874  */
875 void tevent_req_set_print_fn(struct tevent_req *req, tevent_req_print_fn fn);
876
877 /**
878  * @brief The default print function for creating debug messages.
879  *
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
882  * to the string.
883  *
884  * @param[in]  req      The request to be printed.
885  *
886  * @param[in]  mem_ctx  The memory context for the result.
887  *
888  * @return              Text representation of request.
889  *
890  */
891 char *tevent_req_default_print(struct tevent_req *req, TALLOC_CTX *mem_ctx);
892
893 /**
894  * @brief Print an tevent_req structure in debug messages.
895  *
896  * This function should be used by callers of the async API.
897  *
898  * @param[in]  mem_ctx  The memory context for the result.
899  *
900  * @param[in] req       The request to be printed.
901  *
902  * @return              Text representation of request.
903  */
904 char *tevent_req_print(TALLOC_CTX *mem_ctx, struct tevent_req *req);
905
906 /**
907  * @brief A typedef for a cancel function for a tevent request.
908  *
909  * @param[in]  req      The tevent request calling this function.
910  *
911  * @return              True if the request could be canceled, false if not.
912  */
913 typedef bool (*tevent_req_cancel_fn)(struct tevent_req *req);
914
915 /**
916  * @brief This function sets a cancel function for the given tevent request.
917  *
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.
921  *
922  * @param[in]  req      The request to use.
923  *
924  * @param[in]  fn       A pointer to the cancel function.
925  */
926 void tevent_req_set_cancel_fn(struct tevent_req *req, tevent_req_cancel_fn fn);
927
928 #ifdef DOXYGEN
929 /**
930  * @brief Try to cancel the given tevent request.
931  *
932  * This function can be used to cancel the given request.
933  *
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().
936  *
937  * @param[in]  req      The request to use.
938  *
939  * @return              This function returns true is the request is cancelable,
940  *                      othererwise false is returned.
941  *
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.
946  */
947 bool tevent_req_cancel(struct tevent_req *req);
948 #else
949 bool _tevent_req_cancel(struct tevent_req *req, const char *location);
950 #define tevent_req_cancel(req) \
951         _tevent_req_cancel(req, __location__)
952 #endif
953
954 /**
955  * @brief A typedef for a cleanup function for a tevent request.
956  *
957  * @param[in]  req       The tevent request calling this function.
958  *
959  * @param[in]  req_state The current tevent_req_state.
960  *
961  */
962 typedef void (*tevent_req_cleanup_fn)(struct tevent_req *req,
963                                       enum tevent_req_state req_state);
964
965 /**
966  * @brief This function sets a cleanup function for the given tevent request.
967  *
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.
972  *
973  * This might be useful if more than one tevent_req belong together
974  * and need to finish both requests at the same time.
975  *
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.
978  *
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.
982  *
983  * @param[in]  req      The request to use.
984  *
985  * @param[in]  fn       A pointer to the cancel function.
986  */
987 void tevent_req_set_cleanup_fn(struct tevent_req *req, tevent_req_cleanup_fn fn);
988
989 #ifdef DOXYGEN
990 /**
991  * @brief Create an async tevent request.
992  *
993  * The new async request will be initialized in state TEVENT_REQ_IN_PROGRESS.
994  *
995  * @code
996  * struct tevent_req *req;
997  * struct computation_state *state;
998  * req = tevent_req_create(mem_ctx, &state, struct computation_state);
999  * @endcode
1000  *
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.
1007  *
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.
1011  *
1012  * @return              A new async request. NULL on error.
1013  */
1014 struct tevent_req *tevent_req_create(TALLOC_CTX *mem_ctx,
1015                                      void **pstate, #type);
1016 #else
1017 struct tevent_req *_tevent_req_create(TALLOC_CTX *mem_ctx,
1018                                       void *pstate,
1019                                       size_t state_size,
1020                                       const char *type,
1021                                       const char *location);
1022
1023 #define tevent_req_create(_mem_ctx, _pstate, _type) \
1024         _tevent_req_create((_mem_ctx), (_pstate), sizeof(_type), \
1025                            #_type, __location__)
1026 #endif
1027
1028 /**
1029  * @brief Set a timeout for an async request.
1030  *
1031  * @param[in]  req      The request to set the timeout for.
1032  *
1033  * @param[in]  ev       The event context to use for the timer.
1034  *
1035  * @param[in]  endtime  The endtime of the request.
1036  *
1037  * @return              True if succeeded, false if not.
1038  */
1039 bool tevent_req_set_endtime(struct tevent_req *req,
1040                             struct tevent_context *ev,
1041                             struct timeval endtime);
1042
1043 /**
1044  * @brief Reset the timer set by tevent_req_set_endtime.
1045  *
1046  * @param[in]  req      The request to reset the timeout for
1047  */
1048 void tevent_req_reset_endtime(struct tevent_req *req);
1049
1050 #ifdef DOXYGEN
1051 /**
1052  * @brief Call the notify callback of the given tevent request manually.
1053  *
1054  * @param[in]  req      The tevent request to call the notify function from.
1055  *
1056  * @see tevent_req_set_callback()
1057  */
1058 void tevent_req_notify_callback(struct tevent_req *req);
1059 #else
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__)
1063 #endif
1064
1065 #ifdef DOXYGEN
1066 /**
1067  * @brief An async request has successfully finished.
1068  *
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
1071  * function.
1072  *
1073  * @param[in]  req       The finished request.
1074  */
1075 void tevent_req_done(struct tevent_req *req);
1076 #else
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__)
1081 #endif
1082
1083 #ifdef DOXYGEN
1084 /**
1085  * @brief An async request has seen an error.
1086  *
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.
1090  *
1091  * If error is 0 the function returns false and does nothing more.
1092  *
1093  * @param[in]  req      The request with an error.
1094  *
1095  * @param[in]  error    The error code.
1096  *
1097  * @return              On success true is returned, false if error is 0.
1098  *
1099  * @code
1100  * int error = first_function();
1101  * if (tevent_req_error(req, error)) {
1102  *      return;
1103  * }
1104  *
1105  * error = second_function();
1106  * if (tevent_req_error(req, error)) {
1107  *      return;
1108  * }
1109  *
1110  * tevent_req_done(req);
1111  * return;
1112  * @endcode
1113  */
1114 bool tevent_req_error(struct tevent_req *req,
1115                       uint64_t error);
1116 #else
1117 bool _tevent_req_error(struct tevent_req *req,
1118                        uint64_t error,
1119                        const char *location);
1120 #define tevent_req_error(req, error) \
1121         _tevent_req_error(req, error, __location__)
1122 #endif
1123
1124 #ifdef DOXYGEN
1125 /**
1126  * @brief Helper function for nomem check.
1127  *
1128  * Convenience helper to easily check alloc failure within a callback
1129  * implementing the next step of an async request.
1130  *
1131  * @param[in]  p        The pointer to be checked.
1132  *
1133  * @param[in]  req      The request being processed.
1134  *
1135  * @code
1136  * p = talloc(mem_ctx, bla);
1137  * if (tevent_req_nomem(p, req)) {
1138  *      return;
1139  * }
1140  * @endcode
1141  */
1142 bool tevent_req_nomem(const void *p,
1143                       struct tevent_req *req);
1144 #else
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__)
1150 #endif
1151
1152 #ifdef DOXYGEN
1153 /**
1154  * @brief Indicate out of memory to a request
1155  *
1156  * @param[in]  req      The request being processed.
1157  */
1158 void tevent_req_oom(struct tevent_req *req);
1159 #else
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__)
1164 #endif
1165
1166 /**
1167  * @brief Finish a request before the caller had the change to set the callback.
1168  *
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.
1175  *
1176  * @code
1177  * struct tevent_req *computation_send(TALLOC_CTX *mem_ctx,
1178  *                                     struct tevent_context *ev)
1179  * {
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) {
1184  *         return NULL;
1185  *     }
1186  *     subreq = subcomputation_send(state, ev);
1187  *     if (tevent_req_nomem(subreq, req)) {
1188  *         return tevent_req_post(req, ev);
1189  *     }
1190  *     tevent_req_set_callback(subreq, computation_done, req);
1191  *     return req;
1192  * }
1193  * @endcode
1194  *
1195  * @param[in]  req      The finished request.
1196  *
1197  * @param[in]  ev       The tevent_context for the immediate event.
1198  *
1199  * @return              The given request will be returned.
1200  */
1201 struct tevent_req *tevent_req_post(struct tevent_req *req,
1202                                    struct tevent_context *ev);
1203
1204 /**
1205  * @brief Finish multiple requests within one function
1206  *
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.
1212  *
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()).
1218  *
1219  * @code
1220  * struct complete_state {
1221  *       struct tevent_context *ev;
1222  *
1223  *       struct tevent_req **reqs;
1224  * };
1225  *
1226  * void complete(struct complete_state *state)
1227  * {
1228  *       size_t i, c = talloc_array_length(state->reqs);
1229  *
1230  *       for (i=0; i < c; i++) {
1231  *            tevent_req_defer_callback(state->reqs[i], state->ev);
1232  *            tevent_req_done(state->reqs[i]);
1233  *       }
1234  * }
1235  * @endcode
1236  *
1237  * @param[in]  req      The finished request.
1238  *
1239  * @param[in]  ev       The tevent_context for the immediate event.
1240  *
1241  * @return              The given request will be returned.
1242  */
1243 void tevent_req_defer_callback(struct tevent_req *req,
1244                                struct tevent_context *ev);
1245
1246 /**
1247  * @brief Check if the given request is still in progress.
1248  *
1249  * It is typically used by sync wrapper functions.
1250  *
1251  * @param[in]  req      The request to poll.
1252  *
1253  * @return              The boolean form of "is in progress".
1254  */
1255 bool tevent_req_is_in_progress(struct tevent_req *req);
1256
1257 /**
1258  * @brief Actively poll for the given request to finish.
1259  *
1260  * This function is typically used by sync wrapper functions.
1261  *
1262  * @param[in]  req      The request to poll.
1263  *
1264  * @param[in]  ev       The tevent_context to be used.
1265  *
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!
1269  *
1270  * @note This should only be used if the given tevent context was created by the
1271  * caller, to avoid event loop nesting.
1272  *
1273  * @code
1274  * req = tstream_writev_queue_send(mem_ctx,
1275  *                                 ev_ctx,
1276  *                                 tstream,
1277  *                                 send_queue,
1278  *                                 iov, 2);
1279  * ok = tevent_req_poll(req, tctx->ev);
1280  * rc = tstream_writev_queue_recv(req, &sys_errno);
1281  * TALLOC_FREE(req);
1282  * @endcode
1283  */
1284 bool tevent_req_poll(struct tevent_req *req,
1285                      struct tevent_context *ev);
1286
1287 /**
1288  * @brief Get the tevent request state and the actual error set by
1289  * tevent_req_error.
1290  *
1291  * @code
1292  * int computation_recv(struct tevent_req *req, uint64_t *perr)
1293  * {
1294  *     enum tevent_req_state state;
1295  *     uint64_t err;
1296  *     if (tevent_req_is_error(req, &state, &err)) {
1297  *         *perr = err;
1298  *         return -1;
1299  *     }
1300  *     return 0;
1301  * }
1302  * @endcode
1303  *
1304  * @param[in]  req      The tevent request to get the error from.
1305  *
1306  * @param[out] state    A pointer to store the tevent request error state.
1307  *
1308  * @param[out] error    A pointer to store the error set by tevent_req_error().
1309  *
1310  * @return              True if the function could set error and state, false
1311  *                      otherwise.
1312  *
1313  * @see tevent_req_error()
1314  */
1315 bool tevent_req_is_error(struct tevent_req *req,
1316                          enum tevent_req_state *state,
1317                          uint64_t *error);
1318
1319 /**
1320  * @brief Use as the last action of a _recv() function.
1321  *
1322  * This function destroys the attached private data.
1323  *
1324  * @param[in]  req      The finished request.
1325  */
1326 void tevent_req_received(struct tevent_req *req);
1327
1328 /**
1329  * @brief Create a tevent subrequest at a given time.
1330  *
1331  * The idea is that always the same syntax for tevent requests.
1332  *
1333  * @param[in]  mem_ctx  The talloc memory context to use.
1334  *
1335  * @param[in]  ev       The event handle to setup the request.
1336  *
1337  * @param[in]  wakeup_time The time to wakeup and execute the request.
1338  *
1339  * @return              The new subrequest, NULL on error.
1340  *
1341  * Example:
1342  * @code
1343  *   static void my_callback_wakeup_done(tevent_req *subreq)
1344  *   {
1345  *     struct tevent_req *req = tevent_req_callback_data(subreq,
1346  *                              struct tevent_req);
1347  *     bool ok;
1348  *
1349  *     ok = tevent_wakeup_recv(subreq);
1350  *     TALLOC_FREE(subreq);
1351  *     if (!ok) {
1352  *         tevent_req_error(req, -1);
1353  *         return;
1354  *     }
1355  *     ...
1356  *   }
1357  * @endcode
1358  *
1359  * @code
1360  *   subreq = tevent_wakeup_send(mem_ctx, ev, wakeup_time);
1361  *   if (tevent_req_nomem(subreq, req)) {
1362  *     return false;
1363  *   }
1364  *   tevent_set_callback(subreq, my_callback_wakeup_done, req);
1365  * @endcode
1366  *
1367  * @see tevent_wakeup_recv()
1368  */
1369 struct tevent_req *tevent_wakeup_send(TALLOC_CTX *mem_ctx,
1370                                       struct tevent_context *ev,
1371                                       struct timeval wakeup_time);
1372
1373 /**
1374  * @brief Check if the wakeup has been correctly executed.
1375  *
1376  * This function needs to be called in the callback function set after calling
1377  * tevent_wakeup_send().
1378  *
1379  * @param[in]  req      The tevent request to check.
1380  *
1381  * @return              True on success, false otherwise.
1382  *
1383  * @see tevent_wakeup_recv()
1384  */
1385 bool tevent_wakeup_recv(struct tevent_req *req);
1386
1387 /* @} */
1388
1389 /**
1390  * @defgroup tevent_helpers The tevent helper functions
1391  * @ingroup tevent
1392  *
1393  * @todo description
1394  *
1395  * @{
1396  */
1397
1398 /**
1399  * @brief Compare two timeval values.
1400  *
1401  * @param[in]  tv1      The first timeval value to compare.
1402  *
1403  * @param[in]  tv2      The second timeval value to compare.
1404  *
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.
1408  */
1409 int tevent_timeval_compare(const struct timeval *tv1,
1410                            const struct timeval *tv2);
1411
1412 /**
1413  * @brief Get a zero timeval value.
1414  *
1415  * @return              A zero timeval value.
1416  */
1417 struct timeval tevent_timeval_zero(void);
1418
1419 /**
1420  * @brief Get a timeval value for the current time.
1421  *
1422  * @return              A timeval value with the current time.
1423  */
1424 struct timeval tevent_timeval_current(void);
1425
1426 /**
1427  * @brief Get a timeval structure with the given values.
1428  *
1429  * @param[in]  secs     The seconds to set.
1430  *
1431  * @param[in]  usecs    The microseconds to set.
1432  *
1433  * @return              A timeval structure with the given values.
1434  */
1435 struct timeval tevent_timeval_set(uint32_t secs, uint32_t usecs);
1436
1437 /**
1438  * @brief Get the difference between two timeval values.
1439  *
1440  * @param[in]  tv1      The first timeval.
1441  *
1442  * @param[in]  tv2      The second timeval.
1443  *
1444  * @return              A timeval structure with the difference between the
1445  *                      first and the second value.
1446  */
1447 struct timeval tevent_timeval_until(const struct timeval *tv1,
1448                                     const struct timeval *tv2);
1449
1450 /**
1451  * @brief Check if a given timeval structure is zero.
1452  *
1453  * @param[in]  tv       The timeval to check if it is zero.
1454  *
1455  * @return              True if it is zero, false otherwise.
1456  */
1457 bool tevent_timeval_is_zero(const struct timeval *tv);
1458
1459 /**
1460  * @brief Add the given amount of time to a timeval structure.
1461  *
1462  * @param[in]  tv        The timeval structure to add the time.
1463  *
1464  * @param[in]  secs      The seconds to add to the timeval.
1465  *
1466  * @param[in]  usecs     The microseconds to add to the timeval.
1467  *
1468  * @return               The timeval structure with the new time.
1469  */
1470 struct timeval tevent_timeval_add(const struct timeval *tv, uint32_t secs,
1471                                   uint32_t usecs);
1472
1473 /**
1474  * @brief Get a timeval in the future with a specified offset from now.
1475  *
1476  * @param[in]  secs     The seconds of the offset from now.
1477  *
1478  * @param[in]  usecs    The microseconds of the offset from now.
1479  *
1480  * @return              A timval with the given offset in the future.
1481  */
1482 struct timeval tevent_timeval_current_ofs(uint32_t secs, uint32_t usecs);
1483
1484 /* @} */
1485
1486
1487 /**
1488  * @defgroup tevent_queue The tevent queue functions
1489  * @ingroup tevent
1490  *
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.
1498  *
1499  * Take a look at @ref tevent_queue_tutorial for more details.
1500  * @{
1501  */
1502
1503 struct tevent_queue;
1504 struct tevent_queue_entry;
1505
1506 #ifdef DOXYGEN
1507 /**
1508  * @brief Create and start a tevent queue.
1509  *
1510  * @param[in]  mem_ctx  The talloc memory context to allocate the queue.
1511  *
1512  * @param[in]  name     The name to use to identify the queue.
1513  *
1514  * @return              An allocated tevent queue on success, NULL on error.
1515  *
1516  * @see tevent_queue_start()
1517  * @see tevent_queue_stop()
1518  */
1519 struct tevent_queue *tevent_queue_create(TALLOC_CTX *mem_ctx,
1520                                          const char *name);
1521 #else
1522 struct tevent_queue *_tevent_queue_create(TALLOC_CTX *mem_ctx,
1523                                           const char *name,
1524                                           const char *location);
1525
1526 #define tevent_queue_create(_mem_ctx, _name) \
1527         _tevent_queue_create((_mem_ctx), (_name), __location__)
1528 #endif
1529
1530 /**
1531  * @brief A callback trigger function run by the queue.
1532  *
1533  * @param[in]  req      The tevent request the trigger function is executed on.
1534  *
1535  * @param[in]  private_data The private data pointer specified by
1536  *                          tevent_queue_add().
1537  *
1538  * @see tevent_queue_add()
1539  * @see tevent_queue_add_entry()
1540  * @see tevent_queue_add_optimize_empty()
1541  */
1542 typedef void (*tevent_queue_trigger_fn_t)(struct tevent_req *req,
1543                                           void *private_data);
1544
1545 /**
1546  * @brief Add a tevent request to the queue.
1547  *
1548  * @param[in]  queue    The queue to add the request.
1549  *
1550  * @param[in]  ev       The event handle to use for the request.
1551  *
1552  * @param[in]  req      The tevent request to add to the queue.
1553  *
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
1557  *                      queue.
1558  *
1559  * @param[in]  private_data The private data passed to the trigger function.
1560  *
1561  * @return              True if the request has been successfully added, false
1562  *                      otherwise.
1563  */
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);
1569
1570 /**
1571  * @brief Add a tevent request to the queue.
1572  *
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().
1576  *
1577  * @param[in]  queue    The queue to add the request.
1578  *
1579  * @param[in]  ev       The event handle to use for the request.
1580  *
1581  * @param[in]  req      The tevent request to add to the queue.
1582  *
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
1586  *                      queue.
1587  *
1588  * @param[in]  private_data The private data passed to the trigger function.
1589  *
1590  * @return              a pointer to the tevent_queue_entry if the request
1591  *                      has been successfully added, NULL otherwise.
1592  *
1593  * @see tevent_queue_add()
1594  * @see tevent_queue_add_optimize_empty()
1595  */
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);
1602
1603 /**
1604  * @brief Add a tevent request to the queue using a possible optimization.
1605  *
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().
1609  *
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.
1613  *
1614  * The request can be removed from the queue by calling talloc_free()
1615  * (or a similar function) on the returned queue entry.
1616  *
1617  * @param[in]  queue    The queue to add the request.
1618  *
1619  * @param[in]  ev       The event handle to use for the request.
1620  *
1621  * @param[in]  req      The tevent request to add to the queue.
1622  *
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
1626  *                      queue.
1627  *
1628  * @param[in]  private_data The private data passed to the trigger function.
1629  *
1630  * @return              a pointer to the tevent_queue_entry if the request
1631  *                      has been successfully added, NULL otherwise.
1632  *
1633  * @see tevent_queue_add()
1634  * @see tevent_queue_add_entry()
1635  */
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);
1642
1643 /**
1644  * @brief Start a tevent queue.
1645  *
1646  * The queue is started by default.
1647  *
1648  * @param[in]  queue    The queue to start.
1649  */
1650 void tevent_queue_start(struct tevent_queue *queue);
1651
1652 /**
1653  * @brief Stop a tevent queue.
1654  *
1655  * The queue is started by default.
1656  *
1657  * @param[in]  queue    The queue to stop.
1658  */
1659 void tevent_queue_stop(struct tevent_queue *queue);
1660
1661 /**
1662  * @brief Get the length of the queue.
1663  *
1664  * @param[in]  queue    The queue to get the length from.
1665  *
1666  * @return              The number of elements.
1667  */
1668 size_t tevent_queue_length(struct tevent_queue *queue);
1669
1670 /**
1671  * @brief Is the tevent queue running.
1672  *
1673  * The queue is started by default.
1674  *
1675  * @param[in]  queue    The queue.
1676  *
1677  * @return              Wether the queue is running or not..
1678  */
1679 bool tevent_queue_running(struct tevent_queue *queue);
1680
1681 /**
1682  * @brief Create a tevent subrequest that waits in a tevent_queue
1683  *
1684  * The idea is that always the same syntax for tevent requests.
1685  *
1686  * @param[in]  mem_ctx  The talloc memory context to use.
1687  *
1688  * @param[in]  ev       The event handle to setup the request.
1689  *
1690  * @param[in]  queue    The queue to wait in.
1691  *
1692  * @return              The new subrequest, NULL on error.
1693  *
1694  * @see tevent_queue_wait_recv()
1695  */
1696 struct tevent_req *tevent_queue_wait_send(TALLOC_CTX *mem_ctx,
1697                                           struct tevent_context *ev,
1698                                           struct tevent_queue *queue);
1699
1700 /**
1701  * @brief Check if we no longer need to wait in the queue.
1702  *
1703  * This function needs to be called in the callback function set after calling
1704  * tevent_queue_wait_send().
1705  *
1706  * @param[in]  req      The tevent request to check.
1707  *
1708  * @return              True on success, false otherwise.
1709  *
1710  * @see tevent_queue_wait_send()
1711  */
1712 bool tevent_queue_wait_recv(struct tevent_req *req);
1713
1714 typedef int (*tevent_nesting_hook)(struct tevent_context *ev,
1715                                    void *private_data,
1716                                    uint32_t level,
1717                                    bool begin,
1718                                    void *stack_ptr,
1719                                    const char *location);
1720
1721 /**
1722  * @brief Create a tevent_thread_proxy for message passing between threads.
1723  *
1724  * The tevent_context must have been allocated on the NULL
1725  * talloc context, and talloc_disable_null_tracking() must
1726  * have been called.
1727  *
1728  * @param[in]  dest_ev_ctx      The tevent_context to receive events.
1729  *
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.
1733  *
1734  * @see tevent_thread_proxy_schedule()
1735  */
1736 struct tevent_thread_proxy *tevent_thread_proxy_create(
1737                 struct tevent_context *dest_ev_ctx);
1738
1739 /**
1740  * @brief Schedule an immediate event on an event context from another thread.
1741  *
1742  * Causes dest_ev_ctx, being run by another thread, to receive an
1743  * immediate event calling the handler with the *pp_private parameter.
1744  *
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.
1748  *
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.
1755  *
1756  * @param[in]  tp               The tevent_thread_proxy to use.
1757  *
1758  * @param[in]  pp_im            Pointer to immediate event pointer.
1759  *
1760  * @param[in]  handler          The function that will be called.
1761  *
1762  * @param[in]  pp_private_data  The talloced memory to transfer.
1763  *
1764  * @see tevent_thread_proxy_create()
1765  */
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);
1770
1771 /*
1772  * @brief Create a context for threaded activation of immediates
1773  *
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.
1777  *
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 talllc_free'ed
1781  * with an active tevent_threaded_context.
1782  *
1783  * If tevent is build without pthread support, this always returns
1784  * NULL with errno=ENOSYS.
1785  *
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.
1789  *
1790  * @see tevent_threaded_schedule_immediate()
1791  *
1792  * @note Available as of tevent 0.9.30
1793  */
1794 struct tevent_threaded_context *tevent_threaded_context_create(
1795         TALLOC_CTX *mem_ctx, struct tevent_context *ev);
1796
1797 #ifdef DOXYGEN
1798 /*
1799  * @brief Activate an immediate from a thread
1800  *
1801  * Activate an immediate from within a thread.
1802  *
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.
1808  *
1809  * tevent_threaded_schedule_immediate is intended as a job completion
1810  * indicator for simple threaded helpers.
1811  *
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.
1818  *
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
1823  *
1824  * @see tevent_threaded_context_create()
1825  *
1826  * @note Available as of tevent 0.9.30
1827  */
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);
1832 #else
1833 void _tevent_threaded_schedule_immediate(struct tevent_threaded_context *tctx,
1834                                          struct tevent_immediate *im,
1835                                          tevent_immediate_handler_t handler,
1836                                          void *private_data,
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__);
1842 #endif
1843
1844 #ifdef TEVENT_DEPRECATED
1845 #ifndef _DEPRECATED_
1846 #ifdef HAVE___ATTRIBUTE__
1847 #define _DEPRECATED_ __attribute__ ((deprecated))
1848 #else
1849 #define _DEPRECATED_
1850 #endif
1851 #endif
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),
1858                        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__)
1862 #endif
1863
1864 int tevent_re_initialise(struct tevent_context *ev);
1865
1866 /* @} */
1867
1868 /**
1869  * @defgroup tevent_ops The tevent operation functions
1870  * @ingroup tevent
1871  *
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.
1875  * @{
1876  */
1877
1878 struct tevent_ops {
1879         /* context init */
1880         int (*context_init)(struct tevent_context *ev);
1881
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,
1887                                     void *private_data,
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);
1894
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,
1900                                           void *private_data,
1901                                           const char *handler_name,
1902                                           const char *location);
1903
1904         /* immediate event functions */
1905         void (*schedule_immediate)(struct tevent_immediate *im,
1906                                    struct tevent_context *ev,
1907                                    tevent_immediate_handler_t handler,
1908                                    void *private_data,
1909                                    const char *handler_name,
1910                                    const char *location);
1911
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,
1917                                             void *private_data,
1918                                             const char *handler_name,
1919                                             const char *location);
1920
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);
1924 };
1925
1926 bool tevent_register_backend(const char *name, const struct tevent_ops *ops);
1927
1928 /* @} */
1929
1930 /**
1931  * @defgroup tevent_compat The tevent compatibility functions
1932  * @ingroup tevent
1933  *
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.
1937  *
1938  * @todo Ignore it?
1939  *
1940  * @{
1941  */
1942
1943 #ifdef TEVENT_COMPAT_DEFINES
1944
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
1950
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
1954
1955 #define event_context_init(mem_ctx) \
1956         tevent_context_init(mem_ctx)
1957
1958 #define event_context_init_byname(mem_ctx, name) \
1959         tevent_context_init_byname(mem_ctx, name)
1960
1961 #define event_backend_list(mem_ctx) \
1962         tevent_backend_list(mem_ctx)
1963
1964 #define event_set_default_backend(backend) \
1965         tevent_set_default_backend(backend)
1966
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)
1969
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)
1972
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)
1975
1976 #define event_loop_once(ev) \
1977         tevent_loop_once(ev)
1978
1979 #define event_loop_wait(ev) \
1980         tevent_loop_wait(ev)
1981
1982 #define event_get_fd_flags(fde) \
1983         tevent_fd_get_flags(fde)
1984
1985 #define event_set_fd_flags(fde, flags) \
1986         tevent_fd_set_flags(fde, flags)
1987
1988 #define EVENT_FD_READ           TEVENT_FD_READ
1989 #define EVENT_FD_WRITE          TEVENT_FD_WRITE
1990
1991 #define EVENT_FD_WRITEABLE(fde) \
1992         TEVENT_FD_WRITEABLE(fde)
1993
1994 #define EVENT_FD_READABLE(fde) \
1995         TEVENT_FD_READABLE(fde)
1996
1997 #define EVENT_FD_NOT_WRITEABLE(fde) \
1998         TEVENT_FD_NOT_WRITEABLE(fde)
1999
2000 #define EVENT_FD_NOT_READABLE(fde) \
2001         TEVENT_FD_NOT_READABLE(fde)
2002
2003 #define ev_debug_level          tevent_debug_level
2004
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
2009
2010 #define ev_set_debug(ev, debug, context) \
2011         tevent_set_debug(ev, debug, context)
2012
2013 #define ev_set_debug_stderr(_ev) tevent_set_debug_stderr(ev)
2014
2015 #endif /* TEVENT_COMPAT_DEFINES */
2016
2017 /* @} */
2018
2019 #endif /* __TEVENT_H__ */