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