source4/lib/events/events.c

   1 /*
   2    Unix SMB/CIFS implementation.
   3    main select loop and event handling
   4    Copyright (C) Andrew Tridgell 2003
   5
   6    This program is free software; you can redistribute it and/or modify
   7    it under the terms of the GNU General Public License as published by
   8    the Free Software Foundation; either version 3 of the License, or
   9    (at your option) any later version.
  10
  11    This program is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14    GNU General Public License for more details.
  15
  16    You should have received a copy of the GNU General Public License
  17    along with this program.  If not, see <http://www.gnu.org/licenses/>.
  18 */
  19
  20 /*
  21   PLEASE READ THIS BEFORE MODIFYING!
  22
  23   This module is a general abstraction for the main select loop and
  24   event handling. Do not ever put any localised hacks in here, instead
  25   register one of the possible event types and implement that event
  26   somewhere else.
  27
  28   There are 2 types of event handling that are handled in this module:
  29
  30   1) a file descriptor becoming readable or writeable. This is mostly
  31      used for network sockets, but can be used for any type of file
  32      descriptor. You may only register one handler for each file
  33      descriptor/io combination or you will get unpredictable results
  34      (this means that you can have a handler for read events, and a
  35      separate handler for write events, but not two handlers that are
  36      both handling read events)
  37
  38   2) a timed event. You can register an event that happens at a
  39      specific time.  You can register as many of these as you
  40      like. They are single shot - add a new timed event in the event
  41      handler to get another event.
  42
  43   To setup a set of events you first need to create a event_context
  44   structure using the function event_context_init(); This returns a
  45   'struct event_context' that you use in all subsequent calls.
  46
  47   After that you can add/remove events that you are interested in
  48   using event_add_*() and talloc_free()
  49
  50   Finally, you call event_loop_wait_once() to block waiting for one of the
  51   events to occor or event_loop_wait() which will loop
  52   forever.
  53
  54 */
  55
  56 #include "includes.h"
  57 #include "lib/events/events.h"
  58 #include "lib/events/events_internal.h"
  59 #include "lib/util/dlinklist.h"
  60 #include "param/param.h"
  61
  62 struct event_ops_list {
  63         struct event_ops_list *next, *prev;
  64         const char *name;
  65         const struct event_ops *ops;
  66 };
  67
  68 /* list of registered event backends */
  69 static struct event_ops_list *event_backends;
  70
  71 static char *event_default_backend = NULL;
  72
  73 /*
  74   register an events backend
  75 */
  76 bool event_register_backend(const char *name, const struct event_ops *ops)
  77 {
  78         struct event_ops_list *e;
  79         e = talloc(talloc_autofree_context(), struct event_ops_list);
  80         if (e == NULL) return false;
  81         e->name = name;
  82         e->ops = ops;
  83         DLIST_ADD(event_backends, e);
  84         return true;
  85 }
  86
  87 /*
  88   set the default event backend
  89  */
  90 void event_set_default_backend(const char *backend)
  91 {
  92         if (event_default_backend) free(event_default_backend);
  93         event_default_backend = strdup(backend);
  94 }
  95
  96 /*
  97   initialise backends if not already done
  98 */
  99 static void event_backend_init(void)
 100 {
 101 #if _SAMBA_BUILD_
 102         NTSTATUS s4_events_standard_init(void);
 103         NTSTATUS s4_events_select_init(void);
 104         NTSTATUS s4_events_epoll_init(void);
 105         NTSTATUS s4_events_aio_init(void);
 106         init_module_fn static_init[] = { STATIC_LIBEVENTS_MODULES };
 107         if (event_backends) return;
 108         run_init_functions(static_init);
 109 #else
 110         bool events_standard_init(void);
 111         bool events_select_init(void);
 112         events_select_init();
 113         events_standard_init();
 114 #if HAVE_EVENTS_EPOLL
 115         {
 116                 bool events_epoll_init(void);
 117                 events_epoll_init();
 118         }
 119 #endif
 120 #endif
 121 }
 122
 123 /*
 124   list available backends
 125 */
 126 const char **event_backend_list(TALLOC_CTX *mem_ctx)
 127 {
 128         const char **list = NULL;
 129         struct event_ops_list *e;
 130
 131         event_backend_init();
 132
 133         for (e=event_backends;e;e=e->next) {
 134                 list = str_list_add(list, e->name);
 135         }
 136
 137         talloc_steal(mem_ctx, list);
 138
 139         return list;
 140 }
 141
 142 /*
 143   create a event_context structure for a specific implemementation.
 144   This must be the first events call, and all subsequent calls pass
 145   this event_context as the first element. Event handlers also
 146   receive this as their first argument.
 147
 148   This function is for allowing third-party-applications to hook in gluecode
 149   to their own event loop code, so that they can make async usage of our client libs
 150
 151   NOTE: use event_context_init() inside of samba!
 152 */
 153 static struct event_context *event_context_init_ops(TALLOC_CTX *mem_ctx,
 154                                                     const struct event_ops *ops)
 155 {
 156         struct event_context *ev;
 157         int ret;
 158
 159         ev = talloc_zero(mem_ctx, struct event_context);
 160         if (!ev) return NULL;
 161
 162         ev->ops = ops;
 163
 164         ret = ev->ops->context_init(ev);
 165         if (ret != 0) {
 166                 talloc_free(ev);
 167                 return NULL;
 168         }
 169
 170         return ev;
 171 }
 172
 173 /*
 174   create a event_context structure. This must be the first events
 175   call, and all subsequent calls pass this event_context as the first
 176   element. Event handlers also receive this as their first argument.
 177 */
 178 struct event_context *event_context_init_byname(TALLOC_CTX *mem_ctx, const char *name)
 179 {
 180         struct event_ops_list *e;
 181
 182         event_backend_init();
 183
 184         if (name == NULL) {
 185                 name = event_default_backend;
 186         }
 187         if (name == NULL) {
 188                 name = "standard";
 189         }
 190
 191         for (e=event_backends;e;e=e->next) {
 192                 if (strcmp(name, e->name) == 0) {
 193                         return event_context_init_ops(mem_ctx, e->ops);
 194                 }
 195         }
 196         return NULL;
 197 }
 198
 199
 200 /*
 201   create a event_context structure. This must be the first events
 202   call, and all subsequent calls pass this event_context as the first
 203   element. Event handlers also receive this as their first argument.
 204 */
 205 struct event_context *event_context_init(TALLOC_CTX *mem_ctx)
 206 {
 207         return event_context_init_byname(mem_ctx, NULL);
 208 }
 209
 210 /*
 211   add a fd based event
 212   return NULL on failure (memory allocation error)
 213
 214   if flags contains EVENT_FD_AUTOCLOSE then the fd will be closed when
 215   the returned fd_event context is freed
 216 */
 217 struct fd_event *event_add_fd(struct event_context *ev, TALLOC_CTX *mem_ctx,
 218                               int fd, uint16_t flags, event_fd_handler_t handler,
 219                               void *private_data)
 220 {
 221         return ev->ops->add_fd(ev, mem_ctx, fd, flags, handler, private_data);
 222 }
 223
 224 /*
 225   add a disk aio event
 226 */
 227 struct aio_event *event_add_aio(struct event_context *ev,
 228                                 TALLOC_CTX *mem_ctx,
 229                                 struct iocb *iocb,
 230                                 event_aio_handler_t handler,
 231                                 void *private_data)
 232 {
 233         if (ev->ops->add_aio == NULL) return NULL;
 234         return ev->ops->add_aio(ev, mem_ctx, iocb, handler, private_data);
 235 }
 236
 237 /*
 238   return the fd event flags
 239 */
 240 uint16_t event_get_fd_flags(struct fd_event *fde)
 241 {
 242         if (!fde) return 0;
 243         return fde->event_ctx->ops->get_fd_flags(fde);
 244 }
 245
 246 /*
 247   set the fd event flags
 248 */
 249 void event_set_fd_flags(struct fd_event *fde, uint16_t flags)
 250 {
 251         if (!fde) return;
 252         fde->event_ctx->ops->set_fd_flags(fde, flags);
 253 }
 254
 255 /*
 256   add a timed event
 257   return NULL on failure
 258 */
 259 struct timed_event *event_add_timed(struct event_context *ev, TALLOC_CTX *mem_ctx,
 260                                     struct timeval next_event,
 261                                     event_timed_handler_t handler,
 262                                     void *private_data)
 263 {
 264         return ev->ops->add_timed(ev, mem_ctx, next_event, handler, private_data);
 265 }
 266
 267 /*
 268   add a signal event
 269
 270   sa_flags are flags to sigaction(2)
 271
 272   return NULL on failure
 273 */
 274 struct signal_event *event_add_signal(struct event_context *ev, TALLOC_CTX *mem_ctx,
 275                                       int signum,
 276                                       int sa_flags,
 277                                       event_signal_handler_t handler,
 278                                       void *private_data)
 279 {
 280         return ev->ops->add_signal(ev, mem_ctx, signum, sa_flags, handler, private_data);
 281 }
 282
 283 /*
 284   do a single event loop using the events defined in ev
 285 */
 286 _PUBLIC_ int event_loop_once(struct event_context *ev)
 287 {
 288         return ev->ops->loop_once(ev);
 289 }
 290
 291 /*
 292   return on failure or (with 0) if all fd events are removed
 293 */
 294 int event_loop_wait(struct event_context *ev)
 295 {
 296         return ev->ops->loop_wait(ev);
 297 }
 298
 299 /*
 300   find an event context that is a parent of the given memory context,
 301   or create a new event context as a child of the given context if
 302   none is found
 303
 304   This should be used in preference to event_context_init() in places
 305   where you would prefer to use the existing event context if possible
 306   (which is most situations)
 307 */
 308 struct event_context *event_context_find(TALLOC_CTX *mem_ctx)
 309 {
 310         struct event_context *ev = talloc_find_parent_bytype(mem_ctx, struct event_context);
 311         if (ev == NULL) {
 312                 ev = event_context_init(mem_ctx);
 313         }
 314         return ev;
 315 }