tevent: tevent.h Source File

00001 /* 
00002    Unix SMB/CIFS implementation.
00003 
00004    generalised event loop handling
00005 
00006    Copyright (C) Andrew Tridgell 2005
00007    Copyright (C) Stefan Metzmacher 2005-2009
00008    Copyright (C) Volker Lendecke 2008
00009 
00010      ** NOTE! The following LGPL license applies to the tevent
00011      ** library. This does NOT imply that all of Samba is released
00012      ** under the LGPL
00013 
00014    This library is free software; you can redistribute it and/or
00015    modify it under the terms of the GNU Lesser General Public
00016    License as published by the Free Software Foundation; either
00017    version 3 of the License, or (at your option) any later version.
00018 
00019    This library is distributed in the hope that it will be useful,
00020    but WITHOUT ANY WARRANTY; without even the implied warranty of
00021    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00022    Lesser General Public License for more details.
00023 
00024    You should have received a copy of the GNU Lesser General Public
00025    License along with this library; if not, see <http://www.gnu.org/licenses/>.
00026 */
00027 
00028 #ifndef __TEVENT_H__
00029 #define __TEVENT_H__
00030 
00031 #include <stdint.h>
00032 #include <talloc.h>
00033 #include <sys/time.h>
00034 #include <stdbool.h>
00035 
00036 struct tevent_context;
00037 struct tevent_ops;
00038 struct tevent_fd;
00039 struct tevent_timer;
00040 struct tevent_immediate;
00041 struct tevent_signal;
00042 
00055 /* event handler types */
00060 typedef void (*tevent_fd_handler_t)(struct tevent_context *ev,
00061                                     struct tevent_fd *fde,
00062                                     uint16_t flags,
00063                                     void *private_data);
00064 
00068 typedef void (*tevent_fd_close_fn_t)(struct tevent_context *ev,
00069                                      struct tevent_fd *fde,
00070                                      int fd,
00071                                      void *private_data);
00072 
00076 typedef void (*tevent_timer_handler_t)(struct tevent_context *ev,
00077                                        struct tevent_timer *te,
00078                                        struct timeval current_time,
00079                                        void *private_data);
00080 
00084 typedef void (*tevent_immediate_handler_t)(struct tevent_context *ctx,
00085                                            struct tevent_immediate *im,
00086                                            void *private_data);
00087 
00091 typedef void (*tevent_signal_handler_t)(struct tevent_context *ev,
00092                                         struct tevent_signal *se,
00093                                         int signum,
00094                                         int count,
00095                                         void *siginfo,
00096                                         void *private_data);
00097 
00111 struct tevent_context *tevent_context_init(TALLOC_CTX *mem_ctx);
00112 
00126 struct tevent_context *tevent_context_init_byname(TALLOC_CTX *mem_ctx, const char *name);
00127 
00136 const char **tevent_backend_list(TALLOC_CTX *mem_ctx);
00137 
00143 void tevent_set_default_backend(const char *backend);
00144 
00145 #if DOXYGEN
00146 
00166 struct tevent_fd *tevent_add_fd(struct tevent_context *ev,
00167                                 TALLOC_CTX *mem_ctx,
00168                                 int fd,
00169                                 uint16_t flags,
00170                                 tevent_fd_handler_t handler,
00171                                 void *private_data);
00172 #else
00173 struct tevent_fd *_tevent_add_fd(struct tevent_context *ev,
00174                                  TALLOC_CTX *mem_ctx,
00175                                  int fd,
00176                                  uint16_t flags,
00177                                  tevent_fd_handler_t handler,
00178                                  void *private_data,
00179                                  const char *handler_name,
00180                                  const char *location);
00181 #define tevent_add_fd(ev, mem_ctx, fd, flags, handler, private_data) \
00182         _tevent_add_fd(ev, mem_ctx, fd, flags, handler, private_data, \
00183                        #handler, __location__)
00184 #endif
00185 
00186 #if DOXYGEN
00187 
00216 struct tevent_timer *tevent_add_timer(struct tevent_context *ev,
00217                                       TALLOC_CTX *mem_ctx,
00218                                       struct timeval next_event,
00219                                       tevent_timer_handler_t handler,
00220                                       void *private_data);
00221 #else
00222 struct tevent_timer *_tevent_add_timer(struct tevent_context *ev,
00223                                        TALLOC_CTX *mem_ctx,
00224                                        struct timeval next_event,
00225                                        tevent_timer_handler_t handler,
00226                                        void *private_data,
00227                                        const char *handler_name,
00228                                        const char *location);
00229 #define tevent_add_timer(ev, mem_ctx, next_event, handler, private_data) \
00230         _tevent_add_timer(ev, mem_ctx, next_event, handler, private_data, \
00231                           #handler, __location__)
00232 #endif
00233 
00234 #if DOXYGEN
00235 
00248 struct tevent_immediate *tevent_create_immediate(TALLOC_CTX *mem_ctx);
00249 #else
00250 struct tevent_immediate *_tevent_create_immediate(TALLOC_CTX *mem_ctx,
00251                                                   const char *location);
00252 #define tevent_create_immediate(mem_ctx) \
00253         _tevent_create_immediate(mem_ctx, __location__)
00254 #endif
00255 
00256 #if DOXYGEN
00257 
00268 void tevent_schedule_immediate(struct tevent_immediate *im,
00269                 struct tevent_context *ctx,
00270                 tevent_immediate_handler_t handler,
00271                 void *private_data);
00272 #else
00273 void _tevent_schedule_immediate(struct tevent_immediate *im,
00274                                 struct tevent_context *ctx,
00275                                 tevent_immediate_handler_t handler,
00276                                 void *private_data,
00277                                 const char *handler_name,
00278                                 const char *location);
00279 #define tevent_schedule_immediate(im, ctx, handler, private_data) \
00280         _tevent_schedule_immediate(im, ctx, handler, private_data, \
00281                                    #handler, __location__);
00282 #endif
00283 
00284 #if DOXYGEN
00285 
00309 struct tevent_signal *tevent_add_signal(struct tevent_context *ev,
00310                      TALLOC_CTX *mem_ctx,
00311                      int signum,
00312                      int sa_flags,
00313                      tevent_signal_handler_t handler,
00314                      void *private_data);
00315 #else
00316 struct tevent_signal *_tevent_add_signal(struct tevent_context *ev,
00317                                          TALLOC_CTX *mem_ctx,
00318                                          int signum,
00319                                          int sa_flags,
00320                                          tevent_signal_handler_t handler,
00321                                          void *private_data,
00322                                          const char *handler_name,
00323                                          const char *location);
00324 #define tevent_add_signal(ev, mem_ctx, signum, sa_flags, handler, private_data) \
00325         _tevent_add_signal(ev, mem_ctx, signum, sa_flags, handler, private_data, \
00326                            #handler, __location__)
00327 #endif
00328 
00329 #if DOXYGEN
00330 
00339 int tevent_loop_once(struct tevent_context *ev);
00340 #else
00341 int _tevent_loop_once(struct tevent_context *ev, const char *location);
00342 #define tevent_loop_once(ev) \
00343         _tevent_loop_once(ev, __location__) \
00344 #endif
00345 
00346 #if DOXYGEN
00347 
00357 int tevent_loop_wait(struct tevent_context *ev);
00358 #else
00359 int _tevent_loop_wait(struct tevent_context *ev, const char *location);
00360 #define tevent_loop_wait(ev) \
00361         _tevent_loop_wait(ev, __location__) \
00362 #endif
00363 
00364 
00375 void tevent_fd_set_close_fn(struct tevent_fd *fde,
00376                             tevent_fd_close_fn_t close_fn);
00377 
00385 void tevent_fd_set_auto_close(struct tevent_fd *fde);
00386 
00395 uint16_t tevent_fd_get_flags(struct tevent_fd *fde);
00396 
00404 void tevent_fd_set_flags(struct tevent_fd *fde, uint16_t flags);
00405 
00413 bool tevent_signal_support(struct tevent_context *ev);
00414 
00415 void tevent_set_abort_fn(void (*abort_fn)(const char *reason));
00416 
00417 /* bits for file descriptor event flags */
00418 
00422 #define TEVENT_FD_READ 1
00423 
00426 #define TEVENT_FD_WRITE 2
00427 
00431 #define TEVENT_FD_WRITEABLE(fde) \
00432         tevent_fd_set_flags(fde, tevent_fd_get_flags(fde) | TEVENT_FD_WRITE)
00433 
00437 #define TEVENT_FD_READABLE(fde) \
00438         tevent_fd_set_flags(fde, tevent_fd_get_flags(fde) | TEVENT_FD_READ)
00439 
00443 #define TEVENT_FD_NOT_WRITEABLE(fde) \
00444         tevent_fd_set_flags(fde, tevent_fd_get_flags(fde) & ~TEVENT_FD_WRITE)
00445 
00449 #define TEVENT_FD_NOT_READABLE(fde) \
00450         tevent_fd_set_flags(fde, tevent_fd_get_flags(fde) & ~TEVENT_FD_READ)
00451 
00455 enum tevent_debug_level {
00456         TEVENT_DEBUG_FATAL,
00457         TEVENT_DEBUG_ERROR,
00458         TEVENT_DEBUG_WARNING,
00459         TEVENT_DEBUG_TRACE
00460 };
00461 
00472 int tevent_set_debug(struct tevent_context *ev,
00473                      void (*debug)(void *context,
00474                                    enum tevent_debug_level level,
00475                                    const char *fmt,
00476                                    va_list ap) PRINTF_ATTRIBUTE(3,0),
00477                      void *context);
00478 
00488 int tevent_set_debug_stderr(struct tevent_context *ev);
00489 
00515 enum tevent_req_state {
00519         TEVENT_REQ_INIT,
00523         TEVENT_REQ_IN_PROGRESS,
00527         TEVENT_REQ_DONE,
00531         TEVENT_REQ_USER_ERROR,
00535         TEVENT_REQ_TIMED_OUT,
00539         TEVENT_REQ_NO_MEMORY,
00543         TEVENT_REQ_RECEIVED
00544 };
00545 
00549 struct tevent_req;
00550 
00551 typedef void (*tevent_req_fn)(struct tevent_req *);
00552 
00553 void tevent_req_set_callback(struct tevent_req *req, tevent_req_fn fn, void *pvt);
00554 
00555 void *_tevent_req_callback_data(struct tevent_req *req);
00556 #define tevent_req_callback_data(_req, _type) \
00557         talloc_get_type_abort(_tevent_req_callback_data(_req), _type)
00558 
00559 #define tevent_req_callback_data_void(_req) \
00560         _tevent_req_callback_data(_req)
00561 
00562 void *_tevent_req_data(struct tevent_req *req);
00563 #define tevent_req_data(_req, _type) \
00564         talloc_get_type_abort(_tevent_req_data(_req), _type)
00565 
00566 typedef char *(*tevent_req_print_fn)(struct tevent_req *, TALLOC_CTX *);
00567 
00581 void tevent_req_set_print_fn(struct tevent_req *req, tevent_req_print_fn fn);
00582 
00597 char *tevent_req_default_print(struct tevent_req *req, TALLOC_CTX *mem_ctx);
00598 
00610 char *tevent_req_print(TALLOC_CTX *mem_ctx, struct tevent_req *req);
00611 
00612 typedef bool (*tevent_req_cancel_fn)(struct tevent_req *);
00613 
00625 void tevent_req_set_cancel_fn(struct tevent_req *req, tevent_req_cancel_fn fn);
00626 
00627 #ifdef DOXYGEN
00628 
00646 bool tevent_req_cancel(struct tevent_req *req);
00647 #else
00648 bool _tevent_req_cancel(struct tevent_req *req, const char *location);
00649 #define tevent_req_cancel(req) \
00650         _tevent_req_cancel(req, __location__)
00651 #endif
00652 
00653 #if DOXYGEN
00654 
00669 struct tevent_req *tevent_req_create(TALLOC_CTX *mem_ctx,
00670                                       void *pstate,
00671                                       size_t state_size,
00672                                       const char *type);
00673 #else
00674 struct tevent_req *_tevent_req_create(TALLOC_CTX *mem_ctx,
00675                                       void *pstate,
00676                                       size_t state_size,
00677                                       const char *type,
00678                                       const char *location);
00679 
00680 #define tevent_req_create(_mem_ctx, _pstate, _type) \
00681         _tevent_req_create((_mem_ctx), (_pstate), sizeof(_type), \
00682                            #_type, __location__)
00683 #endif
00684 
00685 bool tevent_req_set_endtime(struct tevent_req *req,
00686                             struct tevent_context *ev,
00687                             struct timeval endtime);
00688 
00689 void _tevent_req_notify_callback(struct tevent_req *req, const char *location);
00690 #define tevent_req_notify_callback(req)         \
00691         _tevent_req_notify_callback(req, __location__)
00692 
00693 #ifdef DOXYGEN
00694 
00703 void tevent_req_done(struct tevent_req *req);
00704 #else
00705 void _tevent_req_done(struct tevent_req *req,
00706                       const char *location);
00707 #define tevent_req_done(req) \
00708         _tevent_req_done(req, __location__)
00709 #endif
00710 
00711 #ifdef DOXYGEN
00712 
00742 bool tevent_req_error(struct tevent_req *req,
00743                       uint64_t error);
00744 #else
00745 bool _tevent_req_error(struct tevent_req *req,
00746                        uint64_t error,
00747                        const char *location);
00748 #define tevent_req_error(req, error) \
00749         _tevent_req_error(req, error, __location__)
00750 #endif
00751 
00752 #ifdef DOXYGEN
00753 
00770 bool tevent_req_nomem(const void *p,
00771                       struct tevent_req *req);
00772 #else
00773 bool _tevent_req_nomem(const void *p,
00774                        struct tevent_req *req,
00775                        const char *location);
00776 #define tevent_req_nomem(p, req) \
00777         _tevent_req_nomem(p, req, __location__)
00778 #endif
00779 
00796 struct tevent_req *tevent_req_post(struct tevent_req *req,
00797                                    struct tevent_context *ev);
00798 
00810 bool tevent_req_is_in_progress(struct tevent_req *req);
00811 
00839 bool tevent_req_poll(struct tevent_req *req,
00840                      struct tevent_context *ev);
00841 
00842 bool tevent_req_is_error(struct tevent_req *req,
00843                          enum tevent_req_state *state,
00844                          uint64_t *error);
00845 
00853 void tevent_req_received(struct tevent_req *req);
00854 
00855 struct tevent_req *tevent_wakeup_send(TALLOC_CTX *mem_ctx,
00856                                       struct tevent_context *ev,
00857                                       struct timeval wakeup_time);
00858 bool tevent_wakeup_recv(struct tevent_req *req);
00859 
00860 /* @} */
00861 
00871 int tevent_timeval_compare(const struct timeval *tv1,
00872                            const struct timeval *tv2);
00873 
00874 struct timeval tevent_timeval_zero(void);
00875 
00876 struct timeval tevent_timeval_current(void);
00877 
00878 struct timeval tevent_timeval_set(uint32_t secs, uint32_t usecs);
00879 
00880 struct timeval tevent_timeval_until(const struct timeval *tv1,
00881                                     const struct timeval *tv2);
00882 
00883 bool tevent_timeval_is_zero(const struct timeval *tv);
00884 
00885 struct timeval tevent_timeval_add(const struct timeval *tv, uint32_t secs,
00886                                   uint32_t usecs);
00887 
00888 struct timeval tevent_timeval_current_ofs(uint32_t secs, uint32_t usecs);
00889 
00890 /* @} */
00891 
00892 
00900 struct tevent_queue;
00901 
00902 struct tevent_queue *_tevent_queue_create(TALLOC_CTX *mem_ctx,
00903                                           const char *name,
00904                                           const char *location);
00905 
00906 #define tevent_queue_create(_mem_ctx, _name) \
00907         _tevent_queue_create((_mem_ctx), (_name), __location__)
00908 
00909 typedef void (*tevent_queue_trigger_fn_t)(struct tevent_req *req,
00910                                           void *private_data);
00911 bool tevent_queue_add(struct tevent_queue *queue,
00912                       struct tevent_context *ev,
00913                       struct tevent_req *req,
00914                       tevent_queue_trigger_fn_t trigger,
00915                       void *private_data);
00916 void tevent_queue_start(struct tevent_queue *queue);
00917 void tevent_queue_stop(struct tevent_queue *queue);
00918 
00919 size_t tevent_queue_length(struct tevent_queue *queue);
00920 
00921 typedef int (*tevent_nesting_hook)(struct tevent_context *ev,
00922                                    void *private_data,
00923                                    uint32_t level,
00924                                    bool begin,
00925                                    void *stack_ptr,
00926                                    const char *location);
00927 #ifdef TEVENT_DEPRECATED
00928 #ifndef _DEPRECATED_
00929 #if (__GNUC__ >= 3) && (__GNUC_MINOR__ >= 1 )
00930 #define _DEPRECATED_ __attribute__ ((deprecated))
00931 #else
00932 #define _DEPRECATED_
00933 #endif
00934 #endif
00935 void tevent_loop_allow_nesting(struct tevent_context *ev) _DEPRECATED_;
00936 void tevent_loop_set_nesting_hook(struct tevent_context *ev,
00937                                   tevent_nesting_hook hook,
00938                                   void *private_data) _DEPRECATED_;
00939 int _tevent_loop_until(struct tevent_context *ev,
00940                        bool (*finished)(void *private_data),
00941                        void *private_data,
00942                        const char *location) _DEPRECATED_;
00943 #define tevent_loop_until(ev, finished, private_data) \
00944         _tevent_loop_until(ev, finished, private_data, __location__)
00945 #endif
00946 
00947 /* @} */
00948 
00959 struct tevent_ops {
00960         /* context init */
00961         int (*context_init)(struct tevent_context *ev);
00962 
00963         /* fd_event functions */
00964         struct tevent_fd *(*add_fd)(struct tevent_context *ev,
00965                                     TALLOC_CTX *mem_ctx,
00966                                     int fd, uint16_t flags,
00967                                     tevent_fd_handler_t handler,
00968                                     void *private_data,
00969                                     const char *handler_name,
00970                                     const char *location);
00971         void (*set_fd_close_fn)(struct tevent_fd *fde,
00972                                 tevent_fd_close_fn_t close_fn);
00973         uint16_t (*get_fd_flags)(struct tevent_fd *fde);
00974         void (*set_fd_flags)(struct tevent_fd *fde, uint16_t flags);
00975 
00976         /* timed_event functions */
00977         struct tevent_timer *(*add_timer)(struct tevent_context *ev,
00978                                           TALLOC_CTX *mem_ctx,
00979                                           struct timeval next_event,
00980                                           tevent_timer_handler_t handler,
00981                                           void *private_data,
00982                                           const char *handler_name,
00983                                           const char *location);
00984 
00985         /* immediate event functions */
00986         void (*schedule_immediate)(struct tevent_immediate *im,
00987                                    struct tevent_context *ev,
00988                                    tevent_immediate_handler_t handler,
00989                                    void *private_data,
00990                                    const char *handler_name,
00991                                    const char *location);
00992 
00993         /* signal functions */
00994         struct tevent_signal *(*add_signal)(struct tevent_context *ev,
00995                                             TALLOC_CTX *mem_ctx,
00996                                             int signum, int sa_flags,
00997                                             tevent_signal_handler_t handler,
00998                                             void *private_data,
00999                                             const char *handler_name,
01000                                             const char *location);
01001 
01002         /* loop functions */
01003         int (*loop_once)(struct tevent_context *ev, const char *location);
01004         int (*loop_wait)(struct tevent_context *ev, const char *location);
01005 };
01006 
01007 bool tevent_register_backend(const char *name, const struct tevent_ops *ops);
01008 
01009 /* @} */
01010 
01024 #ifdef TEVENT_COMPAT_DEFINES
01025 
01026 #define event_context   tevent_context
01027 #define event_ops       tevent_ops
01028 #define fd_event        tevent_fd
01029 #define timed_event     tevent_timer
01030 #define signal_event    tevent_signal
01031 
01032 #define event_fd_handler_t      tevent_fd_handler_t
01033 #define event_timed_handler_t   tevent_timer_handler_t
01034 #define event_signal_handler_t  tevent_signal_handler_t
01035 
01036 #define event_context_init(mem_ctx) \
01037         tevent_context_init(mem_ctx)
01038 
01039 #define event_context_init_byname(mem_ctx, name) \
01040         tevent_context_init_byname(mem_ctx, name)
01041 
01042 #define event_backend_list(mem_ctx) \
01043         tevent_backend_list(mem_ctx)
01044 
01045 #define event_set_default_backend(backend) \
01046         tevent_set_default_backend(backend)
01047 
01048 #define event_add_fd(ev, mem_ctx, fd, flags, handler, private_data) \
01049         tevent_add_fd(ev, mem_ctx, fd, flags, handler, private_data)
01050 
01051 #define event_add_timed(ev, mem_ctx, next_event, handler, private_data) \
01052         tevent_add_timer(ev, mem_ctx, next_event, handler, private_data)
01053 
01054 #define event_add_signal(ev, mem_ctx, signum, sa_flags, handler, private_data) \
01055         tevent_add_signal(ev, mem_ctx, signum, sa_flags, handler, private_data)
01056 
01057 #define event_loop_once(ev) \
01058         tevent_loop_once(ev)
01059 
01060 #define event_loop_wait(ev) \
01061         tevent_loop_wait(ev)
01062 
01063 #define event_get_fd_flags(fde) \
01064         tevent_fd_get_flags(fde)
01065 
01066 #define event_set_fd_flags(fde, flags) \
01067         tevent_fd_set_flags(fde, flags)
01068 
01069 #define EVENT_FD_READ           TEVENT_FD_READ
01070 #define EVENT_FD_WRITE          TEVENT_FD_WRITE
01071 
01072 #define EVENT_FD_WRITEABLE(fde) \
01073         TEVENT_FD_WRITEABLE(fde)
01074 
01075 #define EVENT_FD_READABLE(fde) \
01076         TEVENT_FD_READABLE(fde)
01077 
01078 #define EVENT_FD_NOT_WRITEABLE(fde) \
01079         TEVENT_FD_NOT_WRITEABLE(fde)
01080 
01081 #define EVENT_FD_NOT_READABLE(fde) \
01082         TEVENT_FD_NOT_READABLE(fde)
01083 
01084 #define ev_debug_level          tevent_debug_level
01085 
01086 #define EV_DEBUG_FATAL          TEVENT_DEBUG_FATAL
01087 #define EV_DEBUG_ERROR          TEVENT_DEBUG_ERROR
01088 #define EV_DEBUG_WARNING        TEVENT_DEBUG_WARNING
01089 #define EV_DEBUG_TRACE          TEVENT_DEBUG_TRACE
01090 
01091 #define ev_set_debug(ev, debug, context) \
01092         tevent_set_debug(ev, debug, context)
01093 
01094 #define ev_set_debug_stderr(_ev) tevent_set_debug_stderr(ev)
01095 
01096 #endif /* TEVENT_COMPAT_DEFINES */
01097 
01098 /* @} */
01099 
01100 #endif /* __TEVENT_H__ */