README.embed

   1 EMBEDDING THE LIBEV CODE INTO YOUR OWN PROGRAMS
   2
   3     Instead of building the libev library you cna 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     To include only the libev core (all the ev_* functions):
  12
  13         #define EV_STANDALONE   1
  14         #include "ev.c"
  15
  16     This will automatically include ev.h, too, and should be done in a
  17     single C source file only to provide the function implementations. To
  18     use it, do the same for ev.h in all users:
  19
  20         #define EV_STANDALONE   1
  21         #include "ev.h"
  22
  23     You need the following files in your source tree, or in a directory
  24     in your include path (e.g. in libev/ when using -Ilibev):
  25
  26         ev.h
  27         ev.c
  28         ev_vars.h
  29         ev_wrap.h
  30         ev_select.c     only when select backend is enabled (which is by default)
  31         ev_poll.c       only when poll backend is enabled (disabled by default)
  32         ev_epoll.c      only when the epoll backend is enabled (disabled by default)
  33         ev_kqueue.c     only when the kqueue backend is enabled (disabled by default)
  34
  35     "ev.c" includes the backend files directly when enabled.
  36
  37     To include the libevent compatibility API, also include:
  38
  39         #include "event.c"
  40
  41     in the file including "ev.c", and:
  42
  43         #include "event.h"
  44
  45     in the files that want to use the libevent API. This also includes "ev.h".
  46
  47     You need the following additional files for this:
  48
  49         event.h
  50         event.c
  51
  52 PREPROCESSOR SYMBOLS
  53
  54     Libev can be configured via a variety of preprocessor symbols you have to define
  55     before including any of its files. The default is not to build for mulciplicity
  56     and only include the select backend.
  57
  58     EV_STANDALONE
  59
  60         Must always be "1", which keeps libev from including config.h or
  61         other files, and it also defines dummy implementations for some
  62         libevent functions (such as logging, which is not supported). It
  63         will also not define any of the structs usually found in "event.h"
  64         that are not directly supported by libev code alone.
  65
  66     EV_USE_MONOTONIC
  67
  68         If undefined or defined to be "1", libev will try to detect the
  69         availability of the monotonic clock option at both compiletime and
  70         runtime. Otherwise no use of the monotonic clock option will be
  71         attempted.
  72
  73     EV_USE_REALTIME
  74
  75         If defined to be "1", libev will try to detect the availability
  76         of the realtime clock option at compiletime (and assume its
  77         availability at runtime if successful). Otherwise no use of the
  78         realtime clock option will be attempted. This effectively replaces
  79         gettimeofday by clock_get (CLOCK_REALTIME, ...) and will not normally
  80         affect correctness.
  81
  82     EV_USE_SELECT
  83
  84        If undefined or defined to be "1", libev will compile in support
  85        for the select(2) backend. No attempt at autodetection will be
  86        done: if no other method takes over, select will be it. Otherwise
  87        the select backend will not be compiled in.
  88
  89     EV_USE_POLL
  90
  91        If defined to be "1", libev will compile in support for the poll(2)
  92        backend. No attempt at autodetection will be done. poll usually
  93        performs worse than select, so its not enabled by default (it is
  94        also slightly less portable).
  95
  96     EV_USE_EPOLL
  97
  98        If defined to be "1", libev will compile in support for the Linux
  99        epoll backend. Its availability will be detected at runtime,
 100        otherwise another method will be used as fallback. This is the
 101        preferred backend for GNU/Linux systems.
 102
 103     EV_USE_KQUEUE
 104
 105        If defined to be "1", libev will compile in support for the BSD
 106        style kqueue backend. Its availability will be detected at runtime,
 107        otherwise another method will be used as fallback. This is the
 108        preferred backend for BSD and BSd-like systems. Darwin brokenness
 109        will be detected at runtime and routed around by disabling this
 110        backend.
 111
 112     EV_COMMON
 113
 114        By default, all watchers have a "void *data" member. By redefining
 115        this macro to a something else you can include more and other types
 116        of members. You have to define it each time you include one of the
 117        files, though, and it must be identical each time.
 118
 119        For example, the perl EV module uses this:
 120
 121            #define EV_COMMON                       \
 122              SV *self; /* contains this struct */  \
 123              SV *cb_sv, *fh;
 124
 125     EV_PROTOTYPES
 126
 127        If defined to be "0", then "ev.h" will not define any function
 128        prototypes, but still define all the structs and other
 129        symbols. This is occasionally useful.
 130
 131     EV_MULTIPLICITY
 132
 133        If undefined or defined to "1", then all event-loop-specific
 134        functions will have the "struct ev_loop *" as first argument, and
 135        you can create additional independent event loops. Otherwise there
 136        will be no support for multiple event loops and there is no first
 137        event loop pointer argument. Instead, all functions act on the
 138        single default loop.
 139
 140 EXAMPLES
 141
 142     For a real-world example of a program the includes libev
 143     verbatim, you can have a look at the EV perl module
 144     (http://software.schmorp.de/pkg/EV.html).  It has the libev files in
 145     the liev/ subdirectory and includes them in the EV/EVAPI.h (public
 146     interface) and EV.xs (implementation) files. Only EV.xs file will be
 147     compiled.
 148