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