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