src/common/compat_libevent.c

   1 /* Copyright (c) 2009-2010, The Tor Project, Inc. */
   2 /* See LICENSE for licensing information */
   3
   4 /**
   5  * \file compat_libevent.c
   6  * \brief Wrappers to handle porting between different versions of libevent.
   7  *
   8  * In an ideal world, we'd just use Libevent 2.0 from now on.  But as of June
   9  * 2009, Libevent 2.0 is still in alpha, and we will have old versions of
  10  * Libevent for the forseeable future.
  11  **/
  12
  13 #include "orconfig.h"
  14 #include "compat.h"
  15 #include "compat_libevent.h"
  16
  17 #include "util.h"
  18 #include "torlog.h"
  19
  20 #ifdef HAVE_EVENT2_EVENT_H
  21 #include <event2/event.h>
  22 #else
  23 #include <event.h>
  24 #endif
  25
  26 /** A number representing a version of Libevent.
  27
  28     This is a 4-byte number, with the first three bytes representing the
  29     major, minor, and patchlevel respectively of the library.  The fourth
  30     byte is unused.
  31
  32     This is equivalent to the format of LIBEVENT_VERSION_NUMBER on Libevent
  33     2.0.1 or later.  For versions of Libevent before 1.4.0, which followed the
  34     format of "1.0, 1.0a, 1.0b", we define 1.0 to be equivalent to 1.0.0, 1.0a
  35     to be equivalent to 1.0.1, and so on.
  36 */
  37 typedef uint32_t le_version_t;
  38
  39 /* Macros: returns the number of a libevent version. */
  40 #define V(major, minor, patch) \
  41   (((major) << 24) | ((minor) << 16) | ((patch) << 8))
  42 #define V_OLD(major, minor, patch) \
  43   V((major), (minor), (patch)-'a'+1)
  44
  45 #define LE_OLD V(0,0,0)
  46 #define LE_OTHER V(0,0,99)
  47
  48 static le_version_t tor_get_libevent_version(const char **v_out);
  49
  50 #ifdef HAVE_EVENT_SET_LOG_CALLBACK
  51 /** A string which, if it appears in a libevent log, should be ignored. */
  52 static const char *suppress_msg = NULL;
  53 /** Callback function passed to event_set_log() so we can intercept
  54  * log messages from libevent. */
  55 static void
  56 libevent_logging_callback(int severity, const char *msg)
  57 {
  58   char buf[1024];
  59   size_t n;
  60   if (suppress_msg && strstr(msg, suppress_msg))
  61     return;
  62   n = strlcpy(buf, msg, sizeof(buf));
  63   if (n && n < sizeof(buf) && buf[n-1] == '\n') {
  64     buf[n-1] = '\0';
  65   }
  66   switch (severity) {
  67     case _EVENT_LOG_DEBUG:
  68       log(LOG_DEBUG, LD_NET, "Message from libevent: %s", buf);
  69       break;
  70     case _EVENT_LOG_MSG:
  71       log(LOG_INFO, LD_NET, "Message from libevent: %s", buf);
  72       break;
  73     case _EVENT_LOG_WARN:
  74       log(LOG_WARN, LD_GENERAL, "Warning from libevent: %s", buf);
  75       break;
  76     case _EVENT_LOG_ERR:
  77       log(LOG_ERR, LD_GENERAL, "Error from libevent: %s", buf);
  78       break;
  79     default:
  80       log(LOG_WARN, LD_GENERAL, "Message [%d] from libevent: %s",
  81           severity, buf);
  82       break;
  83   }
  84 }
  85 /** Set hook to intercept log messages from libevent. */
  86 void
  87 configure_libevent_logging(void)
  88 {
  89   event_set_log_callback(libevent_logging_callback);
  90 }
  91 /** Ignore any libevent log message that contains <b>msg</b>. */
  92 void
  93 suppress_libevent_log_msg(const char *msg)
  94 {
  95   suppress_msg = msg;
  96 }
  97 #else
  98 void
  99 configure_libevent_logging(void)
 100 {
 101 }
 102 void
 103 suppress_libevent_log_msg(const char *msg)
 104 {
 105   (void)msg;
 106 }
 107 #endif
 108
 109 #ifndef HAVE_EVENT2_EVENT_H
 110 /** Work-alike replacement for event_new() on pre-Libevent-2.0 systems. */
 111 struct event *
 112 tor_event_new(struct event_base *base, int sock, short what,
 113               void (*cb)(int, short, void *), void *arg)
 114 {
 115   struct event *e = tor_malloc_zero(sizeof(struct event));
 116   event_set(e, sock, what, cb, arg);
 117   if (! base)
 118     base = tor_libevent_get_base();
 119   event_base_set(base, e);
 120   return e;
 121 }
 122 /** Work-alike replacement for evtimer_new() on pre-Libevent-2.0 systems. */
 123 struct event *
 124 tor_evtimer_new(struct event_base *base,
 125                 void (*cb)(int, short, void *), void *arg)
 126 {
 127   return tor_event_new(base, -1, 0, cb, arg);
 128 }
 129 /** Work-alike replacement for evsignal_new() on pre-Libevent-2.0 systems. */
 130 struct event *
 131 tor_evsignal_new(struct event_base * base, int sig,
 132                  void (*cb)(int, short, void *), void *arg)
 133 {
 134   return tor_event_new(base, sig, EV_SIGNAL|EV_PERSIST, cb, arg);
 135 }
 136 /** Work-alike replacement for event_free() on pre-Libevent-2.0 systems. */
 137 void
 138 tor_event_free(struct event *ev)
 139 {
 140   event_del(ev);
 141   tor_free(ev);
 142 }
 143 #endif
 144
 145 /** Global event base for use by the main thread. */
 146 struct event_base *the_event_base = NULL;
 147
 148 /* This is what passes for version detection on OSX.  We set
 149  * MACOSX_KQUEUE_IS_BROKEN to true iff we're on a version of OSX before
 150  * 10.4.0 (aka 1040). */
 151 #ifdef __APPLE__
 152 #ifdef __ENVIRONMENT_MAC_OS_X_VERSION_MIN_REQUIRED__
 153 #define MACOSX_KQUEUE_IS_BROKEN \
 154   (__ENVIRONMENT_MAC_OS_X_VERSION_MIN_REQUIRED__ < 1040)
 155 #else
 156 #define MACOSX_KQUEUE_IS_BROKEN 0
 157 #endif
 158 #endif
 159
 160 /** Initialize the Libevent library and set up the event base. */
 161 void
 162 tor_libevent_initialize(void)
 163 {
 164   tor_assert(the_event_base == NULL);
 165
 166 #ifdef __APPLE__
 167   if (MACOSX_KQUEUE_IS_BROKEN ||
 168       tor_get_libevent_version(NULL) < V_OLD(1,1,'b')) {
 169     setenv("EVENT_NOKQUEUE","1",1);
 170   }
 171 #endif
 172
 173 #ifdef HAVE_EVENT2_EVENT_H
 174   the_event_base = event_base_new();
 175 #else
 176   the_event_base = event_init();
 177 #endif
 178
 179 #if defined(HAVE_EVENT_GET_VERSION) && defined(HAVE_EVENT_GET_METHOD)
 180   /* Making this a NOTICE for now so we can link bugs to a libevent versions
 181    * or methods better. */
 182   log(LOG_NOTICE, LD_GENERAL,
 183       "Initialized libevent version %s using method %s. Good.",
 184       event_get_version(), tor_libevent_get_method());
 185 #else
 186   log(LOG_NOTICE, LD_GENERAL,
 187       "Initialized old libevent (version 1.0b or earlier).");
 188   log(LOG_WARN, LD_GENERAL,
 189       "You have a *VERY* old version of libevent.  It is likely to be buggy; "
 190       "please build Tor with a more recent version.");
 191 #endif
 192 }
 193
 194 /** Return the current Libevent event base that we're set up to use. */
 195 struct event_base *
 196 tor_libevent_get_base(void)
 197 {
 198   return the_event_base;
 199 }
 200
 201 #ifndef HAVE_EVENT_BASE_LOOPEXIT
 202 /* Replacement for event_base_loopexit on some very old versions of Libevent
 203    that we are not yet brave enough to deprecate. */
 204 int
 205 tor_event_base_loopexit(struct event_base *base, struct timeval *tv)
 206 {
 207   tor_assert(base == the_event_base);
 208   return event_loopexit(tv);
 209 }
 210 #endif
 211
 212 /** Return the name of the Libevent backend we're using. */
 213 const char *
 214 tor_libevent_get_method(void)
 215 {
 216 #ifdef HAVE_EVENT2_EVENT_H
 217   return event_base_get_method(the_event_base);
 218 #elif defined(HAVE_EVENT_GET_METHOD)
 219   return event_get_method();
 220 #else
 221   return "<unknown>";
 222 #endif
 223 }
 224
 225 /** Return the le_version_t for the current version of libevent.  If the
 226  * version is very new, return LE_OTHER.  If the version is so old that it
 227  * doesn't support event_get_version(), return LE_OLD. DOCDOC */
 228 static le_version_t
 229 tor_decode_libevent_version(const char *v)
 230 {
 231   unsigned major, minor, patchlevel;
 232   char c, extra;
 233   int fields;
 234
 235   /* Try the new preferred "1.4.11-stable" format. */
 236   fields = sscanf(v, "%u.%u.%u%c", &major, &minor, &patchlevel, &c);
 237   if (fields == 3 ||
 238       (fields == 4 && (c == '-' || c == '_'))) {
 239     return V(major,minor,patchlevel);
 240   }
 241
 242   /* Try the old "1.3e" format. */
 243   fields = sscanf(v, "%u.%u%c%c", &major, &minor, &c, &extra);
 244   if (fields == 3 && TOR_ISALPHA(c)) {
 245     return V_OLD(major, minor, c);
 246   } else if (fields == 2) {
 247     return V(major, minor, 0);
 248   }
 249
 250   return LE_OTHER;
 251 }
 252
 253 /** Return an integer representing the binary interface of a Libevent library.
 254  * Two different versions with different numbers are sure not to be binary
 255  * compatible.  Two different versions with the same numbers have a decent
 256  * chance of binary compatibility.*/
 257 static int
 258 le_versions_compatibility(le_version_t v)
 259 {
 260   if (v == LE_OTHER)
 261     return 0;
 262   if (v < V_OLD(1,0,'c'))
 263     return 1;
 264   else if (v < V(1,4,0))
 265     return 2;
 266   else if (v < V(1,4,99))
 267     return 3;
 268   else if (v < V(2,0,1))
 269     return 4;
 270   else /* Everything 2.0 and later should be compatible. */
 271     return 5;
 272 }
 273
 274 /** Return the version number of the currently running version of Libevent.
 275     See le_version_t for info on the format.
 276  */
 277 static le_version_t
 278 tor_get_libevent_version(const char **v_out)
 279 {
 280   const char *v;
 281   le_version_t r;
 282 #if defined(HAVE_EVENT_GET_VERSION_NUMBER)
 283   v = event_get_version();
 284   r = event_get_version_number();
 285 #elif defined (HAVE_EVENT_GET_VERSION)
 286   v = event_get_version();
 287   r = tor_decode_libevent_version(v);
 288 #else
 289   v = "pre-1.0c";
 290   r = LE_OLD;
 291 #endif
 292   if (v_out)
 293     *v_out = v;
 294   return r;
 295 }
 296
 297 /** Return a string representation of the version of the currently running
 298  * version of Libevent. */
 299 const char *
 300 tor_libevent_get_version_str(void)
 301 {
 302 #ifdef HAVE_EVENT_GET_VERSION
 303   return event_get_version();
 304 #else
 305   return "pre-1.0c";
 306 #endif
 307 }
 308
 309 /**
 310  * Compare the current Libevent method and version to a list of versions
 311  * which are known not to work.  Warn the user as appropriate.
 312  */
 313 void
 314 tor_check_libevent_version(const char *m, int server,
 315                            const char **badness_out)
 316 {
 317   int buggy = 0, iffy = 0, slow = 0, thread_unsafe = 0;
 318   le_version_t version;
 319   const char *v = NULL;
 320   const char *badness = NULL;
 321   const char *sad_os = "";
 322
 323   version = tor_get_libevent_version(&v);
 324
 325   /* XXX Would it be worthwhile disabling the methods that we know
 326    * are buggy, rather than just warning about them and then proceeding
 327    * to use them? If so, we should probably not wrap this whole thing
 328    * in HAVE_EVENT_GET_VERSION and HAVE_EVENT_GET_METHOD. -RD */
 329   /* XXXX The problem is that it's not trivial to get libevent to change it's
 330    * method once it's initialized, and it's not trivial to tell what method it
 331    * will use without initializing it.  I guess we could preemptively disable
 332    * buggy libevent modes based on the version _before_ initializing it,
 333    * though, but then there's no good way (afaict) to warn "I would have used
 334    * kqueue, but instead I'm using select." -NM */
 335   /* XXXX022 revist the above; it is fixable now. */
 336   if (!strcmp(m, "kqueue")) {
 337     if (version < V_OLD(1,1,'b'))
 338       buggy = 1;
 339   } else if (!strcmp(m, "epoll")) {
 340     if (version < V(1,1,0))
 341       iffy = 1;
 342   } else if (!strcmp(m, "poll")) {
 343     if (version < V_OLD(1,0,'e'))
 344       buggy = 1;
 345     if (version < V(1,1,0))
 346       slow = 1;
 347   } else if (!strcmp(m, "select")) {
 348     if (version < V(1,1,0))
 349       slow = 1;
 350   } else if (!strcmp(m, "win32")) {
 351     if (version < V_OLD(1,1,'b'))
 352       buggy = 1;
 353   }
 354
 355   /* Libevent versions before 1.3b do very badly on operating systems with
 356    * user-space threading implementations. */
 357 #if defined(__OpenBSD__) || defined(__FreeBSD__) || defined(__NetBSD__)
 358   if (server && version < V_OLD(1,3,'b')) {
 359     thread_unsafe = 1;
 360     sad_os = "BSD variants";
 361   }
 362 #elif defined(__APPLE__) || defined(__darwin__)
 363   if (server && version < V_OLD(1,3,'b')) {
 364     thread_unsafe = 1;
 365     sad_os = "Mac OS X";
 366   }
 367 #endif
 368
 369   if (thread_unsafe) {
 370     log(LOG_WARN, LD_GENERAL,
 371         "Libevent version %s often crashes when running a Tor server with %s. "
 372         "Please use the latest version of libevent (1.3b or later)",v,sad_os);
 373     badness = "BROKEN";
 374   } else if (buggy) {
 375     log(LOG_WARN, LD_GENERAL,
 376         "There are serious bugs in using %s with libevent %s. "
 377         "Please use the latest version of libevent.", m, v);
 378     badness = "BROKEN";
 379   } else if (iffy) {
 380     log(LOG_WARN, LD_GENERAL,
 381         "There are minor bugs in using %s with libevent %s. "
 382         "You may want to use the latest version of libevent.", m, v);
 383     badness = "BUGGY";
 384   } else if (slow && server) {
 385     log(LOG_WARN, LD_GENERAL,
 386         "libevent %s can be very slow with %s. "
 387         "When running a server, please use the latest version of libevent.",
 388         v,m);
 389     badness = "SLOW";
 390   }
 391
 392   *badness_out = badness;
 393 }
 394
 395 #if defined(LIBEVENT_VERSION)
 396 #define HEADER_VERSION LIBEVENT_VERSION
 397 #elif defined(_EVENT_VERSION)
 398 #define HEADER_VERSION _EVENT_VERSION
 399 #endif
 400
 401 /** See whether the headers we were built against differ from the library we
 402  * linked against so much that we're likely to crash.  If so, warn the
 403  * user. */
 404 void
 405 tor_check_libevent_header_compatibility(void)
 406 {
 407   (void) le_versions_compatibility;
 408   (void) tor_decode_libevent_version;
 409
 410   /* In libevent versions before 2.0, it's hard to keep binary compatibility
 411    * between upgrades, and unpleasant to detect when the version we compiled
 412    * against is unlike the version we have linked against. Here's how. */
 413 #if defined(HEADER_VERSION) && defined(HAVE_EVENT_GET_VERSION)
 414   /* We have a header-file version and a function-call version. Easy. */
 415   if (strcmp(HEADER_VERSION, event_get_version())) {
 416     le_version_t v1, v2;
 417     int compat1 = -1, compat2 = -1;
 418     int verybad;
 419     v1 = tor_decode_libevent_version(HEADER_VERSION);
 420     v2 = tor_decode_libevent_version(event_get_version());
 421     compat1 = le_versions_compatibility(v1);
 422     compat2 = le_versions_compatibility(v2);
 423
 424     verybad = compat1 != compat2;
 425
 426     log(verybad ? LOG_WARN : LOG_NOTICE,
 427         LD_GENERAL, "We were compiled with headers from version %s "
 428         "of Libevent, but we're using a Libevent library that says it's "
 429         "version %s.", HEADER_VERSION, event_get_version());
 430     if (verybad)
 431       log_warn(LD_GENERAL, "This will almost certainly make Tor crash.");
 432     else
 433       log_info(LD_GENERAL, "I think these versions are binary-compatible.");
 434   }
 435 #elif defined(HAVE_EVENT_GET_VERSION)
 436   /* event_get_version but no _EVENT_VERSION.  We might be in 1.4.0-beta or
 437      earlier, where that's normal.  To see whether we were compiled with an
 438      earlier version, let's see whether the struct event defines MIN_HEAP_IDX.
 439   */
 440 #ifdef HAVE_STRUCT_EVENT_MIN_HEAP_IDX
 441   /* The header files are 1.4.0-beta or later. If the version is not
 442    * 1.4.0-beta, we are incompatible. */
 443   {
 444     if (strcmp(event_get_version(), "1.4.0-beta")) {
 445       log_warn(LD_GENERAL, "It's a little hard to tell, but you seem to have "
 446                "Libevent 1.4.0-beta header files, whereas you have linked "
 447                "against Libevent %s.  This will probably make Tor crash.",
 448                event_get_version());
 449     }
 450   }
 451 #else
 452   /* Our headers are 1.3e or earlier. If the library version is not 1.4.x or
 453      later, we're probably fine. */
 454   {
 455     const char *v = event_get_version();
 456     if ((v[0] == '1' && v[2] == '.' && v[3] > '3') || v[0] > '1') {
 457       log_warn(LD_GENERAL, "It's a little hard to tell, but you seem to have "
 458                "Libevent header file from 1.3e or earlier, whereas you have "
 459                "linked against Libevent %s.  This will probably make Tor "
 460                "crash.", event_get_version());
 461     }
 462   }
 463 #endif
 464
 465 #elif defined(HEADER_VERSION)
 466 #warn "_EVENT_VERSION is defined but not get_event_version(): Libevent is odd."
 467 #else
 468   /* Your libevent is ancient. */
 469 #endif
 470 }
 471
 472 /*
 473   If possible, we're going to try to use Libevent's periodic timer support,
 474   since it does a pretty good job of making sure that periodic events get
 475   called exactly M seconds apart, rather than starting each one exactly M
 476   seconds after the time that the last one was run.
 477  */
 478 #ifdef HAVE_EVENT2_EVENT_H
 479 #define HAVE_PERIODIC
 480 #define PERIODIC_FLAGS EV_PERSIST
 481 #else
 482 #define PERIODIC_FLAGS 0
 483 #endif
 484
 485 /** Represents a timer that's run every N microseconds by Libevent. */
 486 struct periodic_timer_t {
 487   /** Underlying event used to implement this periodic event. */
 488   struct event *ev;
 489   /** The callback we'll be invoking whenever the event triggers */
 490   void (*cb)(struct periodic_timer_t *, void *);
 491   /** User-supplied data for the callback */
 492   void *data;
 493 #ifndef HAVE_PERIODIC
 494   /** If Libevent doesn't know how to invoke events every N microseconds,
 495    * we'll need to remember the timeout interval here. */
 496   struct timeval tv;
 497 #endif
 498 };
 499
 500 /** Libevent callback to implement a periodic event. */
 501 static void
 502 periodic_timer_cb(evutil_socket_t fd, short what, void *arg)
 503 {
 504   periodic_timer_t *timer = arg;
 505   (void) what;
 506   (void) fd;
 507 #ifndef HAVE_PERIODIC
 508   /** reschedule the event as needed. */
 509   event_add(timer->ev, &timer->tv);
 510 #endif
 511   timer->cb(timer, timer->data);
 512 }
 513
 514 /** Create and schedule a new timer that will run every <b>tv</b> in
 515  * the event loop of <b>base</b>.  When the timer fires, it will
 516  * run the timer in <b>cb</b> with the user-supplied data in <b>data</b>. */
 517 periodic_timer_t *
 518 periodic_timer_new(struct event_base *base,
 519                    const struct timeval *tv,
 520                    void (*cb)(periodic_timer_t *timer, void *data),
 521                    void *data)
 522 {
 523   periodic_timer_t *timer;
 524   tor_assert(base);
 525   tor_assert(tv);
 526   tor_assert(cb);
 527   timer = tor_malloc_zero(sizeof(periodic_timer_t));
 528   if (!(timer->ev = tor_event_new(base, -1, PERIODIC_FLAGS,
 529                                   periodic_timer_cb, timer))) {
 530     tor_free(timer);
 531     return NULL;
 532   }
 533   timer->cb = cb;
 534   timer->data = data;
 535 #ifndef HAVE_PERIODIC
 536   memcpy(&timer->tv, tv, sizeof(struct timeval));
 537 #endif
 538   event_add(timer->ev, (struct timeval *)tv); /*drop const for old libevent*/
 539   return timer;
 540 }
 541
 542 /** Stop and free a periodic timer */
 543 void
 544 periodic_timer_free(periodic_timer_t *timer)
 545 {
 546   if (!timer)
 547     return;
 548   tor_event_free(timer->ev);
 549   tor_free(timer);
 550 }