README.embed

   1 EMBEDDING THE LIBEV CODE INTO YOUR OWN PROGRAMS
   2
   3     Instead of building the libev library you can also include the code
   4     as-is into your programs. To update, you only have to copy a few files
   5     into your source tree.
   6
   7     This is how it works:
   8
   9 FILESETS
  10
  11     CORE EVENT LOOP
  12
  13     To include only the libev core (all the ev_* functions):
  14
  15         #define EV_STANDALONE   1
  16         #include "ev.c"
  17
  18     This will automatically include ev.h, too, and should be done in a
  19     single C source file only to provide the function implementations. To
  20     use it, do the same for ev.h in all files wishing to use this API
  21     (best done by writing a wrapper around ev.h that you can include
  22     instead and where you can put other configuration options):
  23
  24         #define EV_STANDALONE   1
  25         #include "ev.h"
  26
  27     Both header files and implementation files can be compiled with a C++
  28     compiler (at least, thats a stated goal, and breakage will be treated
  29     as a bug).
  30
  31     You need the following files in your source tree, or in a directory
  32     in your include path (e.g. in libev/ when using -Ilibev):
  33
  34         ev.h
  35         ev.c
  36         ev_vars.h
  37         ev_wrap.h
  38
  39         ev_win32.c      required on win32 platforms only
  40
  41         ev_select.c     only when select backend is enabled (which is is by default)
  42         ev_poll.c       only when poll backend is enabled (disabled by default)
  43         ev_epoll.c      only when the epoll backend is enabled (disabled by default)
  44         ev_kqueue.c     only when the kqueue backend is enabled (disabled by default)
  45         ev_port.c       only when the solaris port backend is enabled (disabled by default)
  46
  47     "ev.c" includes the backend files directly when enabled.
  48
  49     LIBEVENT COMPATIBILITY API
  50
  51     To include the libevent compatibility API, also include:
  52
  53         #include "event.c"
  54
  55     in the file including "ev.c", and:
  56
  57         #include "event.h"
  58
  59     in the files that want to use the libevent API. This also includes "ev.h".
  60
  61     You need the following additional files for this:
  62
  63         event.h
  64         event.c
  65
  66 AUTOCONF SUPPORT
  67
  68     Instead of using EV_STANDALONE=1 and providing your config in whatever
  69     way you want, you can also m4_include([libev.m4]) in your configure.ac
  70     and leave EV_STANDALONE off. ev.c will then include "config.h" and
  71     configure itself accordingly.
  72
  73 PREPROCESSOR SYMBOLS
  74
  75     Libev can be configured via a variety of preprocessor symbols you have to define
  76     before including any of its files. The default is not to build for multiplicity
  77     and only include the select backend.
  78
  79     EV_STANDALONE
  80
  81         Must always be "1", which keeps libev from including config.h or
  82         other files, and it also defines dummy implementations for some
  83         libevent functions (such as logging, which is not supported). It
  84         will also not define any of the structs usually found in "event.h"
  85         that are not directly supported by libev code alone.
  86
  87     EV_USE_MONOTONIC
  88
  89         If defined to be "1", libev will try to detect the availability
  90         of the monotonic clock option at both compiletime and
  91         runtime. Otherwise no use of the monotonic clock option will be
  92         attempted. If you enable this, you usually have to link against
  93         librt or something similar. Enabling it when the functionality
  94         isn't available is safe, though.
  95
  96     EV_USE_REALTIME
  97
  98         If defined to be "1", libev will try to detect the availability
  99         of the realtime clock option at compiletime (and assume its
 100         availability at runtime if successful). Otherwise no use of the
 101         realtime clock option will be attempted. This effectively replaces
 102         gettimeofday by clock_get (CLOCK_REALTIME, ...) and will not normally
 103         affect correctness.
 104
 105     EV_USE_SELECT
 106
 107        If undefined or defined to be "1", libev will compile in support
 108        for the select(2) backend. No attempt at autodetection will be
 109        done: if no other method takes over, select will be it. Otherwise
 110        the select backend will not be compiled in.
 111
 112     EV_SELECT_USE_FD_SET
 113
 114        If defined to 1, then the select backend will use the system fd_set
 115        structure. This is useful if libev doesn't compile due to a missing
 116        NFDBITS or fd_mask definition or it misguesses the bitset layout on
 117        exotic systems. This usually limits the range of file descriptors
 118        to some low limit such as 1024 or might have other limitations
 119        (winsocket only allows 64 sockets). The FD_SETSIZE macro, set
 120        before compilation, might influence the size of the fd_set used.
 121
 122     EV_SELECT_IS_WINSOCKET
 123
 124        When defined to 1, the select backend will assume that
 125        select/socket/connect etc. don't understand file descriptors but
 126        wants osf handles on win32 (this is the case when the select to
 127        be used is the winsock select). This means that it will call
 128        _get_osfhandle on the fd to convert it to an OS handle. Otherwise,
 129        it is assumed that all these functions actually work on fds, even
 130        on win32. Should not be defined on non-win32 platforms.
 131
 132     EV_USE_POLL
 133
 134        If defined to be "1", libev will compile in support for the poll(2)
 135        backend. Otherwise it will be enabled on non-win32 platforms. It
 136        takes precedence over select.
 137
 138     EV_USE_EPOLL
 139
 140        If defined to be "1", libev will compile in support for the Linux
 141        epoll backend. Its availability will be detected at runtime,
 142        otherwise another method will be used as fallback. This is the
 143        preferred backend for GNU/Linux systems.
 144
 145     EV_USE_KQUEUE
 146
 147        If defined to be "1", libev will compile in support for the BSD
 148        style kqueue backend. Its availability will be detected at runtime,
 149        otherwise another method will be used as fallback. This is the
 150        preferred backend for BSD and BSD-like systems. Darwin brokenness
 151        will be detected at runtime and routed around by disabling this
 152        backend.
 153
 154     EV_USE_PORT
 155
 156        If defined to be "1", libev will compile in support for the Solaris
 157        10 port style backend. Its availability will be detected at runtime,
 158        otherwise another method will be used as fallback. This is the
 159        preferred backend for Solaris 10 systems.
 160
 161     EV_USE_DEVPOLL
 162
 163        reserved for future expansion, works like the USE symbols above.
 164
 165     EV_H
 166
 167         The name of the ev.h header file used to include it. The default
 168         if undefined is <ev.h> in event.h and "ev.h" in ev.c. This can
 169         be used to virtually rename the ev.h header file in case of
 170         conflicts.
 171
 172     EV_EVENT_H
 173
 174         Similarly to EV_H, this macro cna be used to override event.c's idea
 175         of how the event.h header can be found.
 176
 177     EV_PROTOTYPES
 178
 179        If defined to be "0", then "ev.h" will not define any function
 180        prototypes, but still define all the structs and other
 181        symbols. This is occasionally useful.
 182
 183     EV_MULTIPLICITY
 184
 185        If undefined or defined to "1", then all event-loop-specific
 186        functions will have the "struct ev_loop *" as first argument, and
 187        you can create additional independent event loops. Otherwise there
 188        will be no support for multiple event loops and there is no first
 189        event loop pointer argument. Instead, all functions act on the
 190        single default loop.
 191
 192     EV_PERIODICS
 193
 194        If undefined or defined to be "1", then periodic timers are
 195        supported, otherwise not. This saves a few kb of code.
 196
 197     EV_COMMON
 198
 199        By default, all watchers have a "void *data" member. By redefining
 200        this macro to a something else you can include more and other types
 201        of members. You have to define it each time you include one of the
 202        files, though, and it must be identical each time.
 203
 204        For example, the perl EV module uses this:
 205
 206            #define EV_COMMON                       \
 207              SV *self; /* contains this struct */  \
 208              SV *cb_sv, *fh /* note no trailing ";" */
 209
 210     EV_CB_DECLARE(type)
 211     EV_CB_INVOKE(watcher,revents)
 212     ev_set_cb(ev,cb)
 213
 214        Can be used to change the callback member declaration in each
 215        watcher, and the way callbacks are invoked and set. Must expand
 216        to a struct member definition and a statement, respectively. See
 217        the ev.v header file for their default definitions. One possible
 218        use for overriding these is to avoid the ev_loop pointer as first
 219        argument in all cases, or to use method calls instead of plain
 220        function calls in C++.
 221
 222 EXAMPLES
 223
 224     For a real-world example of a program the includes libev
 225     verbatim, you can have a look at the EV perl module
 226     (http://software.schmorp.de/pkg/EV.html).  It has the libev files in
 227     the libev/ subdirectory and includes them in the EV/EVAPI.h (public
 228     interface) and EV.xs (implementation) files. Only the EV.xs file will
 229     be compiled.
 230