lib/tevent/tevent.h

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