README

   1 // NOTE: This file is in doxygen[1] format. Maybe you should try to run
   2 //       doxygen to get a better looking documentation ;)
   3 //
   4 // [1] http://www.stack.nl/~dimitri/doxygen/
   5
   6 /** @mainpage
   7
   8 @section Introduction
   9
  10 @libevent is a popular API that provides a mechanism to execute a callback
  11 function when a specific event occurs on a file descriptor or after a
  12 timeout has been reached. Furthermore, @libevent also support callbacks due
  13 to signals or regular timeouts.
  14
  15 @eventxx is a simple, direct, one-header inline C++ wrapper for @libevent.
  16 Yes, it's just one header file, so if you want to use it you can just copy
  17 the file to your project and you are set (well, you'll need to link to
  18 @libevent too ;).
  19
  20 It's designed to be as close to use to @libevent (without compromising
  21 modern C++ programming techniques) and efficient (since all implementation
  22 is trivial and inline, theoretically, it imposes no overhead at all) as
  23 possible.
  24
  25 Please, visit the @eventxx website for the latest version of this
  26 documentation.
  27
  28 @section Download
  29
  30 You can always get the <a href="@home/releases/eventxx.tar.gz">current
  31 release</a> from the <a href="@home/releases/">release directory</a> or
  32 grab the <a href="@gitweb?a=snapshot">most up to date sources</a> from
  33 the <a href="https://git-scm.com/">git</a> repository.
  34
  35 You can also take a look the the <a href="@gitweb">eventxx gitweb</a>
  36 interface to see the latest changes online or subscribe to its
  37 <a href="@gitweb?a=atom">Atom feed</a> to follow the development.
  38
  39
  40 @section Usage
  41
  42 You probably should read @libevent documentation to get started or at least
  43 just for reference, although @eventxx is pretty simple so you can jump right
  44 into the \ref Example section (or the example list) and write a working
  45 program without much trouble.
  46
  47 This wrapper was designed to be used just like @libevent, but with C++ style
  48 syntax sugar (or poison, depends on your point of view ;) and goodies. The
  49 main difference to libevent is you always have to instance a
  50 eventxx::dispatcher to get an event loop. There is no implicit global event
  51 loop. This adds just an extra line of code for single threaded applications
  52 and makes things much more simpler, so I hope nobody complains about it ;).
  53 See eventxx::dispatcher documentation for more details.
  54
  55 You can use use the same plain functions callbacks @libevent use or the other
  56 kind of function objects (see @ref events section for details on event
  57 types).
  58
  59 @eventxx uses @ref exceptions to report errors. All functions have exception
  60 specifications, so it's easy to find out what to expect. See @ref exceptions
  61 section for more detail.
  62
  63 A @c timespec abstraction is provided as eventxx::time for convenient
  64 argument passing. Even more, it's a @c timespec itself, with some convenient
  65 methods for accessing the attributes with pritier names. And even more,
  66 @eventxx is such a direct mapping that all eventxx::event's are @libevent
  67 event structs too, so theoretically you can pass a eventxx::event to
  68 @libevent C functions without much trouble. eventxx::dispatcher is the only
  69 class that is not derived from @libevent struct (@c event_base) because this
  70 struct it's not defined on the libevent header (just declared).
  71
  72 Maybe you shouldn't know this implementation details to keep the abstraction,
  73 but this is a basic design goal of this wrapper so there is not much chance
  74 that this changes in the future (but use this knowledge with care, you have
  75 been  warned ;).
  76
  77
  78 @section Example
  79
  80 @code
  81 #include <eventxx>
  82 #include <iostream>
  83 #include <csignal>
  84
  85 struct handler
  86 {
  87         eventxx::dispatcher& d;
  88         int i;
  89         handler(eventxx::dispatcher& d): d(d), i(0) {}
  90         void operator() (int signum, eventxx::type event)
  91         {
  92                 std::cout << ++i << " interrupts, ";
  93                 if (i < 5) std::cout << "keep going...\n";
  94                 else
  95                 {
  96                         std::cout << "done!\n";
  97                         d.exit();
  98                 }
  99         }
 100 };
 101
 102 void timer_handler(int, short, void*)
 103 {
 104         std::cout << "Press Ctrl-C 5 times to quit.\n";
 105 }
 106
 107 int main()
 108 {
 109         eventxx::dispatcher d;
 110         handler h(d);
 111         eventxx::ctimer t(timer_handler);
 112         eventxx::signal< handler > e(SIGINT, h);
 113         d.add(t, eventxx::time(1)); // 1 second
 114         d.add(e);
 115         d.dispatch();
 116         return 0;
 117 }
 118 @endcode
 119
 120 You can see more examples on the test directory of the distribution or on the
 121 examples related page.
 122
 123
 124 @section Status
 125
 126 I think the library is stable now. The library has no support for buffered
 127 events yet, but patches are welcome. It doesn't support the HTTP stuff, and
 128 probably never will because that has nothing to do with event handling.
 129
 130 @libevent had a memory leak before version 1.3b (before 1.2 it didn't even
 131 had a way free that memory, from version 1.2 to 1.3a, if you tried to free
 132 the memory the program @c abort() because a failed assertion). Because of
 133 that, there is a way to disable the @link eventxx::dispatcher::~dispatcher()
 134 dispatcher destructor @endlink (which calls the inexistent/broken
 135 @c event_base_free() function in the broken versions). So if you use a
 136 @libevent version previous to 1.3b, you have to compile your programs
 137 defining the @c EVENTXX_NO_EVENT_BASE_FREE macro.
 138
 139 If something is broken it would be really easy to fix because @eventxx is
 140 just a simple wrapper around @libevent. So, please try it out, and if you
 141 have any problems, <a href="mailto:llucax+eventxx@gmail.com">drop me an
 142 e-mail</a> and and I'll fix it ASAP (or provide a patch and you will be my
 143 best friend ;).
 144
 145 If you use this library, please drop me an e-mail with your thoughts, or
 146 simply saying "I use it", so I can keep track of how many people really use
 147 it.
 148
 149 @author Leandro Lucarella <llucax+eventxx@gmail.com>
 150
 151 @version 1.0.1
 152
 153 @par License
 154 This program is under the <a href="http://auriga.wearlab.de/~alb/bola/">BOLA
 155 License</a> (see the license website or the
 156 <a href="@gitweb?a=blob_plain;f=LICENSE">LICENSE</a>
 157 file itself for more details, it's very short and it basically says it's
 158 Public Domain).
 159
 160 */
 161
 162 /** @example c-way.cpp
 163 This is a simple example illustrating the usage with C-like callback
 164 functions.
 165 */
 166
 167 /** @example functor-way.cpp
 168 This is a simple example illustrating the usage with function object
 169 callbacks.
 170 */
 171
 172 /** @example wrapped-functor-way.cpp
 173 This is a simple example illustrating the usage with an arbitrary member
 174 function as an event handler callbacks.
 175 */
 176
 177 /** @example mixed-way.cpp
 178 This is a simple example illustrating the usage with a mix of C-like callbacks
 179 and function object callbacks.
 180 */
 181
 182 /** @example bench.cpp
 183 This is a benchmark example, extracted from libevent and ported to eventxx.
 184 */
 185
 186 /** @example prio-test.cpp
 187 This is a priority usage example.
 188 */
 189
 190 /** @example test-time.cpp
 191 This is a timer usage example ported from libevent.
 192 */
 193
 194 /** @example test-eof.cpp
 195 This is some kind of test of EOF ported from libevent.
 196 */
 197
 198 /** @example test-weof.cpp
 199 Another test of EOF ported from libevent.
 200 */
 201
 202 /** @example trivial.cpp
 203 This is the most trivial example.
 204 */
 205