lib/tevent/tevent_internal.h

   1 /*
   2    Unix SMB/CIFS implementation.
   3
   4    generalised event loop handling
   5
   6    INTERNAL STRUCTS. THERE ARE NO API GUARANTEES.
   7    External users should only ever have to include this header when
   8    implementing new tevent backends.
   9
  10    Copyright (C) Stefan Metzmacher 2005-2009
  11
  12      ** NOTE! The following LGPL license applies to the tevent
  13      ** library. This does NOT imply that all of Samba is released
  14      ** under the LGPL
  15
  16    This library is free software; you can redistribute it and/or
  17    modify it under the terms of the GNU Lesser General Public
  18    License as published by the Free Software Foundation; either
  19    version 3 of the License, or (at your option) any later version.
  20
  21    This library is distributed in the hope that it will be useful,
  22    but WITHOUT ANY WARRANTY; without even the implied warranty of
  23    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  24    Lesser General Public License for more details.
  25
  26    You should have received a copy of the GNU Lesser General Public
  27    License along with this library; if not, see <http://www.gnu.org/licenses/>.
  28 */
  29
  30 struct tevent_req {
  31         /**
  32          * @brief What to do on completion
  33          *
  34          * This is used for the user of an async request, fn is called when
  35          * the request completes, either successfully or with an error.
  36          */
  37         struct {
  38                 /**
  39                  * @brief Completion function
  40                  * Completion function, to be filled by the API user
  41                  */
  42                 tevent_req_fn fn;
  43                 /**
  44                  * @brief Private data for the completion function
  45                  */
  46                 void *private_data;
  47                 /**
  48                  * @brief  The completion function name, for flow tracing.
  49                  */
  50                 const char *fn_name;
  51         } async;
  52
  53         /**
  54          * @brief Private state pointer for the actual implementation
  55          *
  56          * The implementation doing the work for the async request needs to
  57          * keep around current data like for example a fd event. The user of
  58          * an async request should not touch this.
  59          */
  60         void *data;
  61
  62         /**
  63          * @brief A function to overwrite the default print function
  64          *
  65          * The implementation doing the work may want to implement a
  66          * custom function to print the text representation of the async
  67          * request.
  68          */
  69         tevent_req_print_fn private_print;
  70
  71         /**
  72          * @brief A function to cancel the request
  73          *
  74          * The implementation might want to set a function
  75          * that is called when the tevent_req_cancel() function
  76          * was called.
  77          */
  78         tevent_req_cancel_fn private_cancel;
  79
  80         /**
  81          * @brief A function to cleanup the request
  82          *
  83          * The implementation might want to set a function
  84          * that is called before the tevent_req_done() and tevent_req_error()
  85          * trigger the callers callback function.
  86          */
  87         struct {
  88                 tevent_req_cleanup_fn fn;
  89                 enum tevent_req_state state;
  90         } private_cleanup;
  91
  92         /**
  93          * @brief Internal state of the request
  94          *
  95          * Callers should only access this via functions and never directly.
  96          */
  97         struct {
  98                 /**
  99                  * @brief The talloc type of the data pointer
 100                  *
 101                  * This is filled by the tevent_req_create() macro.
 102                  *
 103                  * This for debugging only.
 104                  */
 105                 const char *private_type;
 106
 107                 /**
 108                  * @brief The location where the request was created
 109                  *
 110                  * This uses the __location__ macro via the tevent_req_create()
 111                  * macro.
 112                  *
 113                  * This for debugging only.
 114                  */
 115                 const char *create_location;
 116
 117                 /**
 118                  * @brief The location where the request was finished
 119                  *
 120                  * This uses the __location__ macro via the tevent_req_done(),
 121                  * tevent_req_error() or tevent_req_nomem() macro.
 122                  *
 123                  * This for debugging only.
 124                  */
 125                 const char *finish_location;
 126
 127                 /**
 128                  * @brief The location where the request was canceled
 129                  *
 130                  * This uses the __location__ macro via the
 131                  * tevent_req_cancel() macro.
 132                  *
 133                  * This for debugging only.
 134                  */
 135                 const char *cancel_location;
 136
 137                 /**
 138                  * @brief The external state - will be queried by the caller
 139                  *
 140                  * While the async request is being processed, state will remain in
 141                  * TEVENT_REQ_IN_PROGRESS. A request is finished if
 142                  * req->state>=TEVENT_REQ_DONE.
 143                  */
 144                 enum tevent_req_state state;
 145
 146                 /**
 147                  * @brief status code when finished
 148                  *
 149                  * This status can be queried in the async completion function. It
 150                  * will be set to 0 when everything went fine.
 151                  */
 152                 uint64_t error;
 153
 154                 /**
 155                  * @brief the immediate event used by tevent_req_post
 156                  *
 157                  */
 158                 struct tevent_immediate *trigger;
 159
 160                 /**
 161                  * @brief An event context which will be used to
 162                  *        defer the _tevent_req_notify_callback().
 163                  */
 164                 struct tevent_context *defer_callback_ev;
 165
 166                 /**
 167                  * @brief the timer event if tevent_req_set_endtime was used
 168                  *
 169                  */
 170                 struct tevent_timer *timer;
 171
 172                 /**
 173                  * @brief The place where profiling data is kept
 174                  */
 175                 struct tevent_req_profile *profile;
 176
 177                 size_t call_depth;
 178         } internal;
 179 };
 180
 181 struct tevent_req_profile {
 182         struct tevent_req_profile *prev, *next;
 183         struct tevent_req_profile *parent;
 184         const char *req_name;
 185         pid_t pid;
 186         const char *start_location;
 187         struct timeval start_time;
 188         const char *stop_location;
 189         struct timeval stop_time;
 190         enum tevent_req_state state;
 191         uint64_t user_error;
 192         struct tevent_req_profile *subprofiles;
 193 };
 194
 195 struct tevent_fd {
 196         struct tevent_fd *prev, *next;
 197         struct tevent_context *event_ctx;
 198         struct tevent_wrapper_glue *wrapper;
 199         bool busy;
 200         bool destroyed;
 201         int fd;
 202         uint16_t flags; /* see TEVENT_FD_* flags */
 203         tevent_fd_handler_t handler;
 204         tevent_fd_close_fn_t close_fn;
 205         /* this is private for the specific handler */
 206         void *private_data;
 207         /* this is for debugging only! */
 208         const char *handler_name;
 209         const char *location;
 210         /* this is private for the events_ops implementation */
 211         uint64_t additional_flags;
 212         void *additional_data;
 213         /* custom tag that can be set by caller */
 214         uint64_t tag;
 215 };
 216
 217 struct tevent_timer {
 218         struct tevent_timer *prev, *next;
 219         struct tevent_context *event_ctx;
 220         struct tevent_wrapper_glue *wrapper;
 221         bool busy;
 222         bool destroyed;
 223         struct timeval next_event;
 224         tevent_timer_handler_t handler;
 225         /* this is private for the specific handler */
 226         void *private_data;
 227         /* this is for debugging only! */
 228         const char *handler_name;
 229         const char *location;
 230         /* this is private for the events_ops implementation */
 231         void *additional_data;
 232         /* custom tag that can be set by caller */
 233         uint64_t tag;
 234 };
 235
 236 struct tevent_immediate {
 237         struct tevent_immediate *prev, *next;
 238         struct tevent_context *event_ctx;
 239         struct tevent_wrapper_glue *wrapper;
 240         bool busy;
 241         bool destroyed;
 242         struct tevent_context *detach_ev_ctx;
 243         tevent_immediate_handler_t handler;
 244         /* this is private for the specific handler */
 245         void *private_data;
 246         /* this is for debugging only! */
 247         const char *handler_name;
 248         const char *create_location;
 249         const char *schedule_location;
 250         /* this is private for the events_ops implementation */
 251         void (*cancel_fn)(struct tevent_immediate *im);
 252         void *additional_data;
 253         /* custom tag that can be set by caller */
 254         uint64_t tag;
 255 };
 256
 257 struct tevent_signal {
 258         struct tevent_signal *prev, *next;
 259         struct tevent_context *event_ctx;
 260         struct tevent_wrapper_glue *wrapper;
 261         bool busy;
 262         bool destroyed;
 263         int signum;
 264         int sa_flags;
 265         tevent_signal_handler_t handler;
 266         /* this is private for the specific handler */
 267         void *private_data;
 268         /* this is for debugging only! */
 269         const char *handler_name;
 270         const char *location;
 271         /* this is private for the events_ops implementation */
 272         void *additional_data;
 273         /* custom tag that can be set by caller */
 274         uint64_t tag;
 275 };
 276
 277 struct tevent_threaded_context {
 278         struct tevent_threaded_context *next, *prev;
 279
 280 #ifdef HAVE_PTHREAD
 281         pthread_mutex_t event_ctx_mutex;
 282 #endif
 283         struct tevent_context *event_ctx;
 284 };
 285
 286 struct tevent_debug_ops {
 287         void (*debug)(void *context, enum tevent_debug_level level,
 288                       const char *fmt, va_list ap) PRINTF_ATTRIBUTE(3,0);
 289         void *context;
 290 };
 291
 292 void tevent_debug(struct tevent_context *ev, enum tevent_debug_level level,
 293                   const char *fmt, ...) PRINTF_ATTRIBUTE(3,4);
 294
 295 void tevent_abort(struct tevent_context *ev, const char *reason);
 296
 297 void tevent_common_check_double_free(TALLOC_CTX *ptr, const char *reason);
 298
 299 struct tevent_context {
 300         /* the specific events implementation */
 301         const struct tevent_ops *ops;
 302
 303         /*
 304          * The following three pointers are queried on every loop_once
 305          * in the order in which they appear here. Not measured, but
 306          * hopefully putting them at the top together with "ops"
 307          * should make tevent a *bit* more cache-friendly than before.
 308          */
 309
 310         /* list of signal events - used by common code */
 311         struct tevent_signal *signal_events;
 312
 313         /* List of threaded job indicators */
 314         struct tevent_threaded_context *threaded_contexts;
 315
 316         /* list of immediate events - used by common code */
 317         struct tevent_immediate *immediate_events;
 318
 319         /* list of fd events - used by common code */
 320         struct tevent_fd *fd_events;
 321
 322         /* list of timed events - used by common code */
 323         struct tevent_timer *timer_events;
 324
 325         /* List of scheduled immediates */
 326         pthread_mutex_t scheduled_mutex;
 327         struct tevent_immediate *scheduled_immediates;
 328
 329         /* this is private for the events_ops implementation */
 330         void *additional_data;
 331
 332         /* pipe hack used with signal handlers */
 333         struct tevent_fd *wakeup_fde;
 334         int wakeup_fd;          /* fd to write into */
 335 #ifndef HAVE_EVENT_FD
 336         int wakeup_read_fd;
 337 #endif
 338
 339         /* debugging operations */
 340         struct tevent_debug_ops debug_ops;
 341
 342         /* info about the nesting status */
 343         struct {
 344                 bool allowed;
 345                 uint32_t level;
 346                 tevent_nesting_hook hook_fn;
 347                 void *hook_private;
 348         } nesting;
 349
 350         struct {
 351                 struct {
 352                         tevent_trace_callback_t callback;
 353                         void *private_data;
 354                 } point;
 355
 356                 struct {
 357                         tevent_trace_fd_callback_t callback;
 358                         void *private_data;
 359                 } fde;
 360
 361                 struct {
 362                         tevent_trace_signal_callback_t callback;
 363                         void *private_data;
 364                 } se;
 365
 366                 struct {
 367                         tevent_trace_timer_callback_t callback;
 368                         void *private_data;
 369                 } te;
 370
 371                 struct {
 372                         tevent_trace_immediate_callback_t callback;
 373                         void *private_data;
 374                 } im;
 375
 376                 struct {
 377                         tevent_trace_queue_callback_t callback;
 378                         void *private_data;
 379                 } qe;
 380         } tracing;
 381
 382         struct {
 383                 /*
 384                  * This is used on the main event context
 385                  */
 386                 struct tevent_wrapper_glue *list;
 387
 388                 /*
 389                  * This is used on the wrapper event context
 390                  */
 391                 struct tevent_wrapper_glue *glue;
 392         } wrapper;
 393
 394         /*
 395          * an optimization pointer into timer_events
 396          * used by used by common code via
 397          * tevent_common_add_timer_v2()
 398          */
 399         struct tevent_timer *last_zero_timer;
 400
 401 #ifdef HAVE_PTHREAD
 402         struct tevent_context *prev, *next;
 403 #endif
 404 };
 405
 406 int tevent_common_context_destructor(struct tevent_context *ev);
 407 int tevent_common_loop_wait(struct tevent_context *ev,
 408                             const char *location);
 409
 410 int tevent_common_fd_destructor(struct tevent_fd *fde);
 411 struct tevent_fd *tevent_common_add_fd(struct tevent_context *ev,
 412                                        TALLOC_CTX *mem_ctx,
 413                                        int fd,
 414                                        uint16_t flags,
 415                                        tevent_fd_handler_t handler,
 416                                        void *private_data,
 417                                        const char *handler_name,
 418                                        const char *location);
 419 void tevent_common_fd_set_close_fn(struct tevent_fd *fde,
 420                                    tevent_fd_close_fn_t close_fn);
 421 uint16_t tevent_common_fd_get_flags(struct tevent_fd *fde);
 422 void tevent_common_fd_set_flags(struct tevent_fd *fde, uint16_t flags);
 423 int tevent_common_invoke_fd_handler(struct tevent_fd *fde, uint16_t flags,
 424                                     bool *removed);
 425
 426 struct tevent_timer *tevent_common_add_timer(struct tevent_context *ev,
 427                                              TALLOC_CTX *mem_ctx,
 428                                              struct timeval next_event,
 429                                              tevent_timer_handler_t handler,
 430                                              void *private_data,
 431                                              const char *handler_name,
 432                                              const char *location);
 433 struct tevent_timer *tevent_common_add_timer_v2(struct tevent_context *ev,
 434                                                 TALLOC_CTX *mem_ctx,
 435                                                 struct timeval next_event,
 436                                                 tevent_timer_handler_t handler,
 437                                                 void *private_data,
 438                                                 const char *handler_name,
 439                                                 const char *location);
 440 struct timeval tevent_common_loop_timer_delay(struct tevent_context *);
 441 int tevent_common_invoke_timer_handler(struct tevent_timer *te,
 442                                        struct timeval current_time,
 443                                        bool *removed);
 444
 445 void tevent_common_schedule_immediate(struct tevent_immediate *im,
 446                                       struct tevent_context *ev,
 447                                       tevent_immediate_handler_t handler,
 448                                       void *private_data,
 449                                       const char *handler_name,
 450                                       const char *location);
 451 int tevent_common_invoke_immediate_handler(struct tevent_immediate *im,
 452                                            bool *removed);
 453 bool tevent_common_loop_immediate(struct tevent_context *ev);
 454 void tevent_common_threaded_activate_immediate(struct tevent_context *ev);
 455
 456 bool tevent_common_have_events(struct tevent_context *ev);
 457 int tevent_common_wakeup_init(struct tevent_context *ev);
 458 int tevent_common_wakeup_fd(int fd);
 459 int tevent_common_wakeup(struct tevent_context *ev);
 460
 461 struct tevent_signal *tevent_common_add_signal(struct tevent_context *ev,
 462                                                TALLOC_CTX *mem_ctx,
 463                                                int signum,
 464                                                int sa_flags,
 465                                                tevent_signal_handler_t handler,
 466                                                void *private_data,
 467                                                const char *handler_name,
 468                                                const char *location);
 469 int tevent_common_check_signal(struct tevent_context *ev);
 470 void tevent_cleanup_pending_signal_handlers(struct tevent_signal *se);
 471 int tevent_common_invoke_signal_handler(struct tevent_signal *se,
 472                                         int signum, int count, void *siginfo,
 473                                         bool *removed);
 474
 475 struct tevent_context *tevent_wrapper_main_ev(struct tevent_context *ev);
 476
 477 struct tevent_wrapper_ops;
 478
 479 struct tevent_wrapper_glue {
 480         struct tevent_wrapper_glue *prev, *next;
 481         struct tevent_context *wrap_ev;
 482         struct tevent_context *main_ev;
 483         bool busy;
 484         bool destroyed;
 485         const struct tevent_wrapper_ops *ops;
 486         void *private_state;
 487 };
 488
 489 void tevent_wrapper_push_use_internal(struct tevent_context *ev,
 490                                       struct tevent_wrapper_glue *wrapper);
 491 void tevent_wrapper_pop_use_internal(const struct tevent_context *__ev_ptr,
 492                                      struct tevent_wrapper_glue *wrapper);
 493
 494 bool tevent_standard_init(void);
 495 bool tevent_poll_init(void);
 496 bool tevent_poll_event_add_fd_internal(struct tevent_context *ev,
 497                                        struct tevent_fd *fde);
 498 bool tevent_poll_mt_init(void);
 499 #ifdef HAVE_EPOLL
 500 bool tevent_epoll_init(void);
 501 void tevent_epoll_set_panic_fallback(struct tevent_context *ev,
 502                         bool (*panic_fallback)(struct tevent_context *ev,
 503                                                bool replay));
 504 #endif
 505
 506 void tevent_thread_call_depth_set(size_t depth);
 507
 508 void tevent_trace_point_callback(struct tevent_context *ev,
 509                                  enum tevent_trace_point);
 510
 511 void tevent_trace_fd_callback(struct tevent_context *ev,
 512                               struct tevent_fd *fde,
 513                               enum tevent_event_trace_point);
 514
 515 void tevent_trace_signal_callback(struct tevent_context *ev,
 516                                   struct tevent_signal *se,
 517                                   enum tevent_event_trace_point);
 518
 519 void tevent_trace_timer_callback(struct tevent_context *ev,
 520                                  struct tevent_timer *te,
 521                                  enum tevent_event_trace_point);
 522
 523 void tevent_trace_immediate_callback(struct tevent_context *ev,
 524                                      struct tevent_immediate *im,
 525                                      enum tevent_event_trace_point);
 526
 527 void tevent_trace_queue_callback(struct tevent_context *ev,
 528                                  struct tevent_queue_entry *qe,
 529                                  enum tevent_event_trace_point);