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 Internal state of the request
  78          *
  79          * Callers should only access this via functions and never directly.
  80          */
  81         struct {
  82                 /**
  83                  * @brief The talloc type of the data pointer
  84                  *
  85                  * This is filled by the tevent_req_create() macro.
  86                  *
  87                  * This for debugging only.
  88                  */
  89                 const char *private_type;
  90
  91                 /**
  92                  * @brief The location where the request was created
  93                  *
  94                  * This uses the __location__ macro via the tevent_req_create()
  95                  * macro.
  96                  *
  97                  * This for debugging only.
  98                  */
  99                 const char *create_location;
 100
 101                 /**
 102                  * @brief The location where the request was finished
 103                  *
 104                  * This uses the __location__ macro via the tevent_req_done(),
 105                  * tevent_req_error() or tevent_req_nomem() macro.
 106                  *
 107                  * This for debugging only.
 108                  */
 109                 const char *finish_location;
 110
 111                 /**
 112                  * @brief The location where the request was canceled
 113                  *
 114                  * This uses the __location__ macro via the
 115                  * tevent_req_cancel() macro.
 116                  *
 117                  * This for debugging only.
 118                  */
 119                 const char *cancel_location;
 120
 121                 /**
 122                  * @brief The external state - will be queried by the caller
 123                  *
 124                  * While the async request is being processed, state will remain in
 125                  * TEVENT_REQ_IN_PROGRESS. A request is finished if
 126                  * req->state>=TEVENT_REQ_DONE.
 127                  */
 128                 enum tevent_req_state state;
 129
 130                 /**
 131                  * @brief status code when finished
 132                  *
 133                  * This status can be queried in the async completion function. It
 134                  * will be set to 0 when everything went fine.
 135                  */
 136                 uint64_t error;
 137
 138                 /**
 139                  * @brief the immediate event used by tevent_req_post
 140                  *
 141                  */
 142                 struct tevent_immediate *trigger;
 143
 144                 /**
 145                  * @brief An event context which will be used to
 146                  *        defer the _tevent_req_notify_callback().
 147                  */
 148                 struct tevent_context *defer_callback_ev;
 149
 150                 /**
 151                  * @brief the timer event if tevent_req_set_endtime was used
 152                  *
 153                  */
 154                 struct tevent_timer *timer;
 155         } internal;
 156 };
 157
 158 struct tevent_fd {
 159         struct tevent_fd *prev, *next;
 160         struct tevent_context *event_ctx;
 161         int fd;
 162         uint16_t flags; /* see TEVENT_FD_* flags */
 163         tevent_fd_handler_t handler;
 164         tevent_fd_close_fn_t close_fn;
 165         /* this is private for the specific handler */
 166         void *private_data;
 167         /* this is for debugging only! */
 168         const char *handler_name;
 169         const char *location;
 170         /* this is private for the events_ops implementation */
 171         uint64_t additional_flags;
 172         void *additional_data;
 173 };
 174
 175 struct tevent_timer {
 176         struct tevent_timer *prev, *next;
 177         struct tevent_context *event_ctx;
 178         struct timeval next_event;
 179         tevent_timer_handler_t handler;
 180         /* this is private for the specific handler */
 181         void *private_data;
 182         /* this is for debugging only! */
 183         const char *handler_name;
 184         const char *location;
 185         /* this is private for the events_ops implementation */
 186         void *additional_data;
 187 };
 188
 189 struct tevent_immediate {
 190         struct tevent_immediate *prev, *next;
 191         struct tevent_context *event_ctx;
 192         tevent_immediate_handler_t handler;
 193         /* this is private for the specific handler */
 194         void *private_data;
 195         /* this is for debugging only! */
 196         const char *handler_name;
 197         const char *create_location;
 198         const char *schedule_location;
 199         /* this is private for the events_ops implementation */
 200         void (*cancel_fn)(struct tevent_immediate *im);
 201         void *additional_data;
 202 };
 203
 204 struct tevent_signal {
 205         struct tevent_signal *prev, *next;
 206         struct tevent_context *event_ctx;
 207         int signum;
 208         int sa_flags;
 209         tevent_signal_handler_t handler;
 210         /* this is private for the specific handler */
 211         void *private_data;
 212         /* this is for debugging only! */
 213         const char *handler_name;
 214         const char *location;
 215         /* this is private for the events_ops implementation */
 216         void *additional_data;
 217 };
 218
 219 struct tevent_debug_ops {
 220         void (*debug)(void *context, enum tevent_debug_level level,
 221                       const char *fmt, va_list ap) PRINTF_ATTRIBUTE(3,0);
 222         void *context;
 223 };
 224
 225 void tevent_debug(struct tevent_context *ev, enum tevent_debug_level level,
 226                   const char *fmt, ...) PRINTF_ATTRIBUTE(3,4);
 227
 228 struct tevent_context {
 229         /* the specific events implementation */
 230         const struct tevent_ops *ops;
 231
 232         /* list of fd events - used by common code */
 233         struct tevent_fd *fd_events;
 234
 235         /* list of timed events - used by common code */
 236         struct tevent_timer *timer_events;
 237
 238         /* list of immediate events - used by common code */
 239         struct tevent_immediate *immediate_events;
 240
 241         /* list of signal events - used by common code */
 242         struct tevent_signal *signal_events;
 243
 244         /* this is private for the events_ops implementation */
 245         void *additional_data;
 246
 247         /* pipe hack used with signal handlers */
 248         struct tevent_fd *pipe_fde;
 249         int pipe_fds[2];
 250
 251         /* debugging operations */
 252         struct tevent_debug_ops debug_ops;
 253
 254         /* info about the nesting status */
 255         struct {
 256                 bool allowed;
 257                 uint32_t level;
 258                 tevent_nesting_hook hook_fn;
 259                 void *hook_private;
 260         } nesting;
 261
 262         struct {
 263                 tevent_trace_callback_t callback;
 264                 void *private_data;
 265         } tracing;
 266
 267         /*
 268          * an optimization pointer into timer_events
 269          * used by used by common code via
 270          * tevent_common_add_timer_v2()
 271          */
 272         struct tevent_timer *last_zero_timer;
 273 };
 274
 275 const struct tevent_ops *tevent_find_ops_byname(const char *name);
 276
 277 int tevent_common_context_destructor(struct tevent_context *ev);
 278 int tevent_common_loop_wait(struct tevent_context *ev,
 279                             const char *location);
 280
 281 int tevent_common_fd_destructor(struct tevent_fd *fde);
 282 struct tevent_fd *tevent_common_add_fd(struct tevent_context *ev,
 283                                        TALLOC_CTX *mem_ctx,
 284                                        int fd,
 285                                        uint16_t flags,
 286                                        tevent_fd_handler_t handler,
 287                                        void *private_data,
 288                                        const char *handler_name,
 289                                        const char *location);
 290 void tevent_common_fd_set_close_fn(struct tevent_fd *fde,
 291                                    tevent_fd_close_fn_t close_fn);
 292 uint16_t tevent_common_fd_get_flags(struct tevent_fd *fde);
 293 void tevent_common_fd_set_flags(struct tevent_fd *fde, uint16_t flags);
 294
 295 struct tevent_timer *tevent_common_add_timer(struct tevent_context *ev,
 296                                              TALLOC_CTX *mem_ctx,
 297                                              struct timeval next_event,
 298                                              tevent_timer_handler_t handler,
 299                                              void *private_data,
 300                                              const char *handler_name,
 301                                              const char *location);
 302 struct tevent_timer *tevent_common_add_timer_v2(struct tevent_context *ev,
 303                                                 TALLOC_CTX *mem_ctx,
 304                                                 struct timeval next_event,
 305                                                 tevent_timer_handler_t handler,
 306                                                 void *private_data,
 307                                                 const char *handler_name,
 308                                                 const char *location);
 309 struct timeval tevent_common_loop_timer_delay(struct tevent_context *);
 310
 311 void tevent_common_schedule_immediate(struct tevent_immediate *im,
 312                                       struct tevent_context *ev,
 313                                       tevent_immediate_handler_t handler,
 314                                       void *private_data,
 315                                       const char *handler_name,
 316                                       const char *location);
 317 bool tevent_common_loop_immediate(struct tevent_context *ev);
 318
 319 struct tevent_signal *tevent_common_add_signal(struct tevent_context *ev,
 320                                                TALLOC_CTX *mem_ctx,
 321                                                int signum,
 322                                                int sa_flags,
 323                                                tevent_signal_handler_t handler,
 324                                                void *private_data,
 325                                                const char *handler_name,
 326                                                const char *location);
 327 int tevent_common_check_signal(struct tevent_context *ev);
 328 void tevent_cleanup_pending_signal_handlers(struct tevent_signal *se);
 329
 330 bool tevent_standard_init(void);
 331 bool tevent_select_init(void);
 332 bool tevent_poll_init(void);
 333 void tevent_poll_event_add_fd_internal(struct tevent_context *ev,
 334                                        struct tevent_fd *fde);
 335 bool tevent_poll_mt_init(void);
 336 #ifdef HAVE_EPOLL
 337 bool tevent_epoll_init(void);
 338 bool tevent_epoll_set_panic_fallback(struct tevent_context *ev,
 339                         bool (*panic_fallback)(struct tevent_context *ev,
 340                                                bool replay));
 341 #endif
 342
 343
 344 void tevent_trace_point_callback(struct tevent_context *ev,
 345                                  enum tevent_trace_point);