event

   1 #ifndef _EVENT_HPP_
   2 #define _EVENT_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 event
  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: 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: std::invalid_argument, 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: std::invalid_argument, 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< event::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 event::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 event::event for C-style callbacks.
 314  *
 315  * @see event::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 event::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::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 event::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 //@}
 493
 494
 495 /**
 496  * Event dispatcher.
 497  *
 498  * This class is the responsable for looping and dispatching events.
 499  */
 500 struct dispatcher
 501 {
 502
 503         /**
 504          * Creates a default dispatcher (with just 1 prioriority).
 505          *
 506          * @see dispatcher(int) if you want to create a dispatcher with more
 507          *      prioriorities.
 508          */
 509         dispatcher() throw()
 510         {
 511                 _event_base = static_cast< internal::event_base* >(internal::event_init());
 512         }
 513
 514         /**
 515          * Creates a dispatcher with npriorities prioriorities.
 516          *
 517          * @param npriorities Number of priority queues to use.
 518          */
 519         dispatcher(int npriorities) throw(std::bad_alloc)
 520         {
 521                 _event_base = static_cast< internal::event_base* >(internal::event_init());
 522                 if (!_event_base) throw std::bad_alloc();
 523                 // Can't fail because there is no way that it has active events
 524                 internal::event_base_priority_init(_event_base, npriorities);
 525         }
 526
 527 #ifdef EVENT_BASE_FREE_FIX
 528         ~dispatcher() throw() { event_base_free(_event_base); }
 529 #endif
 530
 531         /**
 532          * Adds an event to the dispatcher.
 533          *
 534          * @param e Event to add.
 535          */
 536         void add(basic_event& e) throw()
 537         {
 538                 internal::event_base_set(_event_base, &e);
 539                 internal::event_add(&e, 0);
 540         }
 541
 542         /**
 543          * Adds an event to the dispatcher with a timeout.
 544          *
 545          * The event is fired when there is activity on e or when to is elapsed,
 546          * whatever come first.
 547          *
 548          * @param e Event to add.
 549          * @param to Timeout.
 550          */
 551         void add(basic_event& e, const time& to) throw()
 552         {
 553                 internal::event_base_set(_event_base, &e);
 554                 internal::event_add(&e, const_cast< time* >(&to)); // XXX HACK libevent don't use const
 555         }
 556
 557         /**
 558          * Adds a temporary event.
 559          *
 560          * Adds a temporary event, without the need of instantiating a new event
 561          * object. Events added this way can't EV_PERSIST.
 562          *
 563          * @param fd File descriptor to monitor for events.
 564          * @param ev Type of events to monitor.
 565          * @param handler Callback function.
 566          */
 567         template < typename F >
 568         void add_once(int fd, short ev, F& handler)
 569         {
 570                 internal::event_once(fd, ev, &dispatcher::wrapper< F >,
 571                                 reinterpret_cast< void* >(&handler), 0);
 572         }
 573
 574         /**
 575          * Adds a temporary event to with a C-style callback.
 576          *
 577          * Adds a temporary event, without the need of instantiating a new event
 578          * object. Events added this way can't EV_PERSIST.
 579          *
 580          * @param fd File descriptor to monitor for events.
 581          * @param ev Type of events to monitor.
 582          * @param handler Callback function.
 583          * @param arg Arbitrary pointer to pass to the handler as argument.
 584          */
 585         void add_once(int fd, short ev, ccallback_type handler, void* arg)
 586         {
 587                 internal::event_once(fd, ev, handler, arg, 0);
 588         }
 589
 590         /**
 591          * Adds a temporary event.
 592          *
 593          * Adds a temporary event, without the need of instantiating a new event
 594          * object. Events added this way can't EV_PERSIST.
 595          *
 596          * @param fd File descriptor to monitor for events.
 597          * @param ev Type of events to monitor.
 598          * @param handler Callback function.
 599          * @param to Timeout.
 600          */
 601         template < typename F >
 602         void add_once(int fd, short ev, F& handler, const time& to)
 603         {
 604                 internal::event_once(fd, ev, &dispatcher::wrapper< F >,
 605                                 reinterpret_cast< void* >(&handler),
 606                                 const_cast< time* >(&to)); // XXX HACK libevent don't use const
 607         }
 608
 609         /**
 610          * Adds a temporary event with a C-style callback.
 611          *
 612          * Adds a temporary event, without the need of instantiating a new event
 613          * object. Events added this way can't EV_PERSIST.
 614          *
 615          * @param fd File descriptor to monitor for events.
 616          * @param ev Type of events to monitor.
 617          * @param handler Callback function.
 618          * @param arg Arbitrary pointer to pass to the handler as argument.
 619          * @param to Timeout.
 620          */
 621         void add_once(int fd, short ev, ccallback_type handler, void* arg, const time& to)
 622         {
 623                 internal::event_once(fd, ev, handler, arg, const_cast< time* >(&to)); // XXX HACK libevent don't use const
 624         }
 625
 626         /**
 627          * Adds a temporary timer.
 628          *
 629          * Adds a temporary timer, without the need of instantiating a new timer
 630          * object.
 631          *
 632          * @param handler Callback function.
 633          * @param to Timer's timeout.
 634          */
 635         template < typename F >
 636         void add_once_timer(F& handler, const time& to)
 637         {
 638                 internal::event_once(-1, EV_TIMEOUT, &dispatcher::wrapper< F >,
 639                                 reinterpret_cast< void* >(&handler),
 640                                 const_cast< time* >(&to)); // XXX HACK libevent don't use const
 641         }
 642
 643         /**
 644          * Adds a temporary timer with a C-style callback.
 645          *
 646          * Adds a temporary timer, without the need of instantiating a new timer
 647          * object.
 648          *
 649          * @param handler Callback function.
 650          * @param arg Arbitrary pointer to pass to the handler as argument.
 651          * @param to Timer's timeout.
 652          */
 653         void add_once_timer(ccallback_type handler, void* arg, const time& to)
 654         {
 655                 internal::event_once(-1, EV_TIMEOUT, handler, arg, const_cast< time* >(&to)); // XXX HACK libevent don't use const
 656         }
 657
 658         /**
 659          * Removes an event.
 660          *
 661          * The event e will be no longer monitored by this dispatcher.
 662          *
 663          * @param e Event to remove.
 664          */
 665         void del(basic_event& e) throw()
 666         {
 667                 internal::event_del(&e);
 668         }
 669
 670         /**
 671          * Main dispatcher loop.
 672          *
 673          * This function takes the control of the program, waiting for event and
 674          * calling it's callbacks when they are fired. It only returns under
 675          * this conditions:
 676          * - exit() was called.
 677          * - All events were del()eted.
 678          * - Another internal error.
 679          * - LOOP_ONCE flag was set.
 680          * - LOOP_NONBLOCK flag was set.
 681          *
 682          * @param flags If EVLOOP_ONCE is specified, then just one event is
 683          *              processed, if EVLOOP_NONBLOCK is specified, then this
 684          *              function returns whenever as an event or not.
 685          */
 686         int dispatch(int flags = 0) // TODO  throw(exception)
 687         {
 688                 return internal::event_base_loop(_event_base, flags);
 689         }
 690
 691         /**
 692          * Exit the dispatch() loop.
 693          *
 694          * @param to If a timeout is given, the loop exits after to is passed.
 695          */
 696         int exit(const time& to = time())
 697         {
 698                 return internal::event_base_loopexit(_event_base, const_cast< time* >(&to)); // XXX HACK libevent don't use const
 699         }
 700
 701         protected:
 702                 internal::event_base* _event_base;
 703                 template < typename F >
 704                 static void wrapper(int fd, short ev, void* h)
 705                 {
 706                         F& handler = *reinterpret_cast< F* >(h);
 707                         handler(fd, ev);
 708                 }
 709
 710 }; // struct dispatcher
 711
 712
 713 /// Shortcut to C-style event.
 714 typedef event::event< ccallback_type > cevent;
 715
 716 /// Shortcut to C-style timer.
 717 typedef event::timer< ccallback_type > ctimer;
 718
 719 /// Shortcut to C-style signal handler.
 720 typedef event::signal< ccallback_type > csignal;
 721
 722
 723 } // namespace event
 724
 725 #endif // _EVENT_HPP_
 726
 727 // vim: set filetype=cpp :