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