185a8fa193e3f2d47dea546f43c01a507a271c94
[ira/wip.git] / lib / tevent / tevent.h
1 /* 
2    Unix SMB/CIFS implementation.
3
4    generalised event loop handling
5
6    Copyright (C) Andrew Tridgell 2005
7    Copyright (C) Stefan Metzmacher 2005-2009
8    Copyright (C) Volker Lendecke 2008
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 #ifndef __TEVENT_H__
29 #define __TEVENT_H__
30
31 #include <stdint.h>
32 #include <talloc.h>
33 #include <sys/time.h>
34 #include <stdbool.h>
35
36 struct tevent_context;
37 struct tevent_ops;
38 struct tevent_fd;
39 struct tevent_timer;
40 struct tevent_signal;
41
42 /* event handler types */
43 typedef void (*tevent_fd_handler_t)(struct tevent_context *ev,
44                                     struct tevent_fd *fde,
45                                     uint16_t flags,
46                                     void *private_data);
47 typedef void (*tevent_fd_close_fn_t)(struct tevent_context *ev,
48                                      struct tevent_fd *fde,
49                                      int fd,
50                                      void *private_data);
51 typedef void (*tevent_timer_handler_t)(struct tevent_context *ev,
52                                        struct tevent_timer *te,
53                                        struct timeval current_time,
54                                        void *private_data);
55 typedef void (*tevent_signal_handler_t)(struct tevent_context *ev,
56                                         struct tevent_signal *se,
57                                         int signum,
58                                         int count,
59                                         void *siginfo,
60                                         void *private_data);
61
62 struct tevent_context *tevent_context_init(TALLOC_CTX *mem_ctx);
63 struct tevent_context *tevent_context_init_byname(TALLOC_CTX *mem_ctx, const char *name);
64 const char **tevent_backend_list(TALLOC_CTX *mem_ctx);
65 void tevent_set_default_backend(const char *backend);
66
67 struct tevent_fd *_tevent_add_fd(struct tevent_context *ev,
68                                  TALLOC_CTX *mem_ctx,
69                                  int fd,
70                                  uint16_t flags,
71                                  tevent_fd_handler_t handler,
72                                  void *private_data,
73                                  const char *handler_name,
74                                  const char *location);
75 #define tevent_add_fd(ev, mem_ctx, fd, flags, handler, private_data) \
76         _tevent_add_fd(ev, mem_ctx, fd, flags, handler, private_data, \
77                        #handler, __location__)
78
79 struct tevent_timer *_tevent_add_timer(struct tevent_context *ev,
80                                        TALLOC_CTX *mem_ctx,
81                                        struct timeval next_event,
82                                        tevent_timer_handler_t handler,
83                                        void *private_data,
84                                        const char *handler_name,
85                                        const char *location);
86 #define tevent_add_timer(ev, mem_ctx, next_event, handler, private_data) \
87         _tevent_add_timer(ev, mem_ctx, next_event, handler, private_data, \
88                           #handler, __location__)
89
90 struct tevent_signal *_tevent_add_signal(struct tevent_context *ev,
91                                          TALLOC_CTX *mem_ctx,
92                                          int signum,
93                                          int sa_flags,
94                                          tevent_signal_handler_t handler,
95                                          void *private_data,
96                                          const char *handler_name,
97                                          const char *location);
98 #define tevent_add_signal(ev, mem_ctx, signum, sa_flags, handler, private_data) \
99         _tevent_add_signal(ev, mem_ctx, signum, sa_flags, handler, private_data, \
100                            #handler, __location__)
101
102 int tevent_loop_once(struct tevent_context *ev);
103 int tevent_loop_wait(struct tevent_context *ev);
104
105 void tevent_fd_set_close_fn(struct tevent_fd *fde,
106                             tevent_fd_close_fn_t close_fn);
107 void tevent_fd_set_auto_close(struct tevent_fd *fde);
108 uint16_t tevent_fd_get_flags(struct tevent_fd *fde);
109 void tevent_fd_set_flags(struct tevent_fd *fde, uint16_t flags);
110
111 /* bits for file descriptor event flags */
112 #define TEVENT_FD_READ 1
113 #define TEVENT_FD_WRITE 2
114
115 #define TEVENT_FD_WRITEABLE(fde) \
116         tevent_fd_set_flags(fde, tevent_fd_get_flags(fde) | TEVENT_FD_WRITE)
117 #define TEVENT_FD_READABLE(fde) \
118         tevent_fd_set_flags(fde, tevent_fd_get_flags(fde) | TEVENT_FD_READ)
119
120 #define TEVENT_FD_NOT_WRITEABLE(fde) \
121         tevent_fd_set_flags(fde, tevent_fd_get_flags(fde) & ~TEVENT_FD_WRITE)
122 #define TEVENT_FD_NOT_READABLE(fde) \
123         tevent_fd_set_flags(fde, tevent_fd_get_flags(fde) & ~TEVENT_FD_READ)
124
125 /* DEBUG */
126 enum tevent_debug_level {
127         TEVENT_DEBUG_FATAL,
128         TEVENT_DEBUG_ERROR,
129         TEVENT_DEBUG_WARNING,
130         TEVENT_DEBUG_TRACE
131 };
132
133 int tevent_set_debug(struct tevent_context *ev,
134                      void (*debug)(void *context,
135                                    enum tevent_debug_level level,
136                                    const char *fmt,
137                                    va_list ap) PRINTF_ATTRIBUTE(3,0),
138                      void *context);
139 int tevent_set_debug_stderr(struct tevent_context *ev);
140
141 /**
142  * An async request moves between the following 4 states:
143  */
144 enum tevent_req_state {
145         /**
146          * we are creating the request
147          */
148         TEVENT_REQ_INIT,
149         /**
150          * we are waiting the request to complete
151          */
152         TEVENT_REQ_IN_PROGRESS,
153         /**
154          * the request is finished
155          */
156         TEVENT_REQ_DONE,
157         /**
158          * A user error has occured
159          */
160         TEVENT_REQ_USER_ERROR,
161         /**
162          * Request timed out
163          */
164         TEVENT_REQ_TIMED_OUT,
165         /**
166          * No memory in between
167          */
168         TEVENT_REQ_NO_MEMORY
169 };
170
171 /**
172  * @brief An async request
173  *
174  * This represents an async request being processed by callbacks via an event
175  * context. A user can issue for example a write request to a socket, giving
176  * an implementation function the fd, the buffer and the number of bytes to
177  * transfer. The function issuing the request will immediately return without
178  * blocking most likely without having sent anything. The API user then fills
179  * in req->async.fn and req->async.private_data, functions that are called
180  * when the request is finished.
181  *
182  * It is up to the user of the async request to talloc_free it after it has
183  * finished. This can happen while the completion function is called.
184  */
185
186 struct tevent_req {
187         /**
188          * @brief What to do on completion
189          *
190          * This is used for the user of an async request, fn is called when
191          * the request completes, either successfully or with an error.
192          */
193         struct {
194                 /**
195                  * @brief Completion function
196                  * Completion function, to be filled by the API user
197                  */
198                 void (*fn)(struct tevent_req *);
199                 /**
200                  * @brief Private data for the completion function
201                  */
202                 void *private_data;
203         } async;
204
205         /**
206          * @brief Private state pointer for the actual implementation
207          *
208          * The implementation doing the work for the async request needs a
209          * current state like for example a fd event. The user of an async
210          * request should not touch this.
211          */
212         void *private_state;
213
214         /**
215          * @brief A function to overwrite the default print function
216          *
217          * The implementation doing the work may want to imeplement a
218          * custom function to print the text representation of the async
219          * request.
220          */
221         char *(*private_print)(struct tevent_req *req, TALLOC_CTX *mem_ctx);
222
223         /**
224          * @brief Internal state of the request
225          *
226          * Callers should only access this via functions and never directly.
227          */
228         struct {
229                 /**
230                  * @brief The talloc type of the private_state pointer
231                  *
232                  * This is filled by the tevent_req_create() macro.
233                  *
234                  * This for debugging only.
235                  */
236                 const char *private_type;
237
238                 /**
239                  * @brief The location where the request was created
240                  *
241                  * This uses the __location__ macro via the tevent_req_create()
242                  * macro.
243                  *
244                  * This for debugging only.
245                  */
246                 const char *location;
247
248                 /**
249                  * @brief The external state - will be queried by the caller
250                  *
251                  * While the async request is being processed, state will remain in
252                  * TEVENT_REQ_IN_PROGRESS. A request is finished if
253                  * req->state>=TEVENT_REQ_DONE.
254                  */
255                 enum tevent_req_state state;
256
257                 /**
258                  * @brief status code when finished
259                  *
260                  * This status can be queried in the async completion function. It
261                  * will be set to 0 when everything went fine.
262                  */
263                 uint64_t error;
264
265                 /**
266                  * @brief the timer event if tevent_req_post was used
267                  *
268                  */
269                 struct tevent_timer *trigger;
270
271                 /**
272                  * @brief the timer event if tevent_req_set_timeout was used
273                  *
274                  */
275                 struct tevent_timer *timer;
276         } internal;
277 };
278
279 char *tevent_req_default_print(struct tevent_req *req, TALLOC_CTX *mem_ctx);
280
281 char *tevent_req_print(TALLOC_CTX *mem_ctx, struct tevent_req *req);
282
283 struct tevent_req *_tevent_req_create(TALLOC_CTX *mem_ctx,
284                                       void *pstate,
285                                       size_t state_size,
286                                       const char *type,
287                                       const char *location);
288
289 #define tevent_req_create(_mem_ctx, _pstate, _type) \
290         _tevent_req_create((_mem_ctx), (_pstate), sizeof(_type), \
291                            #_type, __location__)
292
293 bool tevent_req_set_endtime(struct tevent_req *req,
294                             struct tevent_context *ev,
295                             struct timeval endtime);
296
297 void tevent_req_done(struct tevent_req *req);
298
299 bool tevent_req_error(struct tevent_req *req,
300                       uint64_t error);
301
302 bool tevent_req_nomem(const void *p,
303                       struct tevent_req *req);
304
305 struct tevent_req *tevent_req_post(struct tevent_req *req,
306                                    struct tevent_context *ev);
307
308 bool tevent_req_is_in_progress(struct tevent_req *req);
309
310 bool tevent_req_poll(struct tevent_req *req,
311                      struct tevent_context *ev);
312
313 bool tevent_req_is_error(struct tevent_req *req,
314                          enum tevent_req_state *state,
315                          uint64_t *error);
316
317 struct tevent_req *tevent_wakeup_send(TALLOC_CTX *mem_ctx,
318                                       struct tevent_context *ev,
319                                       struct timeval wakeup_time);
320 bool tevent_wakeup_recv(struct tevent_req *req);
321
322 int tevent_timeval_compare(const struct timeval *tv1,
323                            const struct timeval *tv2);
324
325 struct timeval tevent_timeval_zero(void);
326
327 struct timeval tevent_timeval_current(void);
328
329 struct timeval tevent_timeval_set(uint32_t secs, uint32_t usecs);
330
331 struct timeval tevent_timeval_until(const struct timeval *tv1,
332                                     const struct timeval *tv2);
333
334 bool tevent_timeval_is_zero(const struct timeval *tv);
335
336 struct timeval tevent_timeval_add(const struct timeval *tv, uint32_t secs,
337                                   uint32_t usecs);
338
339 struct timeval tevent_timeval_current_ofs(uint32_t secs, uint32_t usecs);
340
341 #ifdef TEVENT_COMPAT_DEFINES
342
343 #define event_context   tevent_context
344 #define event_ops       tevent_ops
345 #define fd_event        tevent_fd
346 #define timed_event     tevent_timer
347 #define signal_event    tevent_signal
348
349 #define event_fd_handler_t      tevent_fd_handler_t
350 #define event_timed_handler_t   tevent_timer_handler_t
351 #define event_signal_handler_t  tevent_signal_handler_t
352
353 #define event_context_init(mem_ctx) \
354         tevent_context_init(mem_ctx)
355
356 #define event_context_init_byname(mem_ctx, name) \
357         tevent_context_init_byname(mem_ctx, name)
358
359 #define event_backend_list(mem_ctx) \
360         tevent_backend_list(mem_ctx)
361
362 #define event_set_default_backend(backend) \
363         tevent_set_default_backend(backend)
364
365 #define event_add_fd(ev, mem_ctx, fd, flags, handler, private_data) \
366         tevent_add_fd(ev, mem_ctx, fd, flags, handler, private_data)
367
368 #define event_add_timed(ev, mem_ctx, next_event, handler, private_data) \
369         tevent_add_timer(ev, mem_ctx, next_event, handler, private_data)
370
371 #define event_add_signal(ev, mem_ctx, signum, sa_flags, handler, private_data) \
372         tevent_add_signal(ev, mem_ctx, signum, sa_flags, handler, private_data)
373
374 #define event_loop_once(ev) \
375         tevent_loop_once(ev)
376
377 #define event_loop_wait(ev) \
378         tevent_loop_wait(ev)
379
380 #define event_get_fd_flags(fde) \
381         tevent_fd_get_flags(fde)
382
383 #define event_set_fd_flags(fde, flags) \
384         tevent_fd_set_flags(fde, flags)
385
386 #define EVENT_FD_READ           TEVENT_FD_READ
387 #define EVENT_FD_WRITE          TEVENT_FD_WRITE
388
389 #define EVENT_FD_WRITEABLE(fde) \
390         TEVENT_FD_WRITEABLE(fde)
391
392 #define EVENT_FD_READABLE(fde) \
393         TEVENT_FD_READABLE(fde)
394
395 #define EVENT_FD_NOT_WRITEABLE(fde) \
396         TEVENT_FD_NOT_WRITEABLE(fde)
397
398 #define EVENT_FD_NOT_READABLE(fde) \
399         TEVENT_FD_NOT_READABLE(fde)
400
401 #define ev_debug_level          tevent_debug_level
402
403 #define EV_DEBUG_FATAL          TEVENT_DEBUG_FATAL
404 #define EV_DEBUG_ERROR          TEVENT_DEBUG_ERROR
405 #define EV_DEBUG_WARNING        TEVENT_DEBUG_WARNING
406 #define EV_DEBUG_TRACE          TEVENT_DEBUG_TRACE
407
408 #define ev_set_debug(ev, debug, context) \
409         tevent_set_debug(ev, debug, context)
410
411 #define ev_set_debug_stderr(_ev) tevent_set_debug_stderr(ev)
412
413 #endif /* TEVENT_COMPAT_DEFINES */
414
415 #endif /* __TEVENT_H__ */