| 1 | EMBEDDING THE LIBEV CODE INTO YOUR OWN PROGRAMS |
1 | This file is now included in the main libev documentation, see |
| 2 | |
2 | |
| 3 | Instead of building the libev library you can also include the code |
3 | http://cvs.schmorp.de/libev/ev.html |
| 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_CONFIG_H |
|
|
| 173 | |
|
|
| 174 | If EV_STANDALONE isn't 1, this variable can be used to override |
|
|
| 175 | ev.c's idea of where to find the "config.h" file. |
|
|
| 176 | |
|
|
| 177 | EV_EVENT_H |
|
|
| 178 | |
|
|
| 179 | Similarly to EV_H, this macro can be used to override event.c's idea |
|
|
| 180 | of how the event.h header can be found. |
|
|
| 181 | |
|
|
| 182 | EV_PROTOTYPES |
|
|
| 183 | |
|
|
| 184 | If defined to be "0", then "ev.h" will not define any function |
|
|
| 185 | prototypes, but still define all the structs and other |
|
|
| 186 | symbols. This is occasionally useful. |
|
|
| 187 | |
|
|
| 188 | EV_MULTIPLICITY |
|
|
| 189 | |
|
|
| 190 | If undefined or defined to "1", then all event-loop-specific |
|
|
| 191 | functions will have the "struct ev_loop *" as first argument, and |
|
|
| 192 | you can create additional independent event loops. Otherwise there |
|
|
| 193 | will be no support for multiple event loops and there is no first |
|
|
| 194 | event loop pointer argument. Instead, all functions act on the |
|
|
| 195 | single default loop. |
|
|
| 196 | |
|
|
| 197 | EV_PERIODICS |
|
|
| 198 | |
|
|
| 199 | If undefined or defined to be "1", then periodic timers are |
|
|
| 200 | supported, otherwise not. This saves a few kb of code. |
|
|
| 201 | |
|
|
| 202 | EV_COMMON |
|
|
| 203 | |
|
|
| 204 | By default, all watchers have a "void *data" member. By redefining |
|
|
| 205 | this macro to a something else you can include more and other types |
|
|
| 206 | of members. You have to define it each time you include one of the |
|
|
| 207 | files, though, and it must be identical each time. |
|
|
| 208 | |
|
|
| 209 | For example, the perl EV module uses this: |
|
|
| 210 | |
|
|
| 211 | #define EV_COMMON \ |
|
|
| 212 | SV *self; /* contains this struct */ \ |
|
|
| 213 | SV *cb_sv, *fh /* note no trailing ";" */ |
|
|
| 214 | |
|
|
| 215 | EV_CB_DECLARE(type) |
|
|
| 216 | EV_CB_INVOKE(watcher,revents) |
|
|
| 217 | ev_set_cb(ev,cb) |
|
|
| 218 | |
|
|
| 219 | Can be used to change the callback member declaration in each |
|
|
| 220 | watcher, and the way callbacks are invoked and set. Must expand |
|
|
| 221 | to a struct member definition and a statement, respectively. See |
|
|
| 222 | the ev.v header file for their default definitions. One possible |
|
|
| 223 | use for overriding these is to avoid the ev_loop pointer as first |
|
|
| 224 | argument in all cases, or to use method calls instead of plain |
|
|
| 225 | function calls in C++. |
|
|
| 226 | |
|
|
| 227 | EXAMPLES |
|
|
| 228 | |
|
|
| 229 | For a real-world example of a program the includes libev |
|
|
| 230 | verbatim, you can have a look at the EV perl module |
|
|
| 231 | (http://software.schmorp.de/pkg/EV.html). It has the libev files in |
|
|
| 232 | the libev/ subdirectory and includes them in the EV/EVAPI.h (public |
|
|
| 233 | interface) and EV.xs (implementation) files. Only the EV.xs file will |
|
|
| 234 | be compiled. |
|
|
| 235 | |
|
|
