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