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