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 };
 135
 136
 137 /// C function used as callback in the C API.
 138 typedef void (*ccallback_type)(int, short, void*);
 139
 140
 141 /**
 142  * Time used for timeout values.
 143  *
 144  * This timeout is compose of seconds and microseconds.
 145  */
 146 struct time: ::timeval
 147 {
 148
 149         /**
 150          * Creates a new time with @p sec seconds and @p usec microseconds.
 151          *
 152          * @param sec Number of seconds.
 153          * @param usec Number of microseconds.
 154          */
 155         time(long sec = 0l, long usec = 0l) throw()
 156                 { tv_sec = sec; tv_usec = usec; }
 157
 158         /**
 159          * Gets the number of seconds.
 160          *
 161          * @return Number of seconds.
 162          */
 163         long sec() const throw() { return tv_sec; };
 164
 165         /**
 166          * Gets the number of microseconds.
 167          *
 168          * @return Number of microseconds.
 169          */
 170         long usec() const throw() { return tv_usec; };
 171
 172         /**
 173          * Sets the number of seconds.
 174          *
 175          * @param s Number of seconds.
 176          */
 177         void sec(long s) throw() { tv_sec = s; };
 178
 179         /**
 180          * Sets the number of microseconds.
 181          *
 182          * @param u Number of microseconds.
 183          */
 184         void usec(long u) throw() { tv_usec = u; };
 185
 186 }; // struct time
 187
 188
 189 /// @defgroup events Events
 190 //@{
 191
 192 /**
 193  * Basic event from which all events derive.
 194  *
 195  * All events derive from this class, so it's useful for use in containers,
 196  * like:
 197  * @code
 198  * std::list< eventxx::basic_event* > events;
 199  * @endcode
 200  */
 201 struct basic_event: internal::event
 202 {
 203
 204         /**
 205          * Checks if there is an event pending.
 206          *
 207          * @param ev Type of event to check.
 208          *
 209          * @return true if there is a pending event, false if not.
 210          */
 211         bool pending(short ev) const throw()
 212         {
 213                 // HACK libevent don't use const
 214                 return event_pending(const_cast< basic_event* >(this), ev, 0);
 215         }
 216
 217         /**
 218          * Timeout of the event.
 219          *
 220          * @return Timeout of the event.
 221          */
 222         time timeout() const throw()
 223         {
 224                 time tv;
 225                 // HACK libevent don't use const
 226                 event_pending(const_cast< basic_event* >(this), EV_TIMEOUT, &tv);
 227                 return tv;
 228         }
 229
 230         /**
 231          * Sets the event's priority.
 232          *
 233          * @param priority New event priority.
 234          *
 235          * @see dispatcher::dispatcher(int)
 236          */
 237         void priority(int priority) const throw(invalid_event, invalid_priority)
 238         {
 239                 if (ev_flags & EVLIST_ACTIVE)
 240                         throw invalid_event("can't change the priority of an "
 241                                         "active event");
 242                 // HACK libevent don't use const
 243                 if (event_priority_set(const_cast< basic_event* >(this),
 244                                         priority))
 245                         throw invalid_priority();
 246         }
 247
 248         /**
 249          * Event's file descriptor.
 250          *
 251          * @return Event's file descriptor.
 252          */
 253         int fd() const throw()
 254         {
 255                 return EVENT_FD(this);
 256         }
 257
 258         /// @note This is an abstract class, you can't instantiate it.
 259         protected:
 260                 basic_event() throw() {}
 261                 basic_event(const basic_event&);
 262                 basic_event& operator= (const basic_event&);
 263
 264 }; // struct basic_event
 265
 266
 267 /**
 268  * Generic event object.
 269  *
 270  * This object stores all the information about an event, incluiding a callback
 271  * functor, which is called then the event is fired. Then template parameter
 272  * must be a callable object (functor) that can take 2 parameters: an integer
 273  * (the file descriptor of the fired event) and a short (the type of event
 274  * fired: EV_TIMEOUT, EV_SIGNAL, EV_READ, EV_WRITE). There is an specialized
 275  * version of this class which takes as the template parameter a C function
 276  * with the ccallback_type signature, just like C libevent API does.
 277  *
 278  * @see eventxx::event< ccallback_type >
 279  */
 280 template < typename F >
 281 struct event: basic_event
 282 {
 283
 284         /**
 285          * Creates a new event.
 286          *
 287          * @param fd File descriptor to monitor for events.
 288          * @param ev Type of events to monitor.
 289          * @param handler Callback functor.
 290          * @param priority Priority of the event.
 291          */
 292         event(int fd, short ev, F& handler, int priority = DEFAULT_PRIORITY)
 293                 throw(invalid_priority)
 294         {
 295                 event_set(this, fd, ev, &wrapper, reinterpret_cast< void* >(&handler));
 296                 if (priority != DEFAULT_PRIORITY
 297                                 && event_priority_set(this, priority))
 298                         throw invalid_priority();
 299         }
 300
 301         protected:
 302                 event() {}
 303                 static void wrapper(int fd, short ev, void* h)
 304                 {
 305                         F& handler = *reinterpret_cast< F* >(h);
 306                         handler(fd, ev);
 307                 }
 308
 309 }; // struct event< F >
 310
 311
 312 /**
 313  * This is the specialization of eventxx::event for C-style callbacks.
 314  *
 315  * @see eventxx::event
 316  */
 317 template <>
 318 struct event< ccallback_type >: basic_event
 319 {
 320
 321         /**
 322          * Creates a new event.
 323          *
 324          * @param fd File descriptor to monitor for events.
 325          * @param ev Type of events to monitor.
 326          * @param handler C-style callback function.
 327          * @param arg Arbitrary pointer to pass to the handler as argument.
 328          * @param priority Priority of the event.
 329          */
 330         event(int fd, short ev, ccallback_type handler, void* arg,
 331                         int priority = DEFAULT_PRIORITY)
 332                 throw(invalid_priority)
 333         {
 334                 event_set(this, fd, ev, handler, arg);
 335                 if (priority != DEFAULT_PRIORITY
 336                                 && event_priority_set(this, priority))
 337                         throw invalid_priority();
 338         }
 339
 340         protected:
 341                 event() {}
 342
 343 }; // struct event< ccallback_type >
 344
 345
 346 /**
 347  * Timer event object.
 348  *
 349  * This is just a special case of event that is fired only when a timeout is
 350  * reached. It's just a shortcut to event(-1, 0, handler, priority).
 351  *
 352  * @note This event can't EV_PERSIST.
 353  * @see timer< ccallback_type >
 354  */
 355 template < typename F >
 356 struct timer: event< F >
 357 {
 358
 359         /**
 360          * Creates a new timer event.
 361          *
 362          * @param handler Callback functor.
 363          * @param priority Priority of the event.
 364          */
 365         timer(F& handler, int priority = DEFAULT_PRIORITY)
 366                 throw(invalid_priority)
 367         {
 368                 evtimer_set(this, &event< F >::wrapper,
 369                         reinterpret_cast< void* >(&handler));
 370                 if (priority != DEFAULT_PRIORITY
 371                                 && event_priority_set(this, priority))
 372                         throw invalid_priority();
 373         }
 374
 375 }; // struct timer< F >
 376
 377
 378 /**
 379  * This is the specialization of eventxx::timer for C-style callbacks.
 380  *
 381  * @note This event can't EV_PERSIST.
 382  * @see timer
 383  */
 384 template <>
 385 struct timer< ccallback_type >: event< ccallback_type >
 386 {
 387
 388         /**
 389          * Creates a new timer event.
 390          *
 391          * @param handler C-style callback function.
 392          * @param arg Arbitrary pointer to pass to the handler as argument.
 393          * @param priority Priority of the event.
 394          */
 395         timer(ccallback_type handler, void* arg, int priority = DEFAULT_PRIORITY)
 396                 throw(invalid_priority)
 397         {
 398                 evtimer_set(this, handler, arg);
 399                 if (priority != DEFAULT_PRIORITY
 400                                 && event_priority_set(this, priority))
 401                         throw invalid_priority();
 402         }
 403
 404 }; // struct timer< ccallback_type >
 405
 406
 407 /**
 408  * Signal event object.
 409  *
 410  * This is just a special case of event that is fired when a signal is raised
 411  * (instead of a file descriptor being active). It's just a shortcut to
 412  * event(signal, EV_SIGNAL, handler, priority).
 413  *
 414  * @note This event allways EV_PERSIST.
 415  * @see signal< ccallback_type >
 416  */
 417 template < typename F >
 418 struct signal: event< F >
 419 {
 420
 421         /**
 422          * Creates a new singal event.
 423          *
 424          * @param signum Signal number to monitor.
 425          * @param handler Callback functor.
 426          * @param priority Priority of the event.
 427          */
 428         signal(int signum, F& handler, int priority = DEFAULT_PRIORITY)
 429                 throw(invalid_priority)
 430         {
 431                 signal_set(this, signum, &event< F >::wrapper,
 432                         reinterpret_cast< void* >(&handler));
 433                 if (priority != DEFAULT_PRIORITY
 434                                 && event_priority_set(this, priority))
 435                         throw invalid_priority();
 436         }
 437
 438         /**
 439          * Event's signal number.
 440          *
 441          * @return Event's signal number.
 442          */
 443         int signum() const
 444         {
 445                 return EVENT_SIGNAL(this);
 446         }
 447
 448 }; // struct signal<F>
 449
 450
 451 /**
 452  * This is the specialization of eventxx::signal for C-style callbacks.
 453  *
 454  * @note This event allways EV_PERSIST.
 455  * @see signal
 456  */
 457 template <>
 458 struct signal< ccallback_type >: event< ccallback_type >
 459 {
 460
 461         /**
 462          * Creates a new signal event.
 463          *
 464          * @param signum Signal number to monitor.
 465          * @param handler C-style callback function.
 466          * @param arg Arbitrary pointer to pass to the handler as argument.
 467          * @param priority Priority of the event.
 468          */
 469         signal(int signum, ccallback_type handler, void* arg,
 470                         int priority = DEFAULT_PRIORITY)
 471                 throw(invalid_priority)
 472         {
 473                 signal_set(this, signum, handler, arg);
 474                 if (priority != DEFAULT_PRIORITY
 475                                 && event_priority_set(this, priority))
 476                         throw invalid_priority();
 477         }
 478
 479         /**
 480          * Event's signal number.
 481          *
 482          * @return Event's signal number.
 483          */
 484         int signum() const
 485         {
 486                 return EVENT_SIGNAL(this);
 487         }
 488
 489 }; // struct signal< ccallback_type >
 490
 491
 492 /// Shortcut to C-style event.
 493 typedef eventxx::event< ccallback_type > cevent;
 494
 495 /// Shortcut to C-style timer.
 496 typedef eventxx::timer< ccallback_type > ctimer;
 497
 498 /// Shortcut to C-style signal handler.
 499 typedef eventxx::signal< ccallback_type > csignal;
 500
 501
 502 //@}
 503
 504
 505 /**
 506  * Event dispatcher.
 507  *
 508  * This class is the responsable for looping and dispatching events.
 509  */
 510 struct dispatcher
 511 {
 512
 513         /**
 514          * Creates a default dispatcher (with just 1 prioriority).
 515          *
 516          * @see dispatcher(int) if you want to create a dispatcher with more
 517          *      prioriorities.
 518          */
 519         dispatcher() throw()
 520         {
 521                 _event_base = static_cast< internal::event_base* >(internal::event_init());
 522         }
 523
 524         /**
 525          * Creates a dispatcher with npriorities prioriorities.
 526          *
 527          * @param npriorities Number of priority queues to use.
 528          */
 529         dispatcher(int npriorities) throw(std::bad_alloc)
 530         {
 531                 _event_base = static_cast< internal::event_base* >(internal::event_init());
 532                 if (!_event_base) throw std::bad_alloc();
 533                 // Can't fail because there is no way that it has active events
 534                 internal::event_base_priority_init(_event_base, npriorities);
 535         }
 536
 537 #ifdef EVENT_BASE_FREE_FIX
 538         ~dispatcher() throw() { event_base_free(_event_base); }
 539 #endif
 540
 541         /**
 542          * Adds an event to the dispatcher.
 543          *
 544          * @param e Event to add.
 545          */
 546         void add(basic_event& e) throw()
 547         {
 548                 internal::event_base_set(_event_base, &e);
 549                 internal::event_add(&e, 0);
 550         }
 551
 552         /**
 553          * Adds an event to the dispatcher with a timeout.
 554          *
 555          * The event is fired when there is activity on e or when to is elapsed,
 556          * whatever come first.
 557          *
 558          * @param e Event to add.
 559          * @param to Timeout.
 560          */
 561         void add(basic_event& e, const time& to) throw()
 562         {
 563                 internal::event_base_set(_event_base, &e);
 564                 internal::event_add(&e, const_cast< time* >(&to)); // XXX HACK libevent don't use const
 565         }
 566
 567         /**
 568          * Adds a temporary event.
 569          *
 570          * Adds a temporary event, without the need of instantiating a new event
 571          * object. Events added this way can't EV_PERSIST.
 572          *
 573          * @param fd File descriptor to monitor for events.
 574          * @param ev Type of events to monitor.
 575          * @param handler Callback function.
 576          */
 577         template < typename F >
 578         void add_once(int fd, short ev, F& handler)
 579         {
 580                 internal::event_once(fd, ev, &dispatcher::wrapper< F >,
 581                                 reinterpret_cast< void* >(&handler), 0);
 582         }
 583
 584         /**
 585          * Adds a temporary event to with a C-style callback.
 586          *
 587          * Adds a temporary event, without the need of instantiating a new event
 588          * object. Events added this way can't EV_PERSIST.
 589          *
 590          * @param fd File descriptor to monitor for events.
 591          * @param ev Type of events to monitor.
 592          * @param handler Callback function.
 593          * @param arg Arbitrary pointer to pass to the handler as argument.
 594          */
 595         void add_once(int fd, short ev, ccallback_type handler, void* arg)
 596         {
 597                 internal::event_once(fd, ev, handler, arg, 0);
 598         }
 599
 600         /**
 601          * Adds a temporary event.
 602          *
 603          * Adds a temporary event, without the need of instantiating a new event
 604          * object. Events added this way can't EV_PERSIST.
 605          *
 606          * @param fd File descriptor to monitor for events.
 607          * @param ev Type of events to monitor.
 608          * @param handler Callback function.
 609          * @param to Timeout.
 610          */
 611         template < typename F >
 612         void add_once(int fd, short ev, F& handler, const time& to)
 613         {
 614                 internal::event_once(fd, ev, &dispatcher::wrapper< F >,
 615                                 reinterpret_cast< void* >(&handler),
 616                                 const_cast< time* >(&to)); // XXX HACK libevent don't use const
 617         }
 618
 619         /**
 620          * Adds a temporary event with a C-style callback.
 621          *
 622          * Adds a temporary event, without the need of instantiating a new event
 623          * object. Events added this way can't EV_PERSIST.
 624          *
 625          * @param fd File descriptor to monitor for events.
 626          * @param ev Type of events to monitor.
 627          * @param handler Callback function.
 628          * @param arg Arbitrary pointer to pass to the handler as argument.
 629          * @param to Timeout.
 630          */
 631         void add_once(int fd, short ev, ccallback_type handler, void* arg, const time& to)
 632         {
 633                 internal::event_once(fd, ev, handler, arg, const_cast< time* >(&to)); // XXX HACK libevent don't use const
 634         }
 635
 636         /**
 637          * Adds a temporary timer.
 638          *
 639          * Adds a temporary timer, without the need of instantiating a new timer
 640          * object.
 641          *
 642          * @param handler Callback function.
 643          * @param to Timer's timeout.
 644          */
 645         template < typename F >
 646         void add_once_timer(F& handler, const time& to)
 647         {
 648                 internal::event_once(-1, EV_TIMEOUT, &dispatcher::wrapper< F >,
 649                                 reinterpret_cast< void* >(&handler),
 650                                 const_cast< time* >(&to)); // XXX HACK libevent don't use const
 651         }
 652
 653         /**
 654          * Adds a temporary timer with a C-style callback.
 655          *
 656          * Adds a temporary timer, without the need of instantiating a new timer
 657          * object.
 658          *
 659          * @param handler Callback function.
 660          * @param arg Arbitrary pointer to pass to the handler as argument.
 661          * @param to Timer's timeout.
 662          */
 663         void add_once_timer(ccallback_type handler, void* arg, const time& to)
 664         {
 665                 internal::event_once(-1, EV_TIMEOUT, handler, arg, const_cast< time* >(&to)); // XXX HACK libevent don't use const
 666         }
 667
 668         /**
 669          * Removes an event.
 670          *
 671          * The event e will be no longer monitored by this dispatcher.
 672          *
 673          * @param e Event to remove.
 674          */
 675         void del(basic_event& e) throw()
 676         {
 677                 internal::event_del(&e);
 678         }
 679
 680         /**
 681          * Main dispatcher loop.
 682          *
 683          * This function takes the control of the program, waiting for event and
 684          * calling it's callbacks when they are fired. It only returns under
 685          * this conditions:
 686          * - exit() was called.
 687          * - All events were del()eted.
 688          * - Another internal error.
 689          * - LOOP_ONCE flag was set.
 690          * - LOOP_NONBLOCK flag was set.
 691          *
 692          * @param flags If EVLOOP_ONCE is specified, then just one event is
 693          *              processed, if EVLOOP_NONBLOCK is specified, then this
 694          *              function returns whenever as an event or not.
 695          */
 696         int dispatch(int flags = 0) // TODO  throw(exception)
 697         {
 698                 return internal::event_base_loop(_event_base, flags);
 699         }
 700
 701         /**
 702          * Exit the dispatch() loop.
 703          *
 704          * @param to If a timeout is given, the loop exits after to is passed.
 705          */
 706         int exit(const time& to = time())
 707         {
 708                 return internal::event_base_loopexit(_event_base, const_cast< time* >(&to)); // XXX HACK libevent don't use const
 709         }
 710
 711         protected:
 712                 internal::event_base* _event_base;
 713                 template < typename F >
 714                 static void wrapper(int fd, short ev, void* h)
 715                 {
 716                         F& handler = *reinterpret_cast< F* >(h);
 717                         handler(fd, ev);
 718                 }
 719
 720 }; // struct dispatcher
 721
 722
 723 } // namespace event
 724
 725 #endif // _EVENTXX_HPP_
 726
 727 // vim: set filetype=cpp :