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