document c++ api

[software/libev.git] / README

diff --git a/README b/README
index ee8f4920940eafe09ca3069e71fdff8f9aa2beab..1585243aab80335b9f98103161ee42236804ca2d 100644 (file)
--- a/README
+++ b/README
@@ -1,92 +1,125 @@
-Homepage: http://software.schmorp.de/pkg/libev
-E-Mail: libev@schmorp.de
-

 libev is a high-performance event loop/event model with lots of features.
 libev is a high-performance event loop/event model with lots of features.

+(see benchmark at http://libev.schmorp.de/bench.html)
+
+   Homepage: http://software.schmorp.de/pkg/libev
+   E-Mail: libev@lists.schmorp.de
+
+   It is modelled (very losely) after libevent
+   (http://monkey.org/~provos/libevent/) and the Event perl module, but aims
+   to be faster and more correct, and also more featureful.
+
+ABOUT THIS DISTRIBUTION
+
+   If you downloaded a distribution of libev, you will find it looks
+   very much like libevent. In fact, the distributed libev tarballs are
+   indeed libevent tarballs patched up with the libev event core, taking
+   the evbuffer, evtag, evdns and evhttpd parts from libevent (they use
+   the libevent emulation inside libev). Configure and Makefile stuff is
+   also a more or less direct copy of libevent, and are maintained by the
+   libevent authors.
+
+   If you are looking for an easily embeddable version, I recommend using
+   the CVS repository (linked from the homepage, above), which contains
+   only the libev core parts.
+
+   Examples of programs that embed libev: the EV perl module,
+   rxvt-unicode, gvpe (GNU Virtual Private Ethernet) and deliantra
+   (http://www.deliantra.net).
+
+DIFFERENCES AND COMPARISON TO LIBEVENT
+
+   The comparisons below are relative to libevent-1.3e.
+
+   - multiple watchers can wait for the same event without deregistering others,
+     both for file descriptors as well as signals.
+     (registering two read events on fd 10 and unregistering one will not
+     break the other).
+
+   - fork() is supported and can be handled
+     (there is no way to recover from a fork with libevent).

 
 

-It is modelled (very losely) after libevent
-(http://monkey.org/~provos/libevent/) and the Event perl module, but aims
-to be faster and more correct, and also more featureful.
+   - timers are handled as a priority queue (important operations are O(1))
+     (libevent uses a much less efficient but more complex red-black tree).

 
 

-DIFFERENCES AND COMPARISON TO LIBEVENT:
+   - supports absolute (wallclock-based) timers in addition to relative ones,
+     i.e. can schedule timers to occur after n seconds, or at a specific time.

 
 

-(comparisons relative to libevent-1.3e and libev-0.00, see also the benchmark
-at http://libev.schmorp.de/bench.html).
+   - timers can be repeating (both absolute and relative ones).

 
 

-- multiple watchers can wait for the same event without deregistering others,
-  both for file descriptors as well as signals.
-  (registering two read events on fd 10 and unregistering one will not
-  break the other).
+   - absolute timers can have customised rescheduling hooks (suitable for cron-like
+     applications).

 
 

-- fork() is supported and can be handled
-  (there is no way to recover from a fork when libevent is active).
+   - detects time jumps and adjusts timers
+     (works for both forward and backward time jumps and also for absolute timers).

 
 

-- timers are handled as a priority queue (important operations are O(1))
-  (libevent uses a much less efficient but more complex red-black tree).
+   - race-free signal processing
+     (libevent may delay processing signals till after the next event).

 
 

-- supports absolute (wallclock-based) timers in addition to relative ones,
-  i.e. can schedule timers to occur after n seconds, or at a specific time.
+   - more efficient epoll backend
+     (stopping and starting an io watcher between two loop iterations will not
+     result in spurious epoll_ctl calls).

 
 

-- timers can be repeating (both absolute and relative ones).
+   - usually less calls to gettimeofday and clock_gettime
+     (libevent calls it on every timer event change, libev twice per iteration).

 
 

-- detects time jumps and adjusts timers
-  (works for both forward and backward time jumps and also for absolute timers).
+   - watchers use less memory
+     (libevent watcher on amd64: 152 bytes, libev native: <= 56 bytes, libevent emulation: 144 bytes).

 
 

-- race-free signal processing
-  (libevent may delay processing signals till after the next event).
+   - library uses less memory
+     (libevent allocates large data structures wether used or not, libev
+     scales all its data structures dynamically).

 
 

-- less calls to epoll_ctl
-  (stopping and starting an io watcher between two loop iterations will now
-  result in spuriois epoll_ctl calls).
+   - no hardcoded arbitrary limits
+     (libevent contains an off-by-one bug and sometimes hardcodes limits).

 
 

-- usually less calls to gettimeofday and clock_gettime
-  (libevent calls it on every timer event change, libev twice per iteration).
+   - libev separates timer, signal and io watchers from each other
+     (libevent combines them, but with libev you can combine them yourself
+     by reusing the same callback and still save memory).

 
 

-- watchers use less memory
-  (libevent on amd64: 152 bytes, libev: <= 56 bytes).
+   - simpler design, backends are potentially much simpler
+     (in libevent, backends have to deal with watchers, thus the problems with
+     wildly different semantics between diferent backends)
+     (epoll backend in libevent: 366 lines no caching, libev: 90 lines full caching).

 
 

-- library uses less memory
-  (libevent allocates large data structures wether used or not, libev
-  scales all its data structures dynamically).
+   - libev handles EBADF gracefully by removing the offending fds.

 
 

-- no hardcoded arbitrary limits
-  (libevent contains an off-by-one bug and sometimes hardcodes a limit of
-  32000 fds).
+   - libev communicates errors to the callback, libevent to the
+     event adder or not at all.

 
 

-- libev separates timer, signal and io watchers from each other
-  (libevent combines them, but with libev you can combine them yourself
-  by reusing the same callback and still save memory).
+   - doesn't rely on nonportable BSD header files.

 
 

-- simpler design, backends are potentially much simpler
-  (in libevent, backends have to deal with watchers, thus the problems)
-  (epoll backend in libevent: 366 lines, libev: 90 lines, and more features).
+   - an event.h compatibility header exists, and can be used to run a wide
+     range of libevent programs unchanged (such as evdns.c).

 
 

-- libev handles EBADF gracefully by removing the offending fds.
+   - win32 compatibility for the core parts.
+     (the backend is fd-based as documented and on other platforms,
+     not handle-based like libevent, and can be used for both winscoket environments
+     and unix-like ones).

 
 

-- doesn't rely on nonportable BSD header files.
+   - libev can be embedded easily with or without autoconf support into
+     other programs, with no changes to the source code necessary.

 
 

-- a event.h compatibility header exists, and can be used to run a wide
-  range of libevent programs unchanged (such as evdns.c).
+   - the event core library (ev and event layer) compiles and works both as
+     C and C++.

 
 

-- win32 compatibility for the core parts.
+   - a simple C++ wrapper that supports methods as callbacks exists.

 
 

-- the event core library (ev and event layer) compiles and works both as
-  C and C++.
+   - a full featured and widely used perl module is available.

 
 

-whats missing?
+   whats missing?

 
 

-- no event-like priority support at the moment (the ev priorities
-  are not yet finished and work differently, but you can use idle watchers
-  to get a similar effect).
+   - no event-like priority support at the moment (the ev priorities work
+     differently, but you can use idle watchers to get a similar effect).

 
 AUTHOR
 
 
 AUTHOR
 

-libev was written and designed by Marc Lehmann and Emanuele Giaquinta.
+   libev was written and designed by Marc Lehmann and Emanuele Giaquinta.

 
 

-The following people sent in patches or made other noteworthy
-contributions (if I forgot to include you, please shout at me, it was an
-accident):
+   The following people sent in patches or made other noteworthy
+   contributions to the design (if I forgot to include you, please shout
+   at me, it was an accident):

 
 

-W.C.A. Wijngaards
-Christopher Layne
-Chris Brody
+   W.C.A. Wijngaards
+   Christopher Layne
+   Chris Brody