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
  44 /**
  45  * @defgroup tevent The tevent API
  46  *
  47  * The tevent low-level API
  48  *
  49  * This API provides the public interface to manage events in the tevent
  50  * mainloop. Functions are provided for managing low-level events such
  51  * as timer events, fd events and signal handling.
  52  *
  53  * @{
  54  */
  55
  56 /* event handler types */
  57 /**
  58  * Called when a file descriptor monitored by tevent has
  59  * data to be read or written on it.
  60  */
  61 typedef void (*tevent_fd_handler_t)(struct tevent_context *ev,
  62                                     struct tevent_fd *fde,
  63                                     uint16_t flags,
  64                                     void *private_data);
  65
  66 /**
  67  * Called when tevent is ceasing the monitoring of a file descriptor.
  68  */
  69 typedef void (*tevent_fd_close_fn_t)(struct tevent_context *ev,
  70                                      struct tevent_fd *fde,
  71                                      int fd,
  72                                      void *private_data);
  73
  74 /**
  75  * Called when a tevent timer has fired.
  76  */
  77 typedef void (*tevent_timer_handler_t)(struct tevent_context *ev,
  78                                        struct tevent_timer *te,
  79                                        struct timeval current_time,
  80                                        void *private_data);
  81
  82 /**
  83  * Called when a tevent immediate event is invoked.
  84  */
  85 typedef void (*tevent_immediate_handler_t)(struct tevent_context *ctx,
  86                                            struct tevent_immediate *im,
  87                                            void *private_data);
  88
  89 /**
  90  * Called after tevent detects the specified signal.
  91  */
  92 typedef void (*tevent_signal_handler_t)(struct tevent_context *ev,
  93                                         struct tevent_signal *se,
  94                                         int signum,
  95                                         int count,
  96                                         void *siginfo,
  97                                         void *private_data);
  98
  99 /**
 100  * @brief Create a event_context structure.
 101  *
 102  * This must be the first events call, and all subsequent calls pass this
 103  * event_context as the first element. Event handlers also receive this as
 104  * their first argument.
 105  *
 106  * @param[in]  mem_ctx  The memory context to use.
 107  *
 108  * @return              An allocated tevent context, NULL on error.
 109  *
 110  * @see tevent_context_init()
 111  */
 112 struct tevent_context *tevent_context_init(TALLOC_CTX *mem_ctx);
 113
 114 /**
 115  * @brief Create a event_context structure and select a specific backend.
 116  *
 117  * This must be the first events call, and all subsequent calls pass this
 118  * event_context as the first element. Event handlers also receive this as
 119  * their first argument.
 120  *
 121  * @param[in]  mem_ctx  The memory context to use.
 122  *
 123  * @param[in]  name     The name of the backend to use.
 124  *
 125  * @return              An allocated tevent context, NULL on error.
 126  */
 127 struct tevent_context *tevent_context_init_byname(TALLOC_CTX *mem_ctx, const char *name);
 128
 129 /**
 130  * @brief Create a custom event context
 131  *
 132  * @param[in]  mem_ctx  The memory context to use.
 133  * @param[in]  ops      The function pointer table of the backend.
 134  * @param[in]  additional_data  The additional/private data to this instance
 135  *
 136  * @return              An allocated tevent context, NULL on error.
 137  *
 138  */
 139 struct tevent_context *tevent_context_init_ops(TALLOC_CTX *mem_ctx,
 140                                                const struct tevent_ops *ops,
 141                                                void *additional_data);
 142
 143 /**
 144  * @brief List available backends.
 145  *
 146  * @param[in]  mem_ctx  The memory context to use.
 147  *
 148  * @return              A string vector with a terminating NULL element, NULL
 149  *                      on error.
 150  */
 151 const char **tevent_backend_list(TALLOC_CTX *mem_ctx);
 152
 153 /**
 154  * @brief Set the default tevent backend.
 155  *
 156  * @param[in]  backend  The name of the backend to set.
 157  */
 158 void tevent_set_default_backend(const char *backend);
 159
 160 #ifdef DOXYGEN
 161 /**
 162  * @brief Add a file descriptor based event.
 163  *
 164  * @param[in]  ev       The event context to work on.
 165  *
 166  * @param[in]  mem_ctx  The talloc memory context to use.
 167  *
 168  * @param[in]  fd       The file descriptor to base the event on.
 169  *
 170  * @param[in]  flags    #TEVENT_FD_READ or #TEVENT_FD_WRITE
 171  *
 172  * @param[in]  handler  The callback handler for the event.
 173  *
 174  * @param[in]  private_data  The private data passed to the callback handler.
 175  *
 176  * @return              The file descriptor based event, NULL on error.
 177  *
 178  * @note To cancel the monitoring of a file descriptor, call talloc_free()
 179  * on the object returned by this function.
 180  *
 181  * @note The caller should avoid closing the file descriptor before
 182  * calling talloc_free()! Otherwise the behaviour is undefined which
 183  * might result in crashes. See https://bugzilla.samba.org/show_bug.cgi?id=11141
 184  * for an example.
 185  */
 186 struct tevent_fd *tevent_add_fd(struct tevent_context *ev,
 187                                 TALLOC_CTX *mem_ctx,
 188                                 int fd,
 189                                 uint16_t flags,
 190                                 tevent_fd_handler_t handler,
 191                                 void *private_data);
 192 #else
 193 struct tevent_fd *_tevent_add_fd(struct tevent_context *ev,
 194                                  TALLOC_CTX *mem_ctx,
 195                                  int fd,
 196                                  uint16_t flags,
 197                                  tevent_fd_handler_t handler,
 198                                  void *private_data,
 199                                  const char *handler_name,
 200                                  const char *location);
 201 #define tevent_add_fd(ev, mem_ctx, fd, flags, handler, private_data) \
 202         _tevent_add_fd(ev, mem_ctx, fd, flags, handler, private_data, \
 203                        #handler, __location__)
 204 #endif
 205
 206 #ifdef DOXYGEN
 207 /**
 208  * @brief Add a timed event
 209  *
 210  * @param[in]  ev       The event context to work on.
 211  *
 212  * @param[in]  mem_ctx  The talloc memory context to use.
 213  *
 214  * @param[in]  next_event  Timeval specifying the absolute time to fire this
 215  * event. This is not an offset.
 216  *
 217  * @param[in]  handler  The callback handler for the event.
 218  *
 219  * @param[in]  private_data  The private data passed to the callback handler.
 220  *
 221  * @return The newly-created timer event, or NULL on error.
 222  *
 223  * @note To cancel a timer event before it fires, call talloc_free() on the
 224  * event returned from this function. This event is automatically
 225  * talloc_free()-ed after its event handler files, if it hasn't been freed yet.
 226  *
 227  * @note Unlike some mainloops, tevent timers are one-time events. To set up
 228  * a recurring event, it is necessary to call tevent_add_timer() again during
 229  * the handler processing.
 230  *
 231  * @note Due to the internal mainloop processing, a timer set to run
 232  * immediately will do so after any other pending timers fire, but before
 233  * any further file descriptor or signal handling events fire. Callers should
 234  * not rely on this behavior!
 235  */
 236 struct tevent_timer *tevent_add_timer(struct tevent_context *ev,
 237                                       TALLOC_CTX *mem_ctx,
 238                                       struct timeval next_event,
 239                                       tevent_timer_handler_t handler,
 240                                       void *private_data);
 241 #else
 242 struct tevent_timer *_tevent_add_timer(struct tevent_context *ev,
 243                                        TALLOC_CTX *mem_ctx,
 244                                        struct timeval next_event,
 245                                        tevent_timer_handler_t handler,
 246                                        void *private_data,
 247                                        const char *handler_name,
 248                                        const char *location);
 249 #define tevent_add_timer(ev, mem_ctx, next_event, handler, private_data) \
 250         _tevent_add_timer(ev, mem_ctx, next_event, handler, private_data, \
 251                           #handler, __location__)
 252 #endif
 253
 254 #ifdef DOXYGEN
 255 /**
 256  * Initialize an immediate event object
 257  *
 258  * This object can be used to trigger an event to occur immediately after
 259  * returning from the current event (before any other event occurs)
 260  *
 261  * @param[in] mem_ctx  The talloc memory context to use as the parent
 262  *
 263  * @return An empty tevent_immediate object. Use tevent_schedule_immediate
 264  * to populate and use it.
 265  *
 266  * @note Available as of tevent 0.9.8
 267  */
 268 struct tevent_immediate *tevent_create_immediate(TALLOC_CTX *mem_ctx);
 269 #else
 270 struct tevent_immediate *_tevent_create_immediate(TALLOC_CTX *mem_ctx,
 271                                                   const char *location);
 272 #define tevent_create_immediate(mem_ctx) \
 273         _tevent_create_immediate(mem_ctx, __location__)
 274 #endif
 275
 276 #ifdef DOXYGEN
 277
 278 /**
 279  * Schedule an event for immediate execution. This event will occur
 280  * immediately after returning from the current event (before any other
 281  * event occurs)
 282  *
 283  * @param[in] im       The tevent_immediate object to populate and use
 284  * @param[in] ctx      The tevent_context to run this event
 285  * @param[in] handler  The event handler to run when this event fires
 286  * @param[in] private_data  Data to pass to the event handler
 287  */
 288 void tevent_schedule_immediate(struct tevent_immediate *im,
 289                 struct tevent_context *ctx,
 290                 tevent_immediate_handler_t handler,
 291                 void *private_data);
 292 #else
 293 void _tevent_schedule_immediate(struct tevent_immediate *im,
 294                                 struct tevent_context *ctx,
 295                                 tevent_immediate_handler_t handler,
 296                                 void *private_data,
 297                                 const char *handler_name,
 298                                 const char *location);
 299 #define tevent_schedule_immediate(im, ctx, handler, private_data) \
 300         _tevent_schedule_immediate(im, ctx, handler, private_data, \
 301                                    #handler, __location__);
 302 #endif
 303
 304 #ifdef DOXYGEN
 305 /**
 306  * @brief Add a tevent signal handler
 307  *
 308  * tevent_add_signal() creates a new event for handling a signal the next
 309  * time through the mainloop. It implements a very simple traditional signal
 310  * handler whose only purpose is to add the handler event into the mainloop.
 311  *
 312  * @param[in]  ev       The event context to work on.
 313  *
 314  * @param[in]  mem_ctx  The talloc memory context to use.
 315  *
 316  * @param[in]  signum   The signal to trap
 317  *
 318  * @param[in]  handler  The callback handler for the signal.
 319  *
 320  * @param[in]  sa_flags sigaction flags for this signal handler.
 321  *
 322  * @param[in]  private_data  The private data passed to the callback handler.
 323  *
 324  * @return The newly-created signal handler event, or NULL on error.
 325  *
 326  * @note To cancel a signal handler, call talloc_free() on the event returned
 327  * from this function.
 328  *
 329  * @see tevent_num_signals, tevent_sa_info_queue_count
 330  */
 331 struct tevent_signal *tevent_add_signal(struct tevent_context *ev,
 332                      TALLOC_CTX *mem_ctx,
 333                      int signum,
 334                      int sa_flags,
 335                      tevent_signal_handler_t handler,
 336                      void *private_data);
 337 #else
 338 struct tevent_signal *_tevent_add_signal(struct tevent_context *ev,
 339                                          TALLOC_CTX *mem_ctx,
 340                                          int signum,
 341                                          int sa_flags,
 342                                          tevent_signal_handler_t handler,
 343                                          void *private_data,
 344                                          const char *handler_name,
 345                                          const char *location);
 346 #define tevent_add_signal(ev, mem_ctx, signum, sa_flags, handler, private_data) \
 347         _tevent_add_signal(ev, mem_ctx, signum, sa_flags, handler, private_data, \
 348                            #handler, __location__)
 349 #endif
 350
 351 /**
 352  * @brief the number of supported signals
 353  *
 354  * This returns value of the configure time TEVENT_NUM_SIGNALS constant.
 355  *
 356  * The 'signum' argument of tevent_add_signal() must be less than
 357  * TEVENT_NUM_SIGNALS.
 358  *
 359  * @see tevent_add_signal
 360  */
 361 size_t tevent_num_signals(void);
 362
 363 /**
 364  * @brief the number of pending realtime signals
 365  *
 366  * This returns value of TEVENT_SA_INFO_QUEUE_COUNT.
 367  *
 368  * The tevent internals remember the last TEVENT_SA_INFO_QUEUE_COUNT
 369  * siginfo_t structures for SA_SIGINFO signals. If the system generates
 370  * more some signals get lost.
 371  *
 372  * @see tevent_add_signal
 373  */
 374 size_t tevent_sa_info_queue_count(void);
 375
 376 #ifdef DOXYGEN
 377 /**
 378  * @brief Pass a single time through the mainloop
 379  *
 380  * This will process any appropriate signal, immediate, fd and timer events
 381  *
 382  * @param[in]  ev The event context to process
 383  *
 384  * @return Zero on success, nonzero if an internal error occurred
 385  */
 386 int tevent_loop_once(struct tevent_context *ev);
 387 #else
 388 int _tevent_loop_once(struct tevent_context *ev, const char *location);
 389 #define tevent_loop_once(ev) \
 390         _tevent_loop_once(ev, __location__)
 391 #endif
 392
 393 #ifdef DOXYGEN
 394 /**
 395  * @brief Run the mainloop
 396  *
 397  * The mainloop will run until there are no events remaining to be processed
 398  *
 399  * @param[in]  ev The event context to process
 400  *
 401  * @return Zero if all events have been processed. Nonzero if an internal
 402  * error occurred.
 403  */
 404 int tevent_loop_wait(struct tevent_context *ev);
 405 #else
 406 int _tevent_loop_wait(struct tevent_context *ev, const char *location);
 407 #define tevent_loop_wait(ev) \
 408         _tevent_loop_wait(ev, __location__)
 409 #endif
 410
 411
 412 /**
 413  * Assign a function to run when a tevent_fd is freed
 414  *
 415  * This function is a destructor for the tevent_fd. It does not automatically
 416  * close the file descriptor. If this is the desired behavior, then it must be
 417  * performed by the close_fn.
 418  *
 419  * @param[in] fde       File descriptor event on which to set the destructor
 420  * @param[in] close_fn  Destructor to execute when fde is freed
 421  */
 422 void tevent_fd_set_close_fn(struct tevent_fd *fde,
 423                             tevent_fd_close_fn_t close_fn);
 424
 425 /**
 426  * Automatically close the file descriptor when the tevent_fd is freed
 427  *
 428  * This function calls close(fd) internally.
 429  *
 430  * @param[in] fde  File descriptor event to auto-close
 431  */
 432 void tevent_fd_set_auto_close(struct tevent_fd *fde);
 433
 434 /**
 435  * Return the flags set on this file descriptor event
 436  *
 437  * @param[in] fde  File descriptor event to query
 438  *
 439  * @return The flags set on the event. See #TEVENT_FD_READ and
 440  * #TEVENT_FD_WRITE
 441  */
 442 uint16_t tevent_fd_get_flags(struct tevent_fd *fde);
 443
 444 /**
 445  * Set flags on a file descriptor event
 446  *
 447  * @param[in] fde    File descriptor event to set
 448  * @param[in] flags  Flags to set on the event. See #TEVENT_FD_READ and
 449  * #TEVENT_FD_WRITE
 450  */
 451 void tevent_fd_set_flags(struct tevent_fd *fde, uint16_t flags);
 452
 453 /**
 454  * Query whether tevent supports signal handling
 455  *
 456  * @param[in] ev  An initialized tevent context
 457  *
 458  * @return True if this platform and tevent context support signal handling
 459  */
 460 bool tevent_signal_support(struct tevent_context *ev);
 461
 462 void tevent_set_abort_fn(void (*abort_fn)(const char *reason));
 463
 464 /* bits for file descriptor event flags */
 465
 466 /**
 467  * Monitor a file descriptor for write availability
 468  */
 469 #define TEVENT_FD_READ 1
 470 /**
 471  * Monitor a file descriptor for data to be read
 472  */
 473 #define TEVENT_FD_WRITE 2
 474
 475 /**
 476  * Convenience function for declaring a tevent_fd writable
 477  */
 478 #define TEVENT_FD_WRITEABLE(fde) \
 479         tevent_fd_set_flags(fde, tevent_fd_get_flags(fde) | TEVENT_FD_WRITE)
 480
 481 /**
 482  * Convenience function for declaring a tevent_fd readable
 483  */
 484 #define TEVENT_FD_READABLE(fde) \
 485         tevent_fd_set_flags(fde, tevent_fd_get_flags(fde) | TEVENT_FD_READ)
 486
 487 /**
 488  * Convenience function for declaring a tevent_fd non-writable
 489  */
 490 #define TEVENT_FD_NOT_WRITEABLE(fde) \
 491         tevent_fd_set_flags(fde, tevent_fd_get_flags(fde) & ~TEVENT_FD_WRITE)
 492
 493 /**
 494  * Convenience function for declaring a tevent_fd non-readable
 495  */
 496 #define TEVENT_FD_NOT_READABLE(fde) \
 497         tevent_fd_set_flags(fde, tevent_fd_get_flags(fde) & ~TEVENT_FD_READ)
 498
 499 /**
 500  * Debug level of tevent
 501  */
 502 enum tevent_debug_level {
 503         TEVENT_DEBUG_FATAL,
 504         TEVENT_DEBUG_ERROR,
 505         TEVENT_DEBUG_WARNING,
 506         TEVENT_DEBUG_TRACE
 507 };
 508
 509 /**
 510  * @brief The tevent debug callbac.
 511  *
 512  * @param[in]  context  The memory context to use.
 513  *
 514  * @param[in]  level    The debug level.
 515  *
 516  * @param[in]  fmt      The format string.
 517  *
 518  * @param[in]  ap       The arguments for the format string.
 519  */
 520 typedef void (*tevent_debug_fn)(void *context,
 521                                 enum tevent_debug_level level,
 522                                 const char *fmt,
 523                                 va_list ap) PRINTF_ATTRIBUTE(3,0);
 524
 525 /**
 526  * Set destination for tevent debug messages
 527  *
 528  * @param[in] ev        Event context to debug
 529  * @param[in] debug     Function to handle output printing
 530  * @param[in] context   The context to pass to the debug function.
 531  *
 532  * @return Always returns 0 as of version 0.9.8
 533  *
 534  * @note Default is to emit no debug messages
 535  */
 536 int tevent_set_debug(struct tevent_context *ev,
 537                      tevent_debug_fn debug,
 538                      void *context);
 539
 540 /**
 541  * Designate stderr for debug message output
 542  *
 543  * @param[in] ev     Event context to debug
 544  *
 545  * @note This function will only output TEVENT_DEBUG_FATAL, TEVENT_DEBUG_ERROR
 546  * and TEVENT_DEBUG_WARNING messages. For TEVENT_DEBUG_TRACE, please define a
 547  * function for tevent_set_debug()
 548  */
 549 int tevent_set_debug_stderr(struct tevent_context *ev);
 550
 551 enum tevent_trace_point {
 552         /**
 553          * Corresponds to a trace point just before waiting
 554          */
 555         TEVENT_TRACE_BEFORE_WAIT,
 556         /**
 557          * Corresponds to a trace point just after waiting
 558          */
 559         TEVENT_TRACE_AFTER_WAIT,
 560 #define TEVENT_HAS_LOOP_ONCE_TRACE_POINTS 1
 561         /**
 562          * Corresponds to a trace point just before calling
 563          * the loop_once() backend function.
 564          */
 565         TEVENT_TRACE_BEFORE_LOOP_ONCE,
 566         /**
 567          * Corresponds to a trace point right after the
 568          * loop_once() backend function has returned.
 569          */
 570         TEVENT_TRACE_AFTER_LOOP_ONCE,
 571 };
 572
 573 typedef void (*tevent_trace_callback_t)(enum tevent_trace_point,
 574                                         void *private_data);
 575
 576 /**
 577  * Register a callback to be called at certain trace points
 578  *
 579  * @param[in] ev             Event context
 580  * @param[in] cb             Trace callback
 581  * @param[in] private_data   Data to be passed to callback
 582  *
 583  * @note The callback will be called at trace points defined by
 584  * tevent_trace_point.  Call with NULL to reset.
 585  */
 586 void tevent_set_trace_callback(struct tevent_context *ev,
 587                                tevent_trace_callback_t cb,
 588                                void *private_data);
 589
 590 /**
 591  * Retrieve the current trace callback
 592  *
 593  * @param[in] ev             Event context
 594  * @param[out] cb            Registered trace callback
 595  * @param[out] private_data  Registered data to be passed to callback
 596  *
 597  * @note This can be used to allow one component that wants to
 598  * register a callback to respect the callback that another component
 599  * has already registered.
 600  */
 601 void tevent_get_trace_callback(struct tevent_context *ev,
 602                                tevent_trace_callback_t *cb,
 603                                void *private_data);
 604
 605 /**
 606  * @}
 607  */
 608
 609 /**
 610  * @defgroup tevent_request The tevent request functions.
 611  * @ingroup tevent
 612  *
 613  * A tevent_req represents an asynchronous computation.
 614  *
 615  * The tevent_req group of API calls is the recommended way of
 616  * programming async computations within tevent. In particular the
 617  * file descriptor (tevent_add_fd) and timer (tevent_add_timed) events
 618  * are considered too low-level to be used in larger computations. To
 619  * read and write from and to sockets, Samba provides two calls on top
 620  * of tevent_add_fd: tstream_read_packet_send/recv and tstream_writev_send/recv.
 621  * These requests are much easier to compose than the low-level event
 622  * handlers called from tevent_add_fd.
 623  *
 624  * A lot of the simplicity tevent_req has brought to the notoriously
 625  * hairy async programming came via a set of conventions that every
 626  * async computation programmed should follow. One central piece of
 627  * these conventions is the naming of routines and variables.
 628  *
 629  * Every async computation needs a name (sensibly called "computation"
 630  * down from here). From this name quite a few naming conventions are
 631  * derived.
 632  *
 633  * Every computation that requires local state needs a
 634  * @code
 635  * struct computation_state {
 636  *     int local_var;
 637  * };
 638  * @endcode
 639  * Even if no local variables are required, such a state struct should
 640  * be created containing a dummy variable. Quite a few helper
 641  * functions and macros (for example tevent_req_create()) assume such
 642  * a state struct.
 643  *
 644  * An async computation is started by a computation_send
 645  * function. When it is finished, its result can be received by a
 646  * computation_recv function. For an example how to set up an async
 647  * computation, see the code example in the documentation for
 648  * tevent_req_create() and tevent_req_post(). The prototypes for _send
 649  * and _recv functions should follow some conventions:
 650  *
 651  * @code
 652  * struct tevent_req *computation_send(TALLOC_CTX *mem_ctx,
 653  *                                     struct tevent_req *ev,
 654  *                                     ... further args);
 655  * int computation_recv(struct tevent_req *req, ... further output args);
 656  * @endcode
 657  *
 658  * The "int" result of computation_recv() depends on the result the
 659  * sync version of the function would have, "int" is just an example
 660  * here.
 661  *
 662  * Another important piece of the conventions is that the program flow
 663  * is interrupted as little as possible. Because a blocking
 664  * sub-computation requires that the flow needs to continue in a
 665  * separate function that is the logical sequel of some computation,
 666  * it should lexically follow sending off the blocking
 667  * sub-computation. Setting the callback function via
 668  * tevent_req_set_callback() requires referencing a function lexically
 669  * below the call to tevent_req_set_callback(), forward declarations
 670  * are required. A lot of the async computations thus begin with a
 671  * sequence of declarations such as
 672  *
 673  * @code
 674  * static void computation_step1_done(struct tevent_req *subreq);
 675  * static void computation_step2_done(struct tevent_req *subreq);
 676  * static void computation_step3_done(struct tevent_req *subreq);
 677  * @endcode
 678  *
 679  * It really helps readability a lot to do these forward declarations,
 680  * because the lexically sequential program flow makes the async
 681  * computations almost as clear to read as a normal, sync program
 682  * flow.
 683  *
 684  * It is up to the user of the async computation to talloc_free it
 685  * after it has finished. If an async computation should be aborted,
 686  * the tevent_req structure can be talloc_free'ed. After it has
 687  * finished, it should talloc_free'ed by the API user.
 688  *
 689  * @{
 690  */
 691
 692 /**
 693  * An async request moves from TEVENT_REQ_INIT to
 694  * TEVENT_REQ_IN_PROGRESS. All other states are valid after a request
 695  * has finished.
 696  */
 697 enum tevent_req_state {
 698         /**
 699          * We are creating the request
 700          */
 701         TEVENT_REQ_INIT,
 702         /**
 703          * We are waiting the request to complete
 704          */
 705         TEVENT_REQ_IN_PROGRESS,
 706         /**
 707          * The request is finished successfully
 708          */
 709         TEVENT_REQ_DONE,
 710         /**
 711          * A user error has occurred. The user error has been
 712          * indicated by tevent_req_error(), it can be retrieved via
 713          * tevent_req_is_error().
 714          */
 715         TEVENT_REQ_USER_ERROR,
 716         /**
 717          * Request timed out after the timeout set by tevent_req_set_endtime.
 718          */
 719         TEVENT_REQ_TIMED_OUT,
 720         /**
 721          * An internal allocation has failed, or tevent_req_nomem has
 722          * been given a NULL pointer as the first argument.
 723          */
 724         TEVENT_REQ_NO_MEMORY,
 725         /**
 726          * The request has been received by the caller. No further
 727          * action is valid.
 728          */
 729         TEVENT_REQ_RECEIVED
 730 };
 731
 732 /**
 733  * @brief An async request
 734  */
 735 struct tevent_req;
 736
 737 /**
 738  * @brief A tevent request callback function.
 739  *
 740  * @param[in]  req      The tevent async request which executed this callback.
 741  */
 742 typedef void (*tevent_req_fn)(struct tevent_req *req);
 743
 744 /**
 745  * @brief Set an async request callback.
 746  *
 747  * See the documentation of tevent_req_post() for an example how this
 748  * is supposed to be used.
 749  *
 750  * @param[in]  req      The async request to set the callback.
 751  *
 752  * @param[in]  fn       The callback function to set.
 753  *
 754  * @param[in]  pvt      A pointer to private data to pass to the async request
 755  *                      callback.
 756  */
 757 void tevent_req_set_callback(struct tevent_req *req, tevent_req_fn fn, void *pvt);
 758
 759 #ifdef DOXYGEN
 760 /**
 761  * @brief Get the private data cast to the given type for a callback from
 762  *        a tevent request structure.
 763  *
 764  * @code
 765  * static void computation_done(struct tevent_req *subreq) {
 766  *     struct tevent_req *req = tevent_req_callback_data(subreq, struct tevent_req);
 767  *     struct computation_state *state = tevent_req_data(req, struct computation_state);
 768  *     .... more things, eventually maybe call tevent_req_done(req);
 769  * }
 770  * @endcode
 771  *
 772  * @param[in]  req      The structure to get the callback data from.
 773  *
 774  * @param[in]  type     The type of the private callback data to get.
 775  *
 776  * @return              The type casted private data set NULL if not set.
 777  */
 778 void *tevent_req_callback_data(struct tevent_req *req, #type);
 779 #else
 780 void *_tevent_req_callback_data(struct tevent_req *req);
 781 #define tevent_req_callback_data(_req, _type) \
 782         talloc_get_type_abort(_tevent_req_callback_data(_req), _type)
 783 #endif
 784
 785 #ifdef DOXYGEN
 786 /**
 787  * @brief Get the private data for a callback from a tevent request structure.
 788  *
 789  * @param[in]  req      The structure to get the callback data from.
 790  *
 791  * @param[in]  req      The structure to get the data from.
 792  *
 793  * @return              The private data or NULL if not set.
 794  */
 795 void *tevent_req_callback_data_void(struct tevent_req *req);
 796 #else
 797 #define tevent_req_callback_data_void(_req) \
 798         _tevent_req_callback_data(_req)
 799 #endif
 800
 801 #ifdef DOXYGEN
 802 /**
 803  * @brief Get the private data from a tevent request structure.
 804  *
 805  * When the tevent_req has been created by tevent_req_create, the
 806  * result of tevent_req_data() is the state variable created by
 807  * tevent_req_create() as a child of the req.
 808  *
 809  * @param[in]  req      The structure to get the private data from.
 810  *
 811  * @param[in]  type     The type of the private data
 812  *
 813  * @return              The private data or NULL if not set.
 814  */
 815 void *tevent_req_data(struct tevent_req *req, #type);
 816 #else
 817 void *_tevent_req_data(struct tevent_req *req);
 818 #define tevent_req_data(_req, _type) \
 819         talloc_get_type_abort(_tevent_req_data(_req), _type)
 820 #endif
 821
 822 /**
 823  * @brief The print function which can be set for a tevent async request.
 824  *
 825  * @param[in]  req      The tevent async request.
 826  *
 827  * @param[in]  ctx      A talloc memory context which can be uses to allocate
 828  *                      memory.
 829  *
 830  * @return              An allocated string buffer to print.
 831  *
 832  * Example:
 833  * @code
 834  *   static char *my_print(struct tevent_req *req, TALLOC_CTX *mem_ctx)
 835  *   {
 836  *     struct my_data *data = tevent_req_data(req, struct my_data);
 837  *     char *result;
 838  *
 839  *     result = tevent_req_default_print(mem_ctx, req);
 840  *     if (result == NULL) {
 841  *       return NULL;
 842  *     }
 843  *
 844  *     return talloc_asprintf_append_buffer(result, "foo=%d, bar=%d",
 845  *       data->foo, data->bar);
 846  *   }
 847  * @endcode
 848  */
 849 typedef char *(*tevent_req_print_fn)(struct tevent_req *req, TALLOC_CTX *ctx);
 850
 851 /**
 852  * @brief This function sets a print function for the given request.
 853  *
 854  * This function can be used to setup a print function for the given request.
 855  * This will be triggered if the tevent_req_print() function was
 856  * called on the given request.
 857  *
 858  * @param[in]  req      The request to use.
 859  *
 860  * @param[in]  fn       A pointer to the print function
 861  *
 862  * @note This function should only be used for debugging.
 863  */
 864 void tevent_req_set_print_fn(struct tevent_req *req, tevent_req_print_fn fn);
 865
 866 /**
 867  * @brief The default print function for creating debug messages.
 868  *
 869  * The function should not be used by users of the async API,
 870  * but custom print function can use it and append custom text
 871  * to the string.
 872  *
 873  * @param[in]  req      The request to be printed.
 874  *
 875  * @param[in]  mem_ctx  The memory context for the result.
 876  *
 877  * @return              Text representation of request.
 878  *
 879  */
 880 char *tevent_req_default_print(struct tevent_req *req, TALLOC_CTX *mem_ctx);
 881
 882 /**
 883  * @brief Print an tevent_req structure in debug messages.
 884  *
 885  * This function should be used by callers of the async API.
 886  *
 887  * @param[in]  mem_ctx  The memory context for the result.
 888  *
 889  * @param[in] req       The request to be printed.
 890  *
 891  * @return              Text representation of request.
 892  */
 893 char *tevent_req_print(TALLOC_CTX *mem_ctx, struct tevent_req *req);
 894
 895 /**
 896  * @brief A typedef for a cancel function for a tevent request.
 897  *
 898  * @param[in]  req      The tevent request calling this function.
 899  *
 900  * @return              True if the request could be canceled, false if not.
 901  */
 902 typedef bool (*tevent_req_cancel_fn)(struct tevent_req *req);
 903
 904 /**
 905  * @brief This function sets a cancel function for the given tevent request.
 906  *
 907  * This function can be used to setup a cancel function for the given request.
 908  * This will be triggered if the tevent_req_cancel() function was
 909  * called on the given request.
 910  *
 911  * @param[in]  req      The request to use.
 912  *
 913  * @param[in]  fn       A pointer to the cancel function.
 914  */
 915 void tevent_req_set_cancel_fn(struct tevent_req *req, tevent_req_cancel_fn fn);
 916
 917 #ifdef DOXYGEN
 918 /**
 919  * @brief Try to cancel the given tevent request.
 920  *
 921  * This function can be used to cancel the given request.
 922  *
 923  * It is only possible to cancel a request when the implementation
 924  * has registered a cancel function via the tevent_req_set_cancel_fn().
 925  *
 926  * @param[in]  req      The request to use.
 927  *
 928  * @return              This function returns true is the request is cancelable,
 929  *                      othererwise false is returned.
 930  *
 931  * @note Even if the function returns true, the caller need to wait
 932  *       for the function to complete normally.
 933  *       Only the _recv() function of the given request indicates
 934  *       if the request was really canceled.
 935  */
 936 bool tevent_req_cancel(struct tevent_req *req);
 937 #else
 938 bool _tevent_req_cancel(struct tevent_req *req, const char *location);
 939 #define tevent_req_cancel(req) \
 940         _tevent_req_cancel(req, __location__)
 941 #endif
 942
 943 /**
 944  * @brief A typedef for a cleanup function for a tevent request.
 945  *
 946  * @param[in]  req       The tevent request calling this function.
 947  *
 948  * @param[in]  req_state The current tevent_req_state.
 949  *
 950  */
 951 typedef void (*tevent_req_cleanup_fn)(struct tevent_req *req,
 952                                       enum tevent_req_state req_state);
 953
 954 /**
 955  * @brief This function sets a cleanup function for the given tevent request.
 956  *
 957  * This function can be used to setup a cleanup function for the given request.
 958  * This will be triggered when the tevent_req_done() or tevent_req_error()
 959  * function was called, before notifying the callers callback function,
 960  * and also before scheduling the deferred trigger.
 961  *
 962  * This might be useful if more than one tevent_req belong together
 963  * and need to finish both requests at the same time.
 964  *
 965  * The cleanup function is able to call tevent_req_done() or tevent_req_error()
 966  * recursively, the cleanup function is only triggered the first time.
 967  *
 968  * The cleanup function is also called by tevent_req_received()
 969  * (possibly triggered from tevent_req_destructor()) before destroying
 970  * the private data of the tevent_req.
 971  *
 972  * @param[in]  req      The request to use.
 973  *
 974  * @param[in]  fn       A pointer to the cancel function.
 975  */
 976 void tevent_req_set_cleanup_fn(struct tevent_req *req, tevent_req_cleanup_fn fn);
 977
 978 #ifdef DOXYGEN
 979 /**
 980  * @brief Create an async tevent request.
 981  *
 982  * The new async request will be initialized in state TEVENT_REQ_IN_PROGRESS.
 983  *
 984  * @code
 985  * struct tevent_req *req;
 986  * struct computation_state *state;
 987  * req = tevent_req_create(mem_ctx, &state, struct computation_state);
 988  * @endcode
 989  *
 990  * Tevent_req_create() allocates and zeros the state variable as a talloc
 991  * child of its result. The state variable should be used as the talloc
 992  * parent for all temporary variables that are allocated during the async
 993  * computation. This way, when the user of the async computation frees
 994  * the request, the state as a talloc child will be free'd along with
 995  * all the temporary variables hanging off the state.
 996  *
 997  * @param[in] mem_ctx   The memory context for the result.
 998  * @param[in] pstate    Pointer to the private request state.
 999  * @param[in] type      The name of the request.
1000  *
1001  * @return              A new async request. NULL on error.
1002  */
1003 struct tevent_req *tevent_req_create(TALLOC_CTX *mem_ctx,
1004                                      void **pstate, #type);
1005 #else
1006 struct tevent_req *_tevent_req_create(TALLOC_CTX *mem_ctx,
1007                                       void *pstate,
1008                                       size_t state_size,
1009                                       const char *type,
1010                                       const char *location);
1011
1012 #define tevent_req_create(_mem_ctx, _pstate, _type) \
1013         _tevent_req_create((_mem_ctx), (_pstate), sizeof(_type), \
1014                            #_type, __location__)
1015 #endif
1016
1017 /**
1018  * @brief Set a timeout for an async request.
1019  *
1020  * @param[in]  req      The request to set the timeout for.
1021  *
1022  * @param[in]  ev       The event context to use for the timer.
1023  *
1024  * @param[in]  endtime  The endtime of the request.
1025  *
1026  * @return              True if succeeded, false if not.
1027  */
1028 bool tevent_req_set_endtime(struct tevent_req *req,
1029                             struct tevent_context *ev,
1030                             struct timeval endtime);
1031
1032 #ifdef DOXYGEN
1033 /**
1034  * @brief Call the notify callback of the given tevent request manually.
1035  *
1036  * @param[in]  req      The tevent request to call the notify function from.
1037  *
1038  * @see tevent_req_set_callback()
1039  */
1040 void tevent_req_notify_callback(struct tevent_req *req);
1041 #else
1042 void _tevent_req_notify_callback(struct tevent_req *req, const char *location);
1043 #define tevent_req_notify_callback(req)         \
1044         _tevent_req_notify_callback(req, __location__)
1045 #endif
1046
1047 #ifdef DOXYGEN
1048 /**
1049  * @brief An async request has successfully finished.
1050  *
1051  * This function is to be used by implementors of async requests. When a
1052  * request is successfully finished, this function calls the user's completion
1053  * function.
1054  *
1055  * @param[in]  req       The finished request.
1056  */
1057 void tevent_req_done(struct tevent_req *req);
1058 #else
1059 void _tevent_req_done(struct tevent_req *req,
1060                       const char *location);
1061 #define tevent_req_done(req) \
1062         _tevent_req_done(req, __location__)
1063 #endif
1064
1065 #ifdef DOXYGEN
1066 /**
1067  * @brief An async request has seen an error.
1068  *
1069  * This function is to be used by implementors of async requests. When a
1070  * request can not successfully completed, the implementation should call this
1071  * function with the appropriate status code.
1072  *
1073  * If error is 0 the function returns false and does nothing more.
1074  *
1075  * @param[in]  req      The request with an error.
1076  *
1077  * @param[in]  error    The error code.
1078  *
1079  * @return              On success true is returned, false if error is 0.
1080  *
1081  * @code
1082  * int error = first_function();
1083  * if (tevent_req_error(req, error)) {
1084  *      return;
1085  * }
1086  *
1087  * error = second_function();
1088  * if (tevent_req_error(req, error)) {
1089  *      return;
1090  * }
1091  *
1092  * tevent_req_done(req);
1093  * return;
1094  * @endcode
1095  */
1096 bool tevent_req_error(struct tevent_req *req,
1097                       uint64_t error);
1098 #else
1099 bool _tevent_req_error(struct tevent_req *req,
1100                        uint64_t error,
1101                        const char *location);
1102 #define tevent_req_error(req, error) \
1103         _tevent_req_error(req, error, __location__)
1104 #endif
1105
1106 #ifdef DOXYGEN
1107 /**
1108  * @brief Helper function for nomem check.
1109  *
1110  * Convenience helper to easily check alloc failure within a callback
1111  * implementing the next step of an async request.
1112  *
1113  * @param[in]  p        The pointer to be checked.
1114  *
1115  * @param[in]  req      The request being processed.
1116  *
1117  * @code
1118  * p = talloc(mem_ctx, bla);
1119  * if (tevent_req_nomem(p, req)) {
1120  *      return;
1121  * }
1122  * @endcode
1123  */
1124 bool tevent_req_nomem(const void *p,
1125                       struct tevent_req *req);
1126 #else
1127 bool _tevent_req_nomem(const void *p,
1128                        struct tevent_req *req,
1129                        const char *location);
1130 #define tevent_req_nomem(p, req) \
1131         _tevent_req_nomem(p, req, __location__)
1132 #endif
1133
1134 #ifdef DOXYGEN
1135 /**
1136  * @brief Indicate out of memory to a request
1137  *
1138  * @param[in]  req      The request being processed.
1139  */
1140 void tevent_req_oom(struct tevent_req *req);
1141 #else
1142 void _tevent_req_oom(struct tevent_req *req,
1143                      const char *location);
1144 #define tevent_req_oom(req) \
1145         _tevent_req_oom(req, __location__)
1146 #endif
1147
1148 /**
1149  * @brief Finish a request before the caller had the change to set the callback.
1150  *
1151  * An implementation of an async request might find that it can either finish
1152  * the request without waiting for an external event, or it can not even start
1153  * the engine. To present the illusion of a callback to the user of the API,
1154  * the implementation can call this helper function which triggers an
1155  * immediate event. This way the caller can use the same calling
1156  * conventions, independent of whether the request was actually deferred.
1157  *
1158  * @code
1159  * struct tevent_req *computation_send(TALLOC_CTX *mem_ctx,
1160  *                                     struct tevent_context *ev)
1161  * {
1162  *     struct tevent_req *req, *subreq;
1163  *     struct computation_state *state;
1164  *     req = tevent_req_create(mem_ctx, &state, struct computation_state);
1165  *     if (req == NULL) {
1166  *         return NULL;
1167  *     }
1168  *     subreq = subcomputation_send(state, ev);
1169  *     if (tevent_req_nomem(subreq, req)) {
1170  *         return tevent_req_post(req, ev);
1171  *     }
1172  *     tevent_req_set_callback(subreq, computation_done, req);
1173  *     return req;
1174  * }
1175  * @endcode
1176  *
1177  * @param[in]  req      The finished request.
1178  *
1179  * @param[in]  ev       The tevent_context for the immediate event.
1180  *
1181  * @return              The given request will be returned.
1182  */
1183 struct tevent_req *tevent_req_post(struct tevent_req *req,
1184                                    struct tevent_context *ev);
1185
1186 /**
1187  * @brief Finish multiple requests within one function
1188  *
1189  * Normally tevent_req_notify_callback() and all wrappers
1190  * (e.g. tevent_req_done() and tevent_req_error())
1191  * need to be the last thing an event handler should call.
1192  * This is because the callback is likely to destroy the
1193  * context of the current function.
1194  *
1195  * If a function wants to notify more than one caller,
1196  * it is dangerous if it just triggers multiple callbacks
1197  * in a row. With tevent_req_defer_callback() it is possible
1198  * to set an event context that will be used to defer the callback
1199  * via an immediate event (similar to tevent_req_post()).
1200  *
1201  * @code
1202  * struct complete_state {
1203  *       struct tevent_context *ev;
1204  *
1205  *       struct tevent_req **reqs;
1206  * };
1207  *
1208  * void complete(struct complete_state *state)
1209  * {
1210  *       size_t i, c = talloc_array_length(state->reqs);
1211  *
1212  *       for (i=0; i < c; i++) {
1213  *            tevent_req_defer_callback(state->reqs[i], state->ev);
1214  *            tevent_req_done(state->reqs[i]);
1215  *       }
1216  * }
1217  * @endcode
1218  *
1219  * @param[in]  req      The finished request.
1220  *
1221  * @param[in]  ev       The tevent_context for the immediate event.
1222  *
1223  * @return              The given request will be returned.
1224  */
1225 void tevent_req_defer_callback(struct tevent_req *req,
1226                                struct tevent_context *ev);
1227
1228 /**
1229  * @brief Check if the given request is still in progress.
1230  *
1231  * It is typically used by sync wrapper functions.
1232  *
1233  * @param[in]  req      The request to poll.
1234  *
1235  * @return              The boolean form of "is in progress".
1236  */
1237 bool tevent_req_is_in_progress(struct tevent_req *req);
1238
1239 /**
1240  * @brief Actively poll for the given request to finish.
1241  *
1242  * This function is typically used by sync wrapper functions.
1243  *
1244  * @param[in]  req      The request to poll.
1245  *
1246  * @param[in]  ev       The tevent_context to be used.
1247  *
1248  * @return              On success true is returned. If a critical error has
1249  *                      happened in the tevent loop layer false is returned.
1250  *                      This is not the return value of the given request!
1251  *
1252  * @note This should only be used if the given tevent context was created by the
1253  * caller, to avoid event loop nesting.
1254  *
1255  * @code
1256  * req = tstream_writev_queue_send(mem_ctx,
1257  *                                 ev_ctx,
1258  *                                 tstream,
1259  *                                 send_queue,
1260  *                                 iov, 2);
1261  * ok = tevent_req_poll(req, tctx->ev);
1262  * rc = tstream_writev_queue_recv(req, &sys_errno);
1263  * TALLOC_FREE(req);
1264  * @endcode
1265  */
1266 bool tevent_req_poll(struct tevent_req *req,
1267                      struct tevent_context *ev);
1268
1269 /**
1270  * @brief Get the tevent request state and the actual error set by
1271  * tevent_req_error.
1272  *
1273  * @code
1274  * int computation_recv(struct tevent_req *req, uint64_t *perr)
1275  * {
1276  *     enum tevent_req_state state;
1277  *     uint64_t err;
1278  *     if (tevent_req_is_error(req, &state, &err)) {
1279  *         *perr = err;
1280  *         return -1;
1281  *     }
1282  *     return 0;
1283  * }
1284  * @endcode
1285  *
1286  * @param[in]  req      The tevent request to get the error from.
1287  *
1288  * @param[out] state    A pointer to store the tevent request error state.
1289  *
1290  * @param[out] error    A pointer to store the error set by tevent_req_error().
1291  *
1292  * @return              True if the function could set error and state, false
1293  *                      otherwise.
1294  *
1295  * @see tevent_req_error()
1296  */
1297 bool tevent_req_is_error(struct tevent_req *req,
1298                          enum tevent_req_state *state,
1299                          uint64_t *error);
1300
1301 /**
1302  * @brief Use as the last action of a _recv() function.
1303  *
1304  * This function destroys the attached private data.
1305  *
1306  * @param[in]  req      The finished request.
1307  */
1308 void tevent_req_received(struct tevent_req *req);
1309
1310 /**
1311  * @brief Create a tevent subrequest at a given time.
1312  *
1313  * The idea is that always the same syntax for tevent requests.
1314  *
1315  * @param[in]  mem_ctx  The talloc memory context to use.
1316  *
1317  * @param[in]  ev       The event handle to setup the request.
1318  *
1319  * @param[in]  wakeup_time The time to wakeup and execute the request.
1320  *
1321  * @return              The new subrequest, NULL on error.
1322  *
1323  * Example:
1324  * @code
1325  *   static void my_callback_wakeup_done(tevent_req *subreq)
1326  *   {
1327  *     struct tevent_req *req = tevent_req_callback_data(subreq,
1328  *                              struct tevent_req);
1329  *     bool ok;
1330  *
1331  *     ok = tevent_wakeup_recv(subreq);
1332  *     TALLOC_FREE(subreq);
1333  *     if (!ok) {
1334  *         tevent_req_error(req, -1);
1335  *         return;
1336  *     }
1337  *     ...
1338  *   }
1339  * @endcode
1340  *
1341  * @code
1342  *   subreq = tevent_wakeup_send(mem_ctx, ev, wakeup_time);
1343  *   if (tevent_req_nomem(subreq, req)) {
1344  *     return false;
1345  *   }
1346  *   tevent_set_callback(subreq, my_callback_wakeup_done, req);
1347  * @endcode
1348  *
1349  * @see tevent_wakeup_recv()
1350  */
1351 struct tevent_req *tevent_wakeup_send(TALLOC_CTX *mem_ctx,
1352                                       struct tevent_context *ev,
1353                                       struct timeval wakeup_time);
1354
1355 /**
1356  * @brief Check if the wakeup has been correctly executed.
1357  *
1358  * This function needs to be called in the callback function set after calling
1359  * tevent_wakeup_send().
1360  *
1361  * @param[in]  req      The tevent request to check.
1362  *
1363  * @return              True on success, false otherwise.
1364  *
1365  * @see tevent_wakeup_recv()
1366  */
1367 bool tevent_wakeup_recv(struct tevent_req *req);
1368
1369 /* @} */
1370
1371 /**
1372  * @defgroup tevent_helpers The tevent helper functiions
1373  * @ingroup tevent
1374  *
1375  * @todo description
1376  *
1377  * @{
1378  */
1379
1380 /**
1381  * @brief Compare two timeval values.
1382  *
1383  * @param[in]  tv1      The first timeval value to compare.
1384  *
1385  * @param[in]  tv2      The second timeval value to compare.
1386  *
1387  * @return              0 if they are equal.
1388  *                      1 if the first time is greater than the second.
1389  *                      -1 if the first time is smaller than the second.
1390  */
1391 int tevent_timeval_compare(const struct timeval *tv1,
1392                            const struct timeval *tv2);
1393
1394 /**
1395  * @brief Get a zero timval value.
1396  *
1397  * @return              A zero timval value.
1398  */
1399 struct timeval tevent_timeval_zero(void);
1400
1401 /**
1402  * @brief Get a timeval value for the current time.
1403  *
1404  * @return              A timval value with the current time.
1405  */
1406 struct timeval tevent_timeval_current(void);
1407
1408 /**
1409  * @brief Get a timeval structure with the given values.
1410  *
1411  * @param[in]  secs     The seconds to set.
1412  *
1413  * @param[in]  usecs    The microseconds to set.
1414  *
1415  * @return              A timeval structure with the given values.
1416  */
1417 struct timeval tevent_timeval_set(uint32_t secs, uint32_t usecs);
1418
1419 /**
1420  * @brief Get the difference between two timeval values.
1421  *
1422  * @param[in]  tv1      The first timeval.
1423  *
1424  * @param[in]  tv2      The second timeval.
1425  *
1426  * @return              A timeval structure with the difference between the
1427  *                      first and the second value.
1428  */
1429 struct timeval tevent_timeval_until(const struct timeval *tv1,
1430                                     const struct timeval *tv2);
1431
1432 /**
1433  * @brief Check if a given timeval structure is zero.
1434  *
1435  * @param[in]  tv       The timeval to check if it is zero.
1436  *
1437  * @return              True if it is zero, false otherwise.
1438  */
1439 bool tevent_timeval_is_zero(const struct timeval *tv);
1440
1441 /**
1442  * @brief Add the given amount of time to a timeval structure.
1443  *
1444  * @param[in]  tv        The timeval structure to add the time.
1445  *
1446  * @param[in]  secs      The seconds to add to the timeval.
1447  *
1448  * @param[in]  usecs     The microseconds to add to the timeval.
1449  *
1450  * @return               The timeval structure with the new time.
1451  */
1452 struct timeval tevent_timeval_add(const struct timeval *tv, uint32_t secs,
1453                                   uint32_t usecs);
1454
1455 /**
1456  * @brief Get a timeval in the future with a specified offset from now.
1457  *
1458  * @param[in]  secs     The seconds of the offset from now.
1459  *
1460  * @param[in]  usecs    The microseconds of the offset from now.
1461  *
1462  * @return              A timval with the given offset in the future.
1463  */
1464 struct timeval tevent_timeval_current_ofs(uint32_t secs, uint32_t usecs);
1465
1466 /* @} */
1467
1468
1469 /**
1470  * @defgroup tevent_queue The tevent queue functions
1471  * @ingroup tevent
1472  *
1473  * A tevent_queue is used to queue up async requests that must be
1474  * serialized. For example writing buffers into a socket must be
1475  * serialized. Writing a large lump of data into a socket can require
1476  * multiple write(2) or send(2) system calls. If more than one async
1477  * request is outstanding to write large buffers into a socket, every
1478  * request must individually be completed before the next one begins,
1479  * even if multiple syscalls are required.
1480  *
1481  * Take a look at @ref tevent_queue_tutorial for more details.
1482  * @{
1483  */
1484
1485 struct tevent_queue;
1486 struct tevent_queue_entry;
1487
1488 #ifdef DOXYGEN
1489 /**
1490  * @brief Create and start a tevent queue.
1491  *
1492  * @param[in]  mem_ctx  The talloc memory context to allocate the queue.
1493  *
1494  * @param[in]  name     The name to use to identify the queue.
1495  *
1496  * @return              An allocated tevent queue on success, NULL on error.
1497  *
1498  * @see tevent_queue_start()
1499  * @see tevent_queue_stop()
1500  */
1501 struct tevent_queue *tevent_queue_create(TALLOC_CTX *mem_ctx,
1502                                          const char *name);
1503 #else
1504 struct tevent_queue *_tevent_queue_create(TALLOC_CTX *mem_ctx,
1505                                           const char *name,
1506                                           const char *location);
1507
1508 #define tevent_queue_create(_mem_ctx, _name) \
1509         _tevent_queue_create((_mem_ctx), (_name), __location__)
1510 #endif
1511
1512 /**
1513  * @brief A callback trigger function run by the queue.
1514  *
1515  * @param[in]  req      The tevent request the trigger function is executed on.
1516  *
1517  * @param[in]  private_data The private data pointer specified by
1518  *                          tevent_queue_add().
1519  *
1520  * @see tevent_queue_add()
1521  * @see tevent_queue_add_entry()
1522  * @see tevent_queue_add_optimize_empty()
1523  */
1524 typedef void (*tevent_queue_trigger_fn_t)(struct tevent_req *req,
1525                                           void *private_data);
1526
1527 /**
1528  * @brief Add a tevent request to the queue.
1529  *
1530  * @param[in]  queue    The queue to add the request.
1531  *
1532  * @param[in]  ev       The event handle to use for the request.
1533  *
1534  * @param[in]  req      The tevent request to add to the queue.
1535  *
1536  * @param[in]  trigger  The function triggered by the queue when the request
1537  *                      is called. Since tevent 0.9.14 it's possible to
1538  *                      pass NULL, in order to just add a "blocker" to the
1539  *                      queue.
1540  *
1541  * @param[in]  private_data The private data passed to the trigger function.
1542  *
1543  * @return              True if the request has been successfully added, false
1544  *                      otherwise.
1545  */
1546 bool tevent_queue_add(struct tevent_queue *queue,
1547                       struct tevent_context *ev,
1548                       struct tevent_req *req,
1549                       tevent_queue_trigger_fn_t trigger,
1550                       void *private_data);
1551
1552 /**
1553  * @brief Add a tevent request to the queue.
1554  *
1555  * The request can be removed from the queue by calling talloc_free()
1556  * (or a similar function) on the returned queue entry. This
1557  * is the only difference to tevent_queue_add().
1558  *
1559  * @param[in]  queue    The queue to add the request.
1560  *
1561  * @param[in]  ev       The event handle to use for the request.
1562  *
1563  * @param[in]  req      The tevent request to add to the queue.
1564  *
1565  * @param[in]  trigger  The function triggered by the queue when the request
1566  *                      is called. Since tevent 0.9.14 it's possible to
1567  *                      pass NULL, in order to just add a "blocker" to the
1568  *                      queue.
1569  *
1570  * @param[in]  private_data The private data passed to the trigger function.
1571  *
1572  * @return              a pointer to the tevent_queue_entry if the request
1573  *                      has been successfully added, NULL otherwise.
1574  *
1575  * @see tevent_queue_add()
1576  * @see tevent_queue_add_optimize_empty()
1577  */
1578 struct tevent_queue_entry *tevent_queue_add_entry(
1579                                         struct tevent_queue *queue,
1580                                         struct tevent_context *ev,
1581                                         struct tevent_req *req,
1582                                         tevent_queue_trigger_fn_t trigger,
1583                                         void *private_data);
1584
1585 /**
1586  * @brief Add a tevent request to the queue using a possible optimization.
1587  *
1588  * This tries to optimize for the empty queue case and may calls
1589  * the trigger function directly. This is the only difference compared
1590  * to tevent_queue_add_entry().
1591  *
1592  * The caller needs to be prepared that the trigger function has
1593  * already called tevent_req_notify_callback(), tevent_req_error(),
1594  * tevent_req_done() or a similar function.
1595  *
1596  * The request can be removed from the queue by calling talloc_free()
1597  * (or a similar function) on the returned queue entry.
1598  *
1599  * @param[in]  queue    The queue to add the request.
1600  *
1601  * @param[in]  ev       The event handle to use for the request.
1602  *
1603  * @param[in]  req      The tevent request to add to the queue.
1604  *
1605  * @param[in]  trigger  The function triggered by the queue when the request
1606  *                      is called. Since tevent 0.9.14 it's possible to
1607  *                      pass NULL, in order to just add a "blocker" to the
1608  *                      queue.
1609  *
1610  * @param[in]  private_data The private data passed to the trigger function.
1611  *
1612  * @return              a pointer to the tevent_queue_entry if the request
1613  *                      has been successfully added, NULL otherwise.
1614  *
1615  * @see tevent_queue_add()
1616  * @see tevent_queue_add_entry()
1617  */
1618 struct tevent_queue_entry *tevent_queue_add_optimize_empty(
1619                                         struct tevent_queue *queue,
1620                                         struct tevent_context *ev,
1621                                         struct tevent_req *req,
1622                                         tevent_queue_trigger_fn_t trigger,
1623                                         void *private_data);
1624
1625 /**
1626  * @brief Start a tevent queue.
1627  *
1628  * The queue is started by default.
1629  *
1630  * @param[in]  queue    The queue to start.
1631  */
1632 void tevent_queue_start(struct tevent_queue *queue);
1633
1634 /**
1635  * @brief Stop a tevent queue.
1636  *
1637  * The queue is started by default.
1638  *
1639  * @param[in]  queue    The queue to stop.
1640  */
1641 void tevent_queue_stop(struct tevent_queue *queue);
1642
1643 /**
1644  * @brief Get the length of the queue.
1645  *
1646  * @param[in]  queue    The queue to get the length from.
1647  *
1648  * @return              The number of elements.
1649  */
1650 size_t tevent_queue_length(struct tevent_queue *queue);
1651
1652 /**
1653  * @brief Is the tevent queue running.
1654  *
1655  * The queue is started by default.
1656  *
1657  * @param[in]  queue    The queue.
1658  *
1659  * @return              Wether the queue is running or not..
1660  */
1661 bool tevent_queue_running(struct tevent_queue *queue);
1662
1663 /**
1664  * @brief Create a tevent subrequest that waits in a tevent_queue
1665  *
1666  * The idea is that always the same syntax for tevent requests.
1667  *
1668  * @param[in]  mem_ctx  The talloc memory context to use.
1669  *
1670  * @param[in]  ev       The event handle to setup the request.
1671  *
1672  * @param[in]  queue    The queue to wait in.
1673  *
1674  * @return              The new subrequest, NULL on error.
1675  *
1676  * @see tevent_queue_wait_recv()
1677  */
1678 struct tevent_req *tevent_queue_wait_send(TALLOC_CTX *mem_ctx,
1679                                           struct tevent_context *ev,
1680                                           struct tevent_queue *queue);
1681
1682 /**
1683  * @brief Check if we no longer need to wait in the queue.
1684  *
1685  * This function needs to be called in the callback function set after calling
1686  * tevent_queue_wait_send().
1687  *
1688  * @param[in]  req      The tevent request to check.
1689  *
1690  * @return              True on success, false otherwise.
1691  *
1692  * @see tevent_queue_wait_send()
1693  */
1694 bool tevent_queue_wait_recv(struct tevent_req *req);
1695
1696 typedef int (*tevent_nesting_hook)(struct tevent_context *ev,
1697                                    void *private_data,
1698                                    uint32_t level,
1699                                    bool begin,
1700                                    void *stack_ptr,
1701                                    const char *location);
1702
1703 /**
1704  * @brief Create a tevent_thread_proxy for message passing between threads.
1705  *
1706  * The tevent_context must have been allocated on the NULL
1707  * talloc context, and talloc_disable_null_tracking() must
1708  * have been called.
1709  *
1710  * @param[in]  dest_ev_ctx      The tevent_context to receive events.
1711  *
1712  * @return              An allocated tevent_thread_proxy, NULL on error.
1713  *                      If tevent was compiled without PTHREAD support
1714  *                      NULL is always returned and errno set to ENOSYS.
1715  *
1716  * @see tevent_thread_proxy_schedule()
1717  */
1718 struct tevent_thread_proxy *tevent_thread_proxy_create(
1719                 struct tevent_context *dest_ev_ctx);
1720
1721 /**
1722  * @brief Schedule an immediate event on an event context from another thread.
1723  *
1724  * Causes dest_ev_ctx, being run by another thread, to receive an
1725  * immediate event calling the handler with the *pp_private parameter.
1726  *
1727  * *pp_im must be a pointer to an immediate event talloced on a context owned
1728  * by the calling thread, or the NULL context. Ownership will
1729  * be transferred to the tevent_thread_proxy and *pp_im will be returned as NULL.
1730  *
1731  * *pp_private_data must be a talloced area of memory with no destructors.
1732  * Ownership of this memory will be transferred to the tevent library and
1733  * *pp_private_data will be set to NULL on successful completion of
1734  * the call. Set pp_private to NULL if no parameter transfer
1735  * needed (a pure callback). This is an asynchronous request, caller
1736  * does not wait for callback to be completed before returning.
1737  *
1738  * @param[in]  tp               The tevent_thread_proxy to use.
1739  *
1740  * @param[in]  pp_im            Pointer to immediate event pointer.
1741  *
1742  * @param[in]  handler          The function that will be called.
1743  *
1744  * @param[in]  pp_private_data  The talloced memory to transfer.
1745  *
1746  * @see tevent_thread_proxy_create()
1747  */
1748 void tevent_thread_proxy_schedule(struct tevent_thread_proxy *tp,
1749                                   struct tevent_immediate **pp_im,
1750                                   tevent_immediate_handler_t handler,
1751                                   void *pp_private_data);
1752
1753 #ifdef TEVENT_DEPRECATED
1754 #ifndef _DEPRECATED_
1755 #ifdef HAVE___ATTRIBUTE__
1756 #define _DEPRECATED_ __attribute__ ((deprecated))
1757 #else
1758 #define _DEPRECATED_
1759 #endif
1760 #endif
1761 void tevent_loop_allow_nesting(struct tevent_context *ev) _DEPRECATED_;
1762 void tevent_loop_set_nesting_hook(struct tevent_context *ev,
1763                                   tevent_nesting_hook hook,
1764                                   void *private_data) _DEPRECATED_;
1765 int _tevent_loop_until(struct tevent_context *ev,
1766                        bool (*finished)(void *private_data),
1767                        void *private_data,
1768                        const char *location) _DEPRECATED_;
1769 #define tevent_loop_until(ev, finished, private_data) \
1770         _tevent_loop_until(ev, finished, private_data, __location__)
1771 #endif
1772
1773 int tevent_re_initialise(struct tevent_context *ev);
1774
1775 /* @} */
1776
1777 /**
1778  * @defgroup tevent_ops The tevent operation functions
1779  * @ingroup tevent
1780  *
1781  * The following structure and registration functions are exclusively
1782  * needed for people writing and pluggin a different event engine.
1783  * There is nothing useful for normal tevent user in here.
1784  * @{
1785  */
1786
1787 struct tevent_ops {
1788         /* context init */
1789         int (*context_init)(struct tevent_context *ev);
1790
1791         /* fd_event functions */
1792         struct tevent_fd *(*add_fd)(struct tevent_context *ev,
1793                                     TALLOC_CTX *mem_ctx,
1794                                     int fd, uint16_t flags,
1795                                     tevent_fd_handler_t handler,
1796                                     void *private_data,
1797                                     const char *handler_name,
1798                                     const char *location);
1799         void (*set_fd_close_fn)(struct tevent_fd *fde,
1800                                 tevent_fd_close_fn_t close_fn);
1801         uint16_t (*get_fd_flags)(struct tevent_fd *fde);
1802         void (*set_fd_flags)(struct tevent_fd *fde, uint16_t flags);
1803
1804         /* timed_event functions */
1805         struct tevent_timer *(*add_timer)(struct tevent_context *ev,
1806                                           TALLOC_CTX *mem_ctx,
1807                                           struct timeval next_event,
1808                                           tevent_timer_handler_t handler,
1809                                           void *private_data,
1810                                           const char *handler_name,
1811                                           const char *location);
1812
1813         /* immediate event functions */
1814         void (*schedule_immediate)(struct tevent_immediate *im,
1815                                    struct tevent_context *ev,
1816                                    tevent_immediate_handler_t handler,
1817                                    void *private_data,
1818                                    const char *handler_name,
1819                                    const char *location);
1820
1821         /* signal functions */
1822         struct tevent_signal *(*add_signal)(struct tevent_context *ev,
1823                                             TALLOC_CTX *mem_ctx,
1824                                             int signum, int sa_flags,
1825                                             tevent_signal_handler_t handler,
1826                                             void *private_data,
1827                                             const char *handler_name,
1828                                             const char *location);
1829
1830         /* loop functions */
1831         int (*loop_once)(struct tevent_context *ev, const char *location);
1832         int (*loop_wait)(struct tevent_context *ev, const char *location);
1833 };
1834
1835 bool tevent_register_backend(const char *name, const struct tevent_ops *ops);
1836
1837 /* @} */
1838
1839 /**
1840  * @defgroup tevent_compat The tevent compatibility functions
1841  * @ingroup tevent
1842  *
1843  * The following definitions are usueful only for compatibility with the
1844  * implementation originally developed within the samba4 code and will be
1845  * soon removed. Please NEVER use in new code.
1846  *
1847  * @todo Ignore it?
1848  *
1849  * @{
1850  */
1851
1852 #ifdef TEVENT_COMPAT_DEFINES
1853
1854 #define event_context   tevent_context
1855 #define event_ops       tevent_ops
1856 #define fd_event        tevent_fd
1857 #define timed_event     tevent_timer
1858 #define signal_event    tevent_signal
1859
1860 #define event_fd_handler_t      tevent_fd_handler_t
1861 #define event_timed_handler_t   tevent_timer_handler_t
1862 #define event_signal_handler_t  tevent_signal_handler_t
1863
1864 #define event_context_init(mem_ctx) \
1865         tevent_context_init(mem_ctx)
1866
1867 #define event_context_init_byname(mem_ctx, name) \
1868         tevent_context_init_byname(mem_ctx, name)
1869
1870 #define event_backend_list(mem_ctx) \
1871         tevent_backend_list(mem_ctx)
1872
1873 #define event_set_default_backend(backend) \
1874         tevent_set_default_backend(backend)
1875
1876 #define event_add_fd(ev, mem_ctx, fd, flags, handler, private_data) \
1877         tevent_add_fd(ev, mem_ctx, fd, flags, handler, private_data)
1878
1879 #define event_add_timed(ev, mem_ctx, next_event, handler, private_data) \
1880         tevent_add_timer(ev, mem_ctx, next_event, handler, private_data)
1881
1882 #define event_add_signal(ev, mem_ctx, signum, sa_flags, handler, private_data) \
1883         tevent_add_signal(ev, mem_ctx, signum, sa_flags, handler, private_data)
1884
1885 #define event_loop_once(ev) \
1886         tevent_loop_once(ev)
1887
1888 #define event_loop_wait(ev) \
1889         tevent_loop_wait(ev)
1890
1891 #define event_get_fd_flags(fde) \
1892         tevent_fd_get_flags(fde)
1893
1894 #define event_set_fd_flags(fde, flags) \
1895         tevent_fd_set_flags(fde, flags)
1896
1897 #define EVENT_FD_READ           TEVENT_FD_READ
1898 #define EVENT_FD_WRITE          TEVENT_FD_WRITE
1899
1900 #define EVENT_FD_WRITEABLE(fde) \
1901         TEVENT_FD_WRITEABLE(fde)
1902
1903 #define EVENT_FD_READABLE(fde) \
1904         TEVENT_FD_READABLE(fde)
1905
1906 #define EVENT_FD_NOT_WRITEABLE(fde) \
1907         TEVENT_FD_NOT_WRITEABLE(fde)
1908
1909 #define EVENT_FD_NOT_READABLE(fde) \
1910         TEVENT_FD_NOT_READABLE(fde)
1911
1912 #define ev_debug_level          tevent_debug_level
1913
1914 #define EV_DEBUG_FATAL          TEVENT_DEBUG_FATAL
1915 #define EV_DEBUG_ERROR          TEVENT_DEBUG_ERROR
1916 #define EV_DEBUG_WARNING        TEVENT_DEBUG_WARNING
1917 #define EV_DEBUG_TRACE          TEVENT_DEBUG_TRACE
1918
1919 #define ev_set_debug(ev, debug, context) \
1920         tevent_set_debug(ev, debug, context)
1921
1922 #define ev_set_debug_stderr(_ev) tevent_set_debug_stderr(ev)
1923
1924 #endif /* TEVENT_COMPAT_DEFINES */
1925
1926 /* @} */
1927
1928 #endif /* __TEVENT_H__ */