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 select
 125        doesn't understand file descriptors but wants osf handles on
 126        win32 (this is the case when the select to be used is the winsock
 127        select). This means that it will call _get_osfhandle on the fd to
 128        convert it to an OS handle. Should not be defined on non-win32
 129        platforms.
 130
 131     EV_USE_POLL
 132
 133        If defined to be "1", libev will compile in support for the poll(2)
 134        backend. Otherwise it will be enabled on non-win32 platforms. It
 135        takes precedence over select.
 136
 137     EV_USE_EPOLL
 138
 139        If defined to be "1", libev will compile in support for the Linux
 140        epoll backend. Its availability will be detected at runtime,
 141        otherwise another method will be used as fallback. This is the
 142        preferred backend for GNU/Linux systems.
 143
 144     EV_USE_KQUEUE
 145
 146        If defined to be "1", libev will compile in support for the BSD
 147        style kqueue backend. Its availability will be detected at runtime,
 148        otherwise another method will be used as fallback. This is the
 149        preferred backend for BSD and BSD-like systems. Darwin brokenness
 150        will be detected at runtime and routed around by disabling this
 151        backend.
 152
 153     EV_USE_PORT
 154
 155        If defined to be "1", libev will compile in support for the Solaris
 156        10 port style backend. Its availability will be detected at runtime,
 157        otherwise another method will be used as fallback. This is the
 158        preferred backend for Solaris 10 systems.
 159
 160     EV_USE_DEVPOLL
 161
 162        reserved for future expansion, works like the USE symbols above.
 163
 164     EV_H
 165
 166         The name of the ev.h header file used to include it. The default
 167         if undefined is <ev.h> in event.h and "ev.h" in ev.c. This can
 168         be used to virtually rename the ev.h header file in case of
 169         conflicts.
 170
 171     EV_EVENT_H
 172
 173         Similarly to EV_H, this macro cna be used to override event.c's idea
 174         of how the event.h header can be found.
 175
 176     EV_PROTOTYPES
 177
 178        If defined to be "0", then "ev.h" will not define any function
 179        prototypes, but still define all the structs and other
 180        symbols. This is occasionally useful.
 181
 182     EV_MULTIPLICITY
 183
 184        If undefined or defined to "1", then all event-loop-specific
 185        functions will have the "struct ev_loop *" as first argument, and
 186        you can create additional independent event loops. Otherwise there
 187        will be no support for multiple event loops and there is no first
 188        event loop pointer argument. Instead, all functions act on the
 189        single default loop.
 190
 191     EV_PERIODICS
 192
 193        If undefined or defined to be "1", then periodic timers are
 194        supported, otherwise not. This saves a few kb of code.
 195
 196     EV_COMMON
 197
 198        By default, all watchers have a "void *data" member. By redefining
 199        this macro to a something else you can include more and other types
 200        of members. You have to define it each time you include one of the
 201        files, though, and it must be identical each time.
 202
 203        For example, the perl EV module uses this:
 204
 205            #define EV_COMMON                       \
 206              SV *self; /* contains this struct */  \
 207              SV *cb_sv, *fh /* note no trailing ";" */
 208
 209     EV_CB_DECLARE(type)
 210     EV_CB_INVOKE(watcher,revents)
 211     ev_set_cb(ev,cb)
 212
 213        Can be used to change the callback member declaration in each
 214        watcher, and the way callbacks are invoked and set. Must expand
 215        to a struct member definition and a statement, respectively. See
 216        the ev.v header file for their default definitions. One possible
 217        use for overriding these is to avoid the ev_loop pointer as first
 218        argument in all cases, or to use method calls instead of plain
 219        function calls in C++.
 220
 221 EXAMPLES
 222
 223     For a real-world example of a program the includes libev
 224     verbatim, you can have a look at the EV perl module
 225     (http://software.schmorp.de/pkg/EV.html).  It has the libev files in
 226     the libev/ subdirectory and includes them in the EV/EVAPI.h (public
 227     interface) and EV.xs (implementation) files. Only the EV.xs file will
 228     be compiled.
 229