libevent/include/event2/event_compat.h

   1 /*
   2  * Copyright (c) 2000-2007 Niels Provos <provos@citi.umich.edu>
   3  * Copyright (c) 2007-2010 Niels Provos and Nick Mathewson
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  * 1. Redistributions of source code must retain the above copyright
   9  *    notice, this list of conditions and the following disclaimer.
  10  * 2. Redistributions in binary form must reproduce the above copyright
  11  *    notice, this list of conditions and the following disclaimer in the
  12  *    documentation and/or other materials provided with the distribution.
  13  * 3. The name of the author may not be used to endorse or promote products
  14  *    derived from this software without specific prior written permission.
  15  *
  16  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  17  * IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  18  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  19  * IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  20  * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  21  * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  22  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  23  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  24  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  25  * THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  26  */
  27 #ifndef _EVENT2_EVENT_COMPAT_H_
  28 #define _EVENT2_EVENT_COMPAT_H_
  29
  30 /** @file event_compat.h
  31
  32   Potentially non-threadsafe versions of the functions in event.h: provided
  33   only for backwards compatibility.
  34
  35  */
  36
  37 #ifdef __cplusplus
  38 extern "C" {
  39 #endif
  40
  41 #include <event2/event-config.h>
  42 #ifdef _EVENT_HAVE_SYS_TYPES_H
  43 #include <sys/types.h>
  44 #endif
  45 #ifdef _EVENT_HAVE_SYS_TIME_H
  46 #include <sys/time.h>
  47 #endif
  48
  49 /* For int types. */
  50 #include <event2/util.h>
  51
  52 /**
  53   Initialize the event API.
  54
  55   The event API needs to be initialized with event_init() before it can be
  56   used.  Sets the global current base that gets used for events that have no
  57   base associated with them.
  58
  59   @deprecated This function is deprecated because it replaces the "current"
  60     event_base, and is totally unsafe for multithreaded use.  The replacement
  61     is event_base_new().
  62
  63   @see event_base_set(), event_base_new()
  64  */
  65 struct event_base *event_init(void);
  66
  67 /**
  68   Loop to process events.
  69
  70   In order to process events, an application needs to call
  71   event_dispatch().  This function only returns on error, and should
  72   replace the event core of the application program.
  73
  74   @deprecated This function is deprecated because it is easily confused by
  75     multiple calls to event_init(), and because it is not safe for
  76     multithreaded use.  The replacement is event_base_dispatch().
  77
  78   @see event_base_dispatch()
  79  */
  80 int event_dispatch(void);
  81
  82 /**
  83   Handle events.
  84
  85   This is a more flexible version of event_dispatch().
  86
  87   @deprecated This function is deprecated because it uses the event base from
  88     the last call to event_init, and is therefore not safe for multithreaded
  89     use.  The replacement is event_base_loop().
  90
  91   @param flags any combination of EVLOOP_ONCE | EVLOOP_NONBLOCK
  92   @return 0 if successful, -1 if an error occurred, or 1 if no events were
  93     registered.
  94   @see event_base_loopexit(), event_base_loop()
  95 */
  96 int event_loop(int);
  97
  98
  99 /**
 100   Exit the event loop after the specified time.
 101
 102   The next event_loop() iteration after the given timer expires will
 103   complete normally (handling all queued events) then exit without
 104   blocking for events again.
 105
 106   Subsequent invocations of event_loop() will proceed normally.
 107
 108   @deprecated This function is deprecated because it is easily confused by
 109     multiple calls to event_init(), and because it is not safe for
 110     multithreaded use.  The replacement is event_base_loopexit().
 111
 112   @param tv the amount of time after which the loop should terminate.
 113   @return 0 if successful, or -1 if an error occurred
 114   @see event_loop(), event_base_loop(), event_base_loopexit()
 115   */
 116 int event_loopexit(const struct timeval *);
 117
 118
 119 /**
 120   Abort the active event_loop() immediately.
 121
 122   event_loop() will abort the loop after the next event is completed;
 123   event_loopbreak() is typically invoked from this event's callback.
 124   This behavior is analogous to the "break;" statement.
 125
 126   Subsequent invocations of event_loop() will proceed normally.
 127
 128   @deprecated This function is deprecated because it is easily confused by
 129     multiple calls to event_init(), and because it is not safe for
 130     multithreaded use.  The replacement is event_base_loopbreak().
 131
 132   @return 0 if successful, or -1 if an error occurred
 133   @see event_base_loopbreak(), event_loopexit()
 134  */
 135 int event_loopbreak(void);
 136
 137 /**
 138   Schedule a one-time event to occur.
 139
 140   The function event_once() is similar to event_set().  However, it schedules
 141   a callback to be called exactly once and does not require the caller to
 142   prepare an event structure.
 143
 144   @deprecated This function is deprecated because it is easily confused by
 145     multiple calls to event_init(), and because it is not safe for
 146     multithreaded use.  The replacement is event_base_once().
 147
 148   @param fd a file descriptor to monitor
 149   @param events event(s) to monitor; can be any of EV_TIMEOUT | EV_READ |
 150          EV_WRITE
 151   @param callback callback function to be invoked when the event occurs
 152   @param arg an argument to be passed to the callback function
 153   @param timeout the maximum amount of time to wait for the event, or NULL
 154          to wait forever
 155   @return 0 if successful, or -1 if an error occurred
 156   @see event_set()
 157
 158  */
 159 int event_once(evutil_socket_t , short,
 160     void (*)(evutil_socket_t, short, void *), void *, const struct timeval *);
 161
 162
 163 /**
 164   Get the kernel event notification mechanism used by Libevent.
 165
 166   @return a string identifying the kernel event mechanism (kqueue, epoll, etc.)
 167
 168   @deprecated This function is deprecated because it is easily confused by
 169     multiple calls to event_init(), and because it is not safe for
 170     multithreaded use.  The replacement is event_base_get_method().
 171  */
 172 const char *event_get_method(void);
 173
 174
 175 /**
 176   Set the number of different event priorities.
 177
 178   By default Libevent schedules all active events with the same priority.
 179   However, some time it is desirable to process some events with a higher
 180   priority than others.  For that reason, Libevent supports strict priority
 181   queues.  Active events with a lower priority are always processed before
 182   events with a higher priority.
 183
 184   The number of different priorities can be set initially with the
 185   event_priority_init() function.  This function should be called before the
 186   first call to event_dispatch().  The event_priority_set() function can be
 187   used to assign a priority to an event.  By default, Libevent assigns the
 188   middle priority to all events unless their priority is explicitly set.
 189
 190   @deprecated This function is deprecated because it is easily confused by
 191     multiple calls to event_init(), and because it is not safe for
 192     multithreaded use.  The replacement is event_base_priority_init().
 193
 194   @param npriorities the maximum number of priorities
 195   @return 0 if successful, or -1 if an error occurred
 196   @see event_base_priority_init(), event_priority_set()
 197
 198  */
 199 int     event_priority_init(int);
 200
 201 /**
 202   Prepare an event structure to be added.
 203
 204   The function event_set() prepares the event structure ev to be used in
 205   future calls to event_add() and event_del().  The event will be prepared to
 206   call the function specified by the fn argument with an int argument
 207   indicating the file descriptor, a short argument indicating the type of
 208   event, and a void * argument given in the arg argument.  The fd indicates
 209   the file descriptor that should be monitored for events.  The events can be
 210   either EV_READ, EV_WRITE, or both.  Indicating that an application can read
 211   or write from the file descriptor respectively without blocking.
 212
 213   The function fn will be called with the file descriptor that triggered the
 214   event and the type of event which will be either EV_TIMEOUT, EV_SIGNAL,
 215   EV_READ, or EV_WRITE.  The additional flag EV_PERSIST makes an event_add()
 216   persistent until event_del() has been called.
 217
 218   For read and write events, edge-triggered behavior can be requested
 219   with the EV_ET flag.  Not all backends support edge-triggered
 220   behavior.  When an edge-triggered event is activated, the EV_ET flag
 221   is added to its events argument.
 222
 223   @param ev an event struct to be modified
 224   @param fd the file descriptor to be monitored
 225   @param event desired events to monitor; can be EV_READ and/or EV_WRITE
 226   @param fn callback function to be invoked when the event occurs
 227   @param arg an argument to be passed to the callback function
 228
 229   @see event_add(), event_del(), event_once()
 230
 231   @deprecated event_set() is not recommended for new code, because it requires
 232      a subsequent call to event_base_set() to be safe under many circumstances.
 233      Use event_assign() or event_new() instead.
 234  */
 235 void event_set(struct event *, evutil_socket_t, short, void (*)(evutil_socket_t, short, void *), void *);
 236
 237 #define evtimer_set(ev, cb, arg)        event_set((ev), -1, 0, (cb), (arg))
 238 #define evsignal_set(ev, x, cb, arg)    \
 239         event_set((ev), (x), EV_SIGNAL|EV_PERSIST, (cb), (arg))
 240
 241
 242 /**
 243  * Add a timeout event.
 244  *
 245  * @param ev the event struct to be disabled
 246  * @param tv the timeout value, in seconds
 247  *
 248  * @deprecated This macro is deprecated because its naming is inconsistent.
 249  *    The recommend macro is evtimer_add().
 250  */
 251 #define timeout_add(ev, tv)             event_add((ev), (tv))
 252
 253
 254 /**
 255  * Define a timeout event.
 256  *
 257  * @param ev the event struct to be defined
 258  * @param cb the callback to be invoked when the timeout expires
 259  * @param arg the argument to be passed to the callback
 260  *
 261  * @deprecated This macro is deprecated because its naming is inconsistent.
 262  *    The recommend macro is evtimer_set().
 263  */
 264 #define timeout_set(ev, cb, arg)        event_set((ev), -1, 0, (cb), (arg))
 265
 266 /**
 267  * Disable a timeout event.
 268  *
 269  * @param ev the timeout event to be disabled
 270  *
 271  * @deprecated This macro is deprecated because its naming is inconsistent.
 272  *    The recommend macro is evtimer_del().
 273  */
 274 #define timeout_del(ev)                 event_del(ev)
 275
 276 /**
 277    @deprecated This macro is deprecated because its naming is inconsistent.
 278    The recommend macro is evtimer_pending().
 279 */
 280 #define timeout_pending(ev, tv)         event_pending((ev), EV_TIMEOUT, (tv))
 281 /**
 282    @deprecated This macro is deprecated because its naming is inconsistent.
 283    The recommend macro is evtimer_initialized().
 284 */
 285 #define timeout_initialized(ev)         event_initialized(ev)
 286
 287 /**
 288    @deprecated This macro is deprecated because its naming is inconsistent.
 289     The recommend macro is evsignal_add().
 290 */
 291 #define signal_add(ev, tv)              event_add((ev), (tv))
 292 /**
 293    @deprecated This macro is deprecated because its naming is inconsistent.
 294     The recommend macro is evsignal_set().
 295 */
 296 #define signal_set(ev, x, cb, arg)                              \
 297         event_set((ev), (x), EV_SIGNAL|EV_PERSIST, (cb), (arg))
 298 /**
 299    @deprecated This macro is deprecated because its naming is inconsistent.
 300     The recommend macro is evsignal_del().
 301 */
 302 #define signal_del(ev)                  event_del(ev)
 303 /**
 304    @deprecated This macro is deprecated because its naming is inconsistent.
 305     The recommend macro is evsignal_pending().
 306 */
 307 #define signal_pending(ev, tv)          event_pending((ev), EV_SIGNAL, (tv))
 308 /**
 309    @deprecated This macro is deprecated because its naming is inconsistent.
 310     The recommend macro is evsignal_initialized().
 311 */
 312 #define signal_initialized(ev)          event_initialized(ev)
 313
 314 #ifndef EVENT_FD
 315 /* These macros are obsolete; use event_get_fd and event_get_signal instead. */
 316 #define EVENT_FD(ev)            ((int)event_get_fd(ev))
 317 #define EVENT_SIGNAL(ev)        event_get_signal(ev)
 318 #endif
 319
 320 #ifdef __cplusplus
 321 }
 322 #endif
 323
 324 #endif /* _EVENT2_EVENT_COMPAT_H_ */