lib/tevent/tevent_internal.h

   1 /*
   2    Unix SMB/CIFS implementation.
   3
   4    generalised event loop handling
   5
   6    Internal structs
   7
   8    Copyright (C) Stefan Metzmacher 2005-2009
   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 struct tevent_req {
  29         /**
  30          * @brief What to do on completion
  31          *
  32          * This is used for the user of an async request, fn is called when
  33          * the request completes, either successfully or with an error.
  34          */
  35         struct {
  36                 /**
  37                  * @brief Completion function
  38                  * Completion function, to be filled by the API user
  39                  */
  40                 tevent_req_fn fn;
  41                 /**
  42                  * @brief Private data for the completion function
  43                  */
  44                 void *private_data;
  45         } async;
  46
  47         /**
  48          * @brief Private state pointer for the actual implementation
  49          *
  50          * The implementation doing the work for the async request needs to
  51          * keep around current data like for example a fd event. The user of
  52          * an async request should not touch this.
  53          */
  54         void *data;
  55
  56         /**
  57          * @brief A function to overwrite the default print function
  58          *
  59          * The implementation doing the work may want to implement a
  60          * custom function to print the text representation of the async
  61          * request.
  62          */
  63         tevent_req_print_fn private_print;
  64
  65         /**
  66          * @brief Internal state of the request
  67          *
  68          * Callers should only access this via functions and never directly.
  69          */
  70         struct {
  71                 /**
  72                  * @brief The talloc type of the data pointer
  73                  *
  74                  * This is filled by the tevent_req_create() macro.
  75                  *
  76                  * This for debugging only.
  77                  */
  78                 const char *private_type;
  79
  80                 /**
  81                  * @brief The location where the request was created
  82                  *
  83                  * This uses the __location__ macro via the tevent_req_create()
  84                  * macro.
  85                  *
  86                  * This for debugging only.
  87                  */
  88                 const char *create_location;
  89
  90                 /**
  91                  * @brief The location where the request was finished
  92                  *
  93                  * This uses the __location__ macro via the tevent_req_done(),
  94                  * tevent_req_error() or tevent_req_nomem() macro.
  95                  *
  96                  * This for debugging only.
  97                  */
  98                 const char *finish_location;
  99
 100                 /**
 101                  * @brief The external state - will be queried by the caller
 102                  *
 103                  * While the async request is being processed, state will remain in
 104                  * TEVENT_REQ_IN_PROGRESS. A request is finished if
 105                  * req->state>=TEVENT_REQ_DONE.
 106                  */
 107                 enum tevent_req_state state;
 108
 109                 /**
 110                  * @brief status code when finished
 111                  *
 112                  * This status can be queried in the async completion function. It
 113                  * will be set to 0 when everything went fine.
 114                  */
 115                 uint64_t error;
 116
 117                 /**
 118                  * @brief the immediate event used by tevent_req_post
 119                  *
 120                  */
 121                 struct tevent_immediate *trigger;
 122
 123                 /**
 124                  * @brief the timer event if tevent_req_set_timeout was used
 125                  *
 126                  */
 127                 struct tevent_timer *timer;
 128         } internal;
 129 };
 130
 131 struct tevent_ops {
 132         /* conntext init */
 133         int (*context_init)(struct tevent_context *ev);
 134
 135         /* fd_event functions */
 136         struct tevent_fd *(*add_fd)(struct tevent_context *ev,
 137                                     TALLOC_CTX *mem_ctx,
 138                                     int fd, uint16_t flags,
 139                                     tevent_fd_handler_t handler,
 140                                     void *private_data,
 141                                     const char *handler_name,
 142                                     const char *location);
 143         void (*set_fd_close_fn)(struct tevent_fd *fde,
 144                                 tevent_fd_close_fn_t close_fn);
 145         uint16_t (*get_fd_flags)(struct tevent_fd *fde);
 146         void (*set_fd_flags)(struct tevent_fd *fde, uint16_t flags);
 147
 148         /* timed_event functions */
 149         struct tevent_timer *(*add_timer)(struct tevent_context *ev,
 150                                           TALLOC_CTX *mem_ctx,
 151                                           struct timeval next_event,
 152                                           tevent_timer_handler_t handler,
 153                                           void *private_data,
 154                                           const char *handler_name,
 155                                           const char *location);
 156
 157         /* immediate event functions */
 158         void (*schedule_immediate)(struct tevent_immediate *im,
 159                                    struct tevent_context *ev,
 160                                    tevent_immediate_handler_t handler,
 161                                    void *private_data,
 162                                    const char *handler_name,
 163                                    const char *location);
 164
 165         /* signal functions */
 166         struct tevent_signal *(*add_signal)(struct tevent_context *ev,
 167                                             TALLOC_CTX *mem_ctx,
 168                                             int signum, int sa_flags,
 169                                             tevent_signal_handler_t handler,
 170                                             void *private_data,
 171                                             const char *handler_name,
 172                                             const char *location);
 173
 174         /* loop functions */
 175         int (*loop_once)(struct tevent_context *ev, const char *location);
 176         int (*loop_wait)(struct tevent_context *ev, const char *location);
 177 };
 178
 179 struct tevent_fd {
 180         struct tevent_fd *prev, *next;
 181         struct tevent_context *event_ctx;
 182         int fd;
 183         uint16_t flags; /* see TEVENT_FD_* flags */
 184         tevent_fd_handler_t handler;
 185         tevent_fd_close_fn_t close_fn;
 186         /* this is private for the specific handler */
 187         void *private_data;
 188         /* this is for debugging only! */
 189         const char *handler_name;
 190         const char *location;
 191         /* this is private for the events_ops implementation */
 192         uint16_t additional_flags;
 193         void *additional_data;
 194 };
 195
 196 struct tevent_timer {
 197         struct tevent_timer *prev, *next;
 198         struct tevent_context *event_ctx;
 199         struct timeval next_event;
 200         tevent_timer_handler_t handler;
 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         void *additional_data;
 208 };
 209
 210 struct tevent_immediate {
 211         struct tevent_immediate *prev, *next;
 212         struct tevent_context *event_ctx;
 213         tevent_immediate_handler_t handler;
 214         /* this is private for the specific handler */
 215         void *private_data;
 216         /* this is for debugging only! */
 217         const char *handler_name;
 218         const char *create_location;
 219         const char *schedule_location;
 220         /* this is private for the events_ops implementation */
 221         void (*cancel_fn)(struct tevent_immediate *im);
 222         void *additional_data;
 223 };
 224
 225 struct tevent_signal {
 226         struct tevent_signal *prev, *next;
 227         struct tevent_context *event_ctx;
 228         int signum;
 229         int sa_flags;
 230         tevent_signal_handler_t handler;
 231         /* this is private for the specific handler */
 232         void *private_data;
 233         /* this is for debugging only! */
 234         const char *handler_name;
 235         const char *location;
 236         /* this is private for the events_ops implementation */
 237         void *additional_data;
 238 };
 239
 240 struct tevent_debug_ops {
 241         void (*debug)(void *context, enum tevent_debug_level level,
 242                       const char *fmt, va_list ap) PRINTF_ATTRIBUTE(3,0);
 243         void *context;
 244 };
 245
 246 void tevent_debug(struct tevent_context *ev, enum tevent_debug_level level,
 247                   const char *fmt, ...) PRINTF_ATTRIBUTE(3,4);
 248
 249 struct tevent_context {
 250         /* the specific events implementation */
 251         const struct tevent_ops *ops;
 252
 253         /* list of fd events - used by common code */
 254         struct tevent_fd *fd_events;
 255
 256         /* list of timed events - used by common code */
 257         struct tevent_timer *timer_events;
 258
 259         /* list of immediate events - used by common code */
 260         struct tevent_immediate *immediate_events;
 261
 262         /* list of signal events - used by common code */
 263         struct tevent_signal *signal_events;
 264
 265         /* this is private for the events_ops implementation */
 266         void *additional_data;
 267
 268         /* pipe hack used with signal handlers */
 269         struct tevent_fd *pipe_fde;
 270
 271         /* debugging operations */
 272         struct tevent_debug_ops debug_ops;
 273
 274         /* info about the nesting status */
 275         struct {
 276                 bool allowed;
 277                 uint32_t level;
 278                 tevent_nesting_hook hook_fn;
 279                 void *hook_private;
 280         } nesting;
 281 };
 282
 283
 284 bool tevent_register_backend(const char *name, const struct tevent_ops *ops);
 285
 286 int tevent_common_context_destructor(struct tevent_context *ev);
 287 int tevent_common_loop_wait(struct tevent_context *ev,
 288                             const char *location);
 289
 290 int tevent_common_fd_destructor(struct tevent_fd *fde);
 291 struct tevent_fd *tevent_common_add_fd(struct tevent_context *ev,
 292                                        TALLOC_CTX *mem_ctx,
 293                                        int fd,
 294                                        uint16_t flags,
 295                                        tevent_fd_handler_t handler,
 296                                        void *private_data,
 297                                        const char *handler_name,
 298                                        const char *location);
 299 void tevent_common_fd_set_close_fn(struct tevent_fd *fde,
 300                                    tevent_fd_close_fn_t close_fn);
 301 uint16_t tevent_common_fd_get_flags(struct tevent_fd *fde);
 302 void tevent_common_fd_set_flags(struct tevent_fd *fde, uint16_t flags);
 303
 304 struct tevent_timer *tevent_common_add_timer(struct tevent_context *ev,
 305                                              TALLOC_CTX *mem_ctx,
 306                                              struct timeval next_event,
 307                                              tevent_timer_handler_t handler,
 308                                              void *private_data,
 309                                              const char *handler_name,
 310                                              const char *location);
 311 struct timeval tevent_common_loop_timer_delay(struct tevent_context *);
 312
 313 void tevent_common_schedule_immediate(struct tevent_immediate *im,
 314                                       struct tevent_context *ev,
 315                                       tevent_immediate_handler_t handler,
 316                                       void *private_data,
 317                                       const char *handler_name,
 318                                       const char *location);
 319 bool tevent_common_loop_immediate(struct tevent_context *ev);
 320
 321 struct tevent_signal *tevent_common_add_signal(struct tevent_context *ev,
 322                                                TALLOC_CTX *mem_ctx,
 323                                                int signum,
 324                                                int sa_flags,
 325                                                tevent_signal_handler_t handler,
 326                                                void *private_data,
 327                                                const char *handler_name,
 328                                                const char *location);
 329 int tevent_common_check_signal(struct tevent_context *ev);
 330
 331 bool tevent_standard_init(void);
 332 bool tevent_select_init(void);
 333 #ifdef HAVE_EPOLL
 334 bool tevent_epoll_init(void);
 335 #endif