eventxx

   1 #ifndef _EVENTXX_HPP_
   2 #define _EVENTXX_HPP_
   3
   4 #include <sys/types.h> // timeval (hack -> event.h don't include it)
   5 #include <stdexcept>   // std::exception, std::invalid_argument,
   6                        // std::runtime_error, std::bad_alloc
   7
   8 /** @mainpage
   9  *
  10  * @section Introduction
  11  *
  12  * The libevent API provides a mechanism to execute a callback function when a
  13  * specific event occurs on a file descriptor or after a timeout has been
  14  * reached. Furthermore, libevent also support callbacks due to signals or
  15  * regular timeouts.
  16  *
  17  * libevent is meant to replace the event loop found in event driven network
  18  * servers. An application just needs to call dispatcher::dispatch() and then
  19  * add or remove events dynamically without having to change the event loop.
  20  *
  21  * Currently, libevent supports /dev/poll, kqueue(2), select(2), poll(2) and
  22  * epoll(4). It also has experimental support for real-time signals. The
  23  * internal event mechanism is completely independent of the exposed event API,
  24  * and a simple update of libevent can provide new functionality without having
  25  * to redesign the applications. As a result, Libevent allows for portable
  26  * application development and provides the most scalable event notification
  27  * mechanism available on an operating system. Libevent should compile on Linux,
  28  * *BSD, Mac OS X, Solaris and Windows.
  29  *
  30  * This is a simple, direct, one-header inline C++ wrapper for libevent.
  31  * It's designed to be as close to use to libevent without compromising modern
  32  * C++ programming techniques and efficiency (since all implementation is
  33  * trivial and inline, theoretically, it imposes no overhead at all).
  34  *
  35  *
  36  * @section Usage
  37  *
  38  * The best way to explain how this works is by examples. TODO
  39  *
  40  * @author Leandro Lucarella <llucarella@integratech.com.ar>
  41  * @version 0.1
  42  * @par License
  43  *      This program is under the BOLA license (see
  44  *      http://auriga.wearlab.de/~alb/bola/)
  45  *
  46  */
  47
  48
  49 /**
  50  * Namespace for all symbols libevent C++ wrapper defines.
  51  */
  52 namespace eventxx
  53 {
  54
  55
  56 // All libevent C API symbols and other internal stuff goes here.
  57 namespace internal
  58 {
  59 #include <event.h>
  60 }
  61
  62
  63 /// @defgroup exceptions Exceptions
  64 //@{
  65
  66
  67 /**
  68  * Base class for all libevent exceptions.
  69  */
  70 struct exception: public std::exception
  71 {
  72 };
  73
  74
  75 /**
  76  * Invalid event exception.
  77  *
  78  * This exception is thrown when passing an invalid event to a function, the
  79  * reason is given in the what() description but it usually means that the you
  80  * are making some restricted operation with an active event.
  81  *
  82  * If you hit this exception, you probably got a programming error.
  83  */
  84 struct invalid_event: public std::invalid_argument, public exception
  85 {
  86
  87         /**
  88          * Creates an invalid event exception with a reason.
  89          *
  90          * @param what Reason why the event is invalid).
  91          */
  92         explicit invalid_event(const std::string& what) throw():
  93                 std::invalid_argument(what)
  94         {
  95         }
  96
  97 }; // struct invalid_event
  98
  99
 100 /**
 101  * Invalid priority exception.
 102  *
 103  * This exception is thrown when passing an invalid priority to a function. This
 104  * usually means you don't have enought priority queues in your dispatcher, so
 105  * you should have allocated more in the constructor.
 106  *
 107  * If you hit this exception, you probably got a programming error.
 108  *
 109  * @see dispatcher::dispatcher(int) to allocate more priority queues.
 110  */
 111 struct invalid_priority: public std::invalid_argument, public exception
 112 {
 113
 114         /**
 115          * Creates an invalid priority exception with a reason.
 116          *
 117          * @param what Reason why the priority is invalid).
 118          */
 119         explicit invalid_priority(const std::string& what
 120                         = "invalid priority value") throw():
 121                 std::invalid_argument(what)
 122         {
 123         }
 124
 125 }; // struct invalid_priority
 126
 127 //@}
 128
 129
 130 /// Miscelaneous constants
 131 enum
 132 {
 133         DEFAULT_PRIORITY = -1,      ///< Default priority (the middle value).
 134         ONCE = EVLOOP_ONCE,         ///< Loop just once.
 135         NONBLOCK = EVLOOP_NONBLOCK  ///< Don't block the event loop.
 136 };
 137
 138
 139 /// C function used as callback in the C API.
 140 typedef void (*ccallback_type)(int, short, void*);
 141
 142
 143 /**
 144  * Time used for timeout values.
 145  *
 146  * This timeout is compose of seconds and microseconds.
 147  */
 148 struct time: ::timeval
 149 {
 150
 151         /**
 152          * Creates a new time with @p sec seconds and @p usec microseconds.
 153          *
 154          * @param sec Number of seconds.
 155          * @param usec Number of microseconds.
 156          */
 157         time(long sec = 0l, long usec = 0l) throw()
 158                 { tv_sec = sec; tv_usec = usec; }
 159
 160         /**
 161          * Gets the number of seconds.
 162          *
 163          * @return Number of seconds.
 164          */
 165         long sec() const throw() { return tv_sec; };
 166
 167         /**
 168          * Gets the number of microseconds.
 169          *
 170          * @return Number of microseconds.
 171          */
 172         long usec() const throw() { return tv_usec; };
 173
 174         /**
 175          * Sets the number of seconds.
 176          *
 177          * @param s Number of seconds.
 178          */
 179         void sec(long s) throw() { tv_sec = s; };
 180
 181         /**
 182          * Sets the number of microseconds.
 183          *
 184          * @param u Number of microseconds.
 185          */
 186         void usec(long u) throw() { tv_usec = u; };
 187
 188 }; // struct time
 189
 190
 191 /// @defgroup events Events
 192 //@{
 193
 194 /**
 195  * Type of events.
 196  *
 197  * There are 4 kind of events: eventxx::TIMEOUT, eventxx::READ, eventxx::WRITE
 198  * or eventxx::SIGNAL. eventxx::PERSIST is not an event, is an event modifier
 199  * flag, that tells eventxx that this event should live until dispatcher::del()
 200  * is called. You can use, for example:
 201  * @code
 202  * eventxx::event(fd, eventxx::READ | eventxx::PERSIST, ...);
 203  * @endcode
 204  */
 205 enum type
 206 {
 207         TIMEOUT = EV_TIMEOUT, ///< Timeout event.
 208         READ = EV_READ,       ///< Read event.
 209         WRITE = EV_WRITE,     ///< Write event.
 210         SIGNAL = EV_SIGNAL,   ///< Signal event.
 211         PERSIST = EV_PERSIST  ///< Not really an event, is an event modifier.
 212 };
 213
 214 /**
 215  * Basic event from which all events derive.
 216  *
 217  * All events derive from this class, so it's useful for use in containers,
 218  * like:
 219  * @code
 220  * std::list< eventxx::basic_event* > events;
 221  * @endcode
 222  */
 223 struct basic_event: internal::event
 224 {
 225
 226         /**
 227          * Checks if there is an event pending.
 228          *
 229          * @param ev Type of event to check.
 230          *
 231          * @return true if there is a pending event, false if not.
 232          */
 233         bool pending(type ev) const throw()
 234         {
 235                 // HACK libevent don't use const
 236                 return event_pending(const_cast< basic_event* >(this), ev, 0);
 237         }
 238
 239         /**
 240          * Timeout of the event.
 241          *
 242          * @return Timeout of the event.
 243          */
 244         time timeout() const throw()
 245         {
 246                 time tv;
 247                 // HACK libevent don't use const
 248                 event_pending(const_cast< basic_event* >(this), EV_TIMEOUT, &tv);
 249                 return tv;
 250         }
 251
 252         /**
 253          * Sets the event's priority.
 254          *
 255          * @param priority New event priority.
 256          *
 257          * @pre The event must be added to some dispatcher.
 258          *
 259          * @see dispatcher::dispatcher(int)
 260          */
 261         void priority(int priority) const throw(invalid_event, invalid_priority)
 262         {
 263                 if (ev_flags & EVLIST_ACTIVE)
 264                         throw invalid_event("can't change the priority of an "
 265                                         "active event");
 266                 // HACK libevent don't use const
 267                 if (event_priority_set(const_cast< basic_event* >(this),
 268                                         priority))
 269                         throw invalid_priority();
 270         }
 271
 272         /**
 273          * Event's file descriptor.
 274          *
 275          * @return Event's file descriptor.
 276          */
 277         int fd() const throw()
 278         {
 279                 return EVENT_FD(this);
 280         }
 281
 282         /// @note This is an abstract class, you can't instantiate it.
 283         protected:
 284                 basic_event() throw() {}
 285                 basic_event(const basic_event&);
 286                 basic_event& operator= (const basic_event&);
 287
 288 }; // struct basic_event
 289
 290
 291 /**
 292  * Generic event object.
 293  *
 294  * This object stores all the information about an event, incluiding a callback
 295  * functor, which is called when the event is fired. The template parameter
 296  * must be a functor (callable object or function) that can take 2 parameters:
 297  * an integer (the file descriptor of the fired event) and an event::type (the
 298  * type of event being fired).
 299  * There is a specialized version of this class which takes as the template
 300  * parameter a C function with the ccallback_type signature, just like C
 301  * libevent API does.
 302  *
 303  * @see eventxx::event< ccallback_type >
 304  */
 305 template < typename F >
 306 struct event: basic_event
 307 {
 308
 309         /**
 310          * Creates a new event.
 311          *
 312          * @param fd File descriptor to monitor for events.
 313          * @param ev Type of events to monitor (see eventxx::type).
 314          * @param handler Callback functor.
 315          */
 316         event(int fd, short ev, F& handler) throw()
 317         {
 318                 event_set(this, fd, ev, &wrapper,
 319                                 reinterpret_cast< void* >(&handler));
 320         }
 321
 322         protected:
 323                 event() {}
 324                 static void wrapper(int fd, short ev, void* h)
 325                 {
 326                         F& handler = *reinterpret_cast< F* >(h);
 327                         // Hackish, but this way the handler can get a clean
 328                         // event type
 329                         handler(fd, *reinterpret_cast< type* >(&ev));
 330                 }
 331
 332 }; // struct event< F >
 333
 334
 335 /**
 336  * This is the specialization of eventxx::event for C-style callbacks.
 337  *
 338  * @see eventxx::event
 339  */
 340 template <>
 341 struct event< ccallback_type >: basic_event
 342 {
 343
 344         /**
 345          * Creates a new event.
 346          *
 347          * @param fd File descriptor to monitor for events.
 348          * @param ev Type of events to monitor (see eventxx::type).
 349          * @param handler C-style callback function.
 350          * @param arg Arbitrary pointer to pass to the handler as argument.
 351          */
 352         event(int fd, short ev, ccallback_type handler, void* arg) throw()
 353         {
 354                 event_set(this, fd, ev, handler, arg);
 355         }
 356
 357         protected:
 358                 event() {}
 359
 360 }; // struct event< ccallback_type >
 361
 362
 363 /**
 364  * Timer event object.
 365  *
 366  * This is just a special case of event that is fired only when a timeout is
 367  * reached. It's just a shortcut to:
 368  * @code
 369  * event(-1, 0, handler);
 370  * @endcode
 371  *
 372  * @note This event can't eventxx::PERSIST.
 373  * @see timer< ccallback_type >
 374  */
 375 template < typename F >
 376 struct timer: event< F >
 377 {
 378
 379         /**
 380          * Creates a new timer event.
 381          *
 382          * @param handler Callback functor.
 383          */
 384         timer(F& handler) throw()
 385         {
 386                 evtimer_set(this, &event< F >::wrapper,
 387                         reinterpret_cast< void* >(&handler));
 388         }
 389
 390 }; // struct timer< F >
 391
 392
 393 /**
 394  * This is the specialization of eventxx::timer for C-style callbacks.
 395  *
 396  * @note This event can't eventxx::PERSIST.
 397  * @see timer
 398  */
 399 template <>
 400 struct timer< ccallback_type >: event< ccallback_type >
 401 {
 402
 403         /**
 404          * Creates a new timer event.
 405          *
 406          * @param handler C-style callback function.
 407          * @param arg Arbitrary pointer to pass to the handler as argument.
 408          */
 409         timer(ccallback_type handler, void* arg) throw()
 410         {
 411                 evtimer_set(this, handler, arg);
 412         }
 413
 414 }; // struct timer< ccallback_type >
 415
 416
 417 /**
 418  * Signal event object.
 419  *
 420  * This is just a special case of event that is fired when a signal is raised
 421  * (instead of a file descriptor being active). It's just a shortcut to:
 422  * @code
 423  * event(signum, eventxx::SIGNAL, handler);
 424  * @endcode
 425  *
 426  * @note This event always eventxx::PERSIST.
 427  * @see signal< ccallback_type >
 428  */
 429 template < typename F >
 430 struct signal: event< F >
 431 {
 432
 433         /**
 434          * Creates a new singal event.
 435          *
 436          * @param signum Signal number to monitor.
 437          * @param handler Callback functor.
 438          */
 439         signal(int signum, F& handler) throw()
 440         {
 441                 signal_set(this, signum, &event< F >::wrapper,
 442                         reinterpret_cast< void* >(&handler));
 443         }
 444
 445         /**
 446          * Event's signal number.
 447          *
 448          * @return Event's signal number.
 449          */
 450         int signum() const
 451         {
 452                 return EVENT_SIGNAL(this);
 453         }
 454
 455 }; // struct signal<F>
 456
 457
 458 /**
 459  * This is the specialization of eventxx::signal for C-style callbacks.
 460  *
 461  * @note This event always eventxx::PERSIST.
 462  * @see signal
 463  */
 464 template <>
 465 struct signal< ccallback_type >: event< ccallback_type >
 466 {
 467
 468         /**
 469          * Creates a new signal event.
 470          *
 471          * @param signum Signal number to monitor.
 472          * @param handler C-style callback function.
 473          * @param arg Arbitrary pointer to pass to the handler as argument.
 474          */
 475         signal(int signum, ccallback_type handler, void* arg) throw()
 476         {
 477                 signal_set(this, signum, handler, arg);
 478         }
 479
 480         /**
 481          * Event's signal number.
 482          *
 483          * @return Event's signal number.
 484          */
 485         int signum() const
 486         {
 487                 return EVENT_SIGNAL(this);
 488         }
 489
 490 }; // struct signal< ccallback_type >
 491
 492
 493 /// Shortcut to C-style event.
 494 typedef eventxx::event< ccallback_type > cevent;
 495
 496 /// Shortcut to C-style timer.
 497 typedef eventxx::timer< ccallback_type > ctimer;
 498
 499 /// Shortcut to C-style signal handler.
 500 typedef eventxx::signal< ccallback_type > csignal;
 501
 502
 503 //@}
 504
 505
 506 /**
 507  * Event dispatcher.
 508  *
 509  * This class is the responsable for looping and dispatching events.
 510  */
 511 struct dispatcher
 512 {
 513
 514         /**
 515          * Creates a default dispatcher (with just 1 priority).
 516          *
 517          * @see dispatcher(int) if you want to create a dispatcher with more
 518          *      priorities.
 519          */
 520         dispatcher() throw()
 521         {
 522                 _event_base = static_cast< internal::event_base* >(internal::event_init());
 523         }
 524
 525         /**
 526          * Creates a dispatcher with npriorities priorities.
 527          *
 528          * @param npriorities Number of priority queues to use.
 529          */
 530         dispatcher(int npriorities) throw(std::bad_alloc)
 531         {
 532                 _event_base = static_cast< internal::event_base* >(internal::event_init());
 533                 if (!_event_base) throw std::bad_alloc();
 534                 // Can't fail because there is no way that it has active events
 535                 internal::event_base_priority_init(_event_base, npriorities);
 536         }
 537
 538 #ifdef EVENT_BASE_FREE_FIX
 539         ~dispatcher() throw() { event_base_free(_event_base); }
 540 #else
 541 #warning "The dispatcher class *will* leak memory because of a libevent bug, see http://www.mail-archive.com/libevent-users@monkey.org/msg00110.html for more info an a patch. If you already have this patch, please -DEVENT_BASE_FREE_FIX to your compiler to make this message disappear and really free the dispatcher memory using event_base_free()."
 542 #endif
 543
 544         /**
 545          * Adds an event to the dispatcher.
 546          *
 547          * @param e Event to add.
 548          * @param priority Priority of the event.
 549          */
 550         void add(basic_event& e, int priority = DEFAULT_PRIORITY)
 551                 throw(invalid_priority)
 552         {
 553                 internal::event_base_set(_event_base, &e);
 554                 if (priority != DEFAULT_PRIORITY
 555                                 && internal::event_priority_set(&e, priority))
 556                         throw invalid_priority();
 557                 internal::event_add(&e, 0);
 558         }
 559
 560         /**
 561          * Adds an event to the dispatcher with a timeout.
 562          *
 563          * The event is fired when there is activity on e or when to has elapsed,
 564          * whatever come first.
 565          *
 566          * @param e Event to add.
 567          * @param to Timeout.
 568          * @param priority Priority of the event.
 569          */
 570         void add(basic_event& e, const time& to,
 571                         int priority = DEFAULT_PRIORITY)
 572                 throw(invalid_priority)
 573         {
 574                 internal::event_base_set(_event_base, &e);
 575                 if (priority != DEFAULT_PRIORITY
 576                                 && internal::event_priority_set(&e, priority))
 577                         throw invalid_priority();
 578                 internal::event_add(&e, const_cast< time* >(&to)); // XXX HACK libevent don't use const
 579         }
 580
 581         /**
 582          * Adds a temporary event.
 583          *
 584          * Adds a temporary event, without the need of instantiating a new event
 585          * object. Events added this way can't eventxx::PERSIST.
 586          *
 587          * @param fd File descriptor to monitor for events.
 588          * @param ev Type of events to monitor.
 589          * @param handler Callback function.
 590          */
 591         template < typename F >
 592         void add_once(int fd, type ev, F& handler)
 593         {
 594                 internal::event_once(fd, ev, &dispatcher::wrapper< F >,
 595                                 reinterpret_cast< void* >(&handler), 0);
 596         }
 597
 598         /**
 599          * Adds a temporary event to with a C-style callback.
 600          *
 601          * Adds a temporary event, without the need of instantiating a new event
 602          * object. Events added this way can't eventxx::PERSIST.
 603          *
 604          * @param fd File descriptor to monitor for events.
 605          * @param ev Type of events to monitor.
 606          * @param handler Callback function.
 607          * @param arg Arbitrary pointer to pass to the handler as argument.
 608          */
 609         void add_once(int fd, type ev, ccallback_type handler, void* arg)
 610         {
 611                 internal::event_once(fd, ev, handler, arg, 0);
 612         }
 613
 614         /**
 615          * Adds a temporary event.
 616          *
 617          * Adds a temporary event, without the need of instantiating a new event
 618          * object. Events added this way can't eventxx::PERSIST.
 619          *
 620          * @param fd File descriptor to monitor for events.
 621          * @param ev Type of events to monitor.
 622          * @param handler Callback function.
 623          * @param to Timeout.
 624          */
 625         template < typename F >
 626         void add_once(int fd, type ev, F& handler, const time& to)
 627         {
 628                 internal::event_once(fd, ev, &dispatcher::wrapper< F >,
 629                                 reinterpret_cast< void* >(&handler),
 630                                 const_cast< time* >(&to)); // XXX HACK libevent don't use const
 631         }
 632
 633         /**
 634          * Adds a temporary event with a C-style callback.
 635          *
 636          * Adds a temporary event, without the need of instantiating a new event
 637          * object. Events added this way can't eventxx::PERSIST.
 638          *
 639          * @param fd File descriptor to monitor for events.
 640          * @param ev Type of events to monitor.
 641          * @param handler Callback function.
 642          * @param arg Arbitrary pointer to pass to the handler as argument.
 643          * @param to Timeout.
 644          */
 645         void add_once(int fd, type ev, ccallback_type handler, void* arg, const time& to)
 646         {
 647                 internal::event_once(fd, ev, handler, arg, const_cast< time* >(&to)); // XXX HACK libevent don't use const
 648         }
 649
 650         /**
 651          * Adds a temporary timer.
 652          *
 653          * Adds a temporary timer, without the need of instantiating a new timer
 654          * object.
 655          *
 656          * @param handler Callback function.
 657          * @param to Timer's timeout.
 658          */
 659         template < typename F >
 660         void add_once_timer(F& handler, const time& to)
 661         {
 662                 internal::event_once(-1, EV_TIMEOUT, &dispatcher::wrapper< F >,
 663                                 reinterpret_cast< void* >(&handler),
 664                                 const_cast< time* >(&to)); // XXX HACK libevent don't use const
 665         }
 666
 667         /**
 668          * Adds a temporary timer with a C-style callback.
 669          *
 670          * Adds a temporary timer, without the need of instantiating a new timer
 671          * object.
 672          *
 673          * @param handler Callback function.
 674          * @param arg Arbitrary pointer to pass to the handler as argument.
 675          * @param to Timer's timeout.
 676          */
 677         void add_once_timer(ccallback_type handler, void* arg, const time& to)
 678         {
 679                 internal::event_once(-1, EV_TIMEOUT, handler, arg, const_cast< time* >(&to)); // XXX HACK libevent don't use const
 680         }
 681
 682         /**
 683          * Removes an event.
 684          *
 685          * The event e will be no longer monitored by this dispatcher.
 686          *
 687          * @param e Event to remove.
 688          */
 689         void del(basic_event& e) throw()
 690         {
 691                 internal::event_del(&e);
 692         }
 693
 694         /**
 695          * Main dispatcher loop.
 696          *
 697          * This function takes the control of the program, waiting for an event
 698          * and calling its callbacks when it's fired. It only returns under
 699          * this conditions:
 700          * - exit() was called.
 701          * - All events were del()eted.
 702          * - Another internal error.
 703          * - eventxx::ONCE flag was set.
 704          * - eventxx::NONBLOCK flag was set.
 705          *
 706          * @param flags If eventxx::ONCE is specified, then just one event is
 707          *              processed, if eventxx::NONBLOCK is specified, then this
 708          *              function returns even if there are no pending events.
 709          */
 710         int dispatch(int flags = 0) // TODO  throw(exception)
 711         {
 712                 return internal::event_base_loop(_event_base, flags);
 713         }
 714
 715         /**
 716          * Exit the dispatch() loop.
 717          *
 718          * @param to If a timeout is given, the loop exits after the specified
 719          *           time is elapsed.
 720          */
 721         int exit(const time& to = time())
 722         {
 723                 // XXX HACK libevent don't use const
 724                 return internal::event_base_loopexit(_event_base,
 725                         const_cast< time* >(&to));
 726         }
 727
 728         protected:
 729                 internal::event_base* _event_base;
 730                 template < typename F >
 731                 static void wrapper(int fd, type ev, void* h)
 732                 {
 733                         F& handler = *reinterpret_cast< F* >(h);
 734                         handler(fd, *reinterpret_cast< type* >(&ev));
 735                 }
 736
 737 }; // struct dispatcher
 738
 739
 740 } // namespace event
 741
 742 #endif // _EVENTXX_HPP_
 743
 744 // vim: set filetype=cpp :