lib/tevent/tevent.h

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