2 Unix SMB/CIFS implementation.
3 main select loop and event handling
4 Copyright (C) Andrew Tridgell 2003
5 Copyright (C) Stefan Metzmacher 2009
7 ** NOTE! The following LGPL license applies to the tevent
8 ** library. This does NOT imply that all of Samba is released
11 This library is free software; you can redistribute it and/or
12 modify it under the terms of the GNU Lesser General Public
13 License as published by the Free Software Foundation; either
14 version 3 of the License, or (at your option) any later version.
16 This library is distributed in the hope that it will be useful,
17 but WITHOUT ANY WARRANTY; without even the implied warranty of
18 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 Lesser General Public License for more details.
21 You should have received a copy of the GNU Lesser General Public
22 License along with this library; if not, see <http://www.gnu.org/licenses/>.
26 PLEASE READ THIS BEFORE MODIFYING!
28 This module is a general abstraction for the main select loop and
29 event handling. Do not ever put any localised hacks in here, instead
30 register one of the possible event types and implement that event
33 There are 2 types of event handling that are handled in this module:
35 1) a file descriptor becoming readable or writeable. This is mostly
36 used for network sockets, but can be used for any type of file
37 descriptor. You may only register one handler for each file
38 descriptor/io combination or you will get unpredictable results
39 (this means that you can have a handler for read events, and a
40 separate handler for write events, but not two handlers that are
41 both handling read events)
43 2) a timed event. You can register an event that happens at a
44 specific time. You can register as many of these as you
45 like. They are single shot - add a new timed event in the event
46 handler to get another event.
48 To setup a set of events you first need to create a event_context
49 structure using the function tevent_context_init(); This returns a
50 'struct tevent_context' that you use in all subsequent calls.
52 After that you can add/remove events that you are interested in
53 using tevent_add_*() and talloc_free()
55 Finally, you call tevent_loop_wait_once() to block waiting for one of the
56 events to occor or tevent_loop_wait() which will loop
60 #include <ccan/tevent/tevent.h>
61 #include <ccan/tevent/tevent_internal.h>
62 #include <ccan/tevent/tevent_util.h>
67 struct tevent_ops_list {
68 struct tevent_ops_list *next, *prev;
70 const struct tevent_ops *ops;
73 /* list of registered event backends */
74 static struct tevent_ops_list *tevent_backends = NULL;
75 static char *tevent_default_backend = NULL;
78 register an events backend
80 bool tevent_register_backend(const char *name, const struct tevent_ops *ops)
82 struct tevent_ops_list *e;
84 for (e = tevent_backends; e != NULL; e = e->next) {
85 if (0 == strcmp(e->name, name)) {
86 /* already registered, skip it */
91 e = talloc(NULL, struct tevent_ops_list);
92 if (e == NULL) return false;
96 DLIST_ADD(tevent_backends, e);
102 set the default event backend
104 void tevent_set_default_backend(const char *backend)
106 talloc_free(tevent_default_backend);
107 tevent_default_backend = talloc_strdup(NULL, backend);
111 initialise backends if not already done
113 static void tevent_backend_init(void)
115 tevent_select_init();
116 tevent_standard_init();
123 list available backends
125 const char **tevent_backend_list(TALLOC_CTX *mem_ctx)
127 const char **list = NULL;
128 struct tevent_ops_list *e;
130 tevent_backend_init();
132 for (e=tevent_backends;e;e=e->next) {
133 list = ev_str_list_add(list, e->name);
136 talloc_steal(mem_ctx, list);
141 int tevent_common_context_destructor(struct tevent_context *ev)
143 struct tevent_fd *fd, *fn;
144 struct tevent_timer *te, *tn;
145 struct tevent_immediate *ie, *in;
146 struct tevent_signal *se, *sn;
149 talloc_free(ev->pipe_fde);
150 close(ev->pipe_fds[0]);
151 close(ev->pipe_fds[1]);
155 for (fd = ev->fd_events; fd; fd = fn) {
157 fd->event_ctx = NULL;
158 DLIST_REMOVE(ev->fd_events, fd);
161 for (te = ev->timer_events; te; te = tn) {
163 te->event_ctx = NULL;
164 DLIST_REMOVE(ev->timer_events, te);
167 for (ie = ev->immediate_events; ie; ie = in) {
169 ie->event_ctx = NULL;
170 ie->cancel_fn = NULL;
171 DLIST_REMOVE(ev->immediate_events, ie);
174 for (se = ev->signal_events; se; se = sn) {
176 se->event_ctx = NULL;
177 DLIST_REMOVE(ev->signal_events, se);
179 * This is important, Otherwise signals
180 * are handled twice in child. eg, SIGHUP.
181 * one added in parent, and another one in
182 * the child. -- BoYang
184 tevent_cleanup_pending_signal_handlers(se);
191 create a event_context structure for a specific implemementation.
192 This must be the first events call, and all subsequent calls pass
193 this event_context as the first element. Event handlers also
194 receive this as their first argument.
196 This function is for allowing third-party-applications to hook in gluecode
197 to their own event loop code, so that they can make async usage of our client libs
199 NOTE: use tevent_context_init() inside of samba!
201 static struct tevent_context *tevent_context_init_ops(TALLOC_CTX *mem_ctx,
202 const struct tevent_ops *ops)
204 struct tevent_context *ev;
207 ev = talloc_zero(mem_ctx, struct tevent_context);
208 if (!ev) return NULL;
210 talloc_set_destructor(ev, tevent_common_context_destructor);
214 ret = ev->ops->context_init(ev);
224 create a event_context structure. This must be the first events
225 call, and all subsequent calls pass this event_context as the first
226 element. Event handlers also receive this as their first argument.
228 struct tevent_context *tevent_context_init_byname(TALLOC_CTX *mem_ctx,
231 struct tevent_ops_list *e;
233 tevent_backend_init();
236 name = tevent_default_backend;
242 for (e=tevent_backends;e;e=e->next) {
243 if (strcmp(name, e->name) == 0) {
244 return tevent_context_init_ops(mem_ctx, e->ops);
252 create a event_context structure. This must be the first events
253 call, and all subsequent calls pass this event_context as the first
254 element. Event handlers also receive this as their first argument.
256 struct tevent_context *tevent_context_init(TALLOC_CTX *mem_ctx)
258 return tevent_context_init_byname(mem_ctx, NULL);
263 return NULL on failure (memory allocation error)
265 struct tevent_fd *_tevent_add_fd(struct tevent_context *ev,
269 tevent_fd_handler_t handler,
271 const char *handler_name,
272 const char *location)
274 return ev->ops->add_fd(ev, mem_ctx, fd, flags, handler, private_data,
275 handler_name, location);
279 set a close function on the fd event
281 void tevent_fd_set_close_fn(struct tevent_fd *fde,
282 tevent_fd_close_fn_t close_fn)
285 if (!fde->event_ctx) return;
286 fde->event_ctx->ops->set_fd_close_fn(fde, close_fn);
289 static void tevent_fd_auto_close_fn(struct tevent_context *ev,
290 struct tevent_fd *fde,
297 void tevent_fd_set_auto_close(struct tevent_fd *fde)
299 tevent_fd_set_close_fn(fde, tevent_fd_auto_close_fn);
303 return the fd event flags
305 uint16_t tevent_fd_get_flags(struct tevent_fd *fde)
308 if (!fde->event_ctx) return 0;
309 return fde->event_ctx->ops->get_fd_flags(fde);
313 set the fd event flags
315 void tevent_fd_set_flags(struct tevent_fd *fde, uint16_t flags)
318 if (!fde->event_ctx) return;
319 fde->event_ctx->ops->set_fd_flags(fde, flags);
322 bool tevent_signal_support(struct tevent_context *ev)
324 if (ev->ops->add_signal) {
330 static void (*tevent_abort_fn)(const char *reason);
332 void tevent_set_abort_fn(void (*abort_fn)(const char *reason))
334 tevent_abort_fn = abort_fn;
339 return NULL on failure
341 struct tevent_timer *_tevent_add_timer(struct tevent_context *ev,
343 struct timeval next_event,
344 tevent_timer_handler_t handler,
346 const char *handler_name,
347 const char *location)
349 return ev->ops->add_timer(ev, mem_ctx, next_event, handler, private_data,
350 handler_name, location);
354 allocate an immediate event
355 return NULL on failure (memory allocation error)
357 struct tevent_immediate *_tevent_create_immediate(TALLOC_CTX *mem_ctx,
358 const char *location)
360 struct tevent_immediate *im;
362 im = talloc(mem_ctx, struct tevent_immediate);
363 if (im == NULL) return NULL;
367 im->event_ctx = NULL;
368 im->create_location = location;
370 im->private_data = NULL;
371 im->handler_name = NULL;
372 im->schedule_location = NULL;
373 im->cancel_fn = NULL;
374 im->additional_data = NULL;
380 schedule an immediate event
381 return NULL on failure
383 void _tevent_schedule_immediate(struct tevent_immediate *im,
384 struct tevent_context *ev,
385 tevent_immediate_handler_t handler,
387 const char *handler_name,
388 const char *location)
390 ev->ops->schedule_immediate(im, ev, handler, private_data,
391 handler_name, location);
397 sa_flags are flags to sigaction(2)
399 return NULL on failure
401 struct tevent_signal *_tevent_add_signal(struct tevent_context *ev,
405 tevent_signal_handler_t handler,
407 const char *handler_name,
408 const char *location)
410 return ev->ops->add_signal(ev, mem_ctx, signum, sa_flags, handler, private_data,
411 handler_name, location);
415 do a single event loop using the events defined in ev
417 int _tevent_loop_once(struct tevent_context *ev, const char *location)
419 return ev->ops->loop_once(ev, location);
423 return on failure or (with 0) if all fd events are removed
425 int tevent_common_loop_wait(struct tevent_context *ev,
426 const char *location)
429 * loop as long as we have events pending
431 while (ev->fd_events ||
433 ev->immediate_events ||
436 ret = _tevent_loop_once(ev, location);
438 tevent_debug(ev, TEVENT_DEBUG_FATAL,
439 "_tevent_loop_once() failed: %d - %s\n",
440 ret, strerror(errno));
445 tevent_debug(ev, TEVENT_DEBUG_WARNING,
446 "tevent_common_loop_wait() out of events\n");
451 return on failure or (with 0) if all fd events are removed
453 int _tevent_loop_wait(struct tevent_context *ev, const char *location)
455 return ev->ops->loop_wait(ev, location);