ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libev/README.embed
Revision: 1.20
Committed: Sun Nov 11 01:07:35 2007 UTC (16 years, 6 months ago) by root
Branch: MAIN
Changes since 1.19: +18 -13 lines
Log Message:
fix bug

File Contents

# User Rev Content
1 root 1.1 EMBEDDING THE LIBEV CODE INTO YOUR OWN PROGRAMS
2    
3 root 1.8 Instead of building the libev library you can also include the code
4 root 1.1 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 root 1.5 CORE EVENT LOOP
12    
13 root 1.1 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 root 1.9 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 root 1.1
24     #define EV_STANDALONE 1
25     #include "ev.h"
26    
27 root 1.11 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 root 1.1 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 root 1.4 ev_win32.c
39    
40 root 1.10 ev_select.c only when select backend is enabled (which is is by default)
41 root 1.3 ev_poll.c only when poll backend is enabled (disabled by default)
42     ev_epoll.c only when the epoll backend is enabled (disabled by default)
43     ev_kqueue.c only when the kqueue backend is enabled (disabled by default)
44    
45     "ev.c" includes the backend files directly when enabled.
46 root 1.1
47 root 1.5 LIBEVENT COMPATIBILITY API
48    
49 root 1.1 To include the libevent compatibility API, also include:
50    
51     #include "event.c"
52    
53     in the file including "ev.c", and:
54    
55     #include "event.h"
56    
57     in the files that want to use the libevent API. This also includes "ev.h".
58    
59     You need the following additional files for this:
60    
61     event.h
62     event.c
63    
64 root 1.18 AUTOCONF SUPPORT
65    
66     Instead of using EV_STANDALONE=1 and providing your config in whatever
67 root 1.19 way you want, you can also m4_include([libev.m4]) in your configure.ac
68 root 1.18 and leave EV_STANDALONE off. ev.c will then include "config.h" and
69     configure itself accordingly.
70    
71 root 1.1 PREPROCESSOR SYMBOLS
72    
73     Libev can be configured via a variety of preprocessor symbols you have to define
74 root 1.18 before including any of its files. The default is not to build for multiplicity
75 root 1.1 and only include the select backend.
76    
77     EV_STANDALONE
78    
79     Must always be "1", which keeps libev from including config.h or
80     other files, and it also defines dummy implementations for some
81     libevent functions (such as logging, which is not supported). It
82     will also not define any of the structs usually found in "event.h"
83     that are not directly supported by libev code alone.
84    
85     EV_USE_MONOTONIC
86    
87     If undefined or defined to be "1", libev will try to detect the
88     availability of the monotonic clock option at both compiletime and
89     runtime. Otherwise no use of the monotonic clock option will be
90     attempted.
91    
92     EV_USE_REALTIME
93    
94     If defined to be "1", libev will try to detect the availability
95     of the realtime clock option at compiletime (and assume its
96     availability at runtime if successful). Otherwise no use of the
97     realtime clock option will be attempted. This effectively replaces
98     gettimeofday by clock_get (CLOCK_REALTIME, ...) and will not normally
99     affect correctness.
100    
101     EV_USE_SELECT
102    
103     If undefined or defined to be "1", libev will compile in support
104     for the select(2) backend. No attempt at autodetection will be
105     done: if no other method takes over, select will be it. Otherwise
106     the select backend will not be compiled in.
107    
108 root 1.7 EV_SELECT_USE_WIN32_HANDLES
109    
110     When defined to 1, the select backend will assume that select
111     doesn't understand file descriptors but wants osf handles on
112     win32 (this is the case when the select to be used is the winsock
113     select). This means that it will call _get_osfhandle on the fd to
114     convert it to an OS handle. Should not be defined on non-win32
115     platforms.
116    
117 root 1.1 EV_USE_POLL
118    
119     If defined to be "1", libev will compile in support for the poll(2)
120     backend. No attempt at autodetection will be done. poll usually
121     performs worse than select, so its not enabled by default (it is
122     also slightly less portable).
123    
124     EV_USE_EPOLL
125    
126     If defined to be "1", libev will compile in support for the Linux
127     epoll backend. Its availability will be detected at runtime,
128     otherwise another method will be used as fallback. This is the
129     preferred backend for GNU/Linux systems.
130    
131     EV_USE_KQUEUE
132    
133     If defined to be "1", libev will compile in support for the BSD
134     style kqueue backend. Its availability will be detected at runtime,
135     otherwise another method will be used as fallback. This is the
136     preferred backend for BSD and BSd-like systems. Darwin brokenness
137     will be detected at runtime and routed around by disabling this
138     backend.
139    
140 root 1.15 EV_H
141    
142     The name of the ev.h header file used to include it. The default
143     if undefined is <ev.h> in event.h and "ev.h" in ev.c. This can
144     be used to virtually rename the ev.h header file in case of
145     conflicts.
146    
147     EV_EVENT_H
148    
149     Similarly to EV_H, this macro cna be used to override event.c's idea
150     of how the event.h header can be found.
151    
152 root 1.1 EV_PROTOTYPES
153    
154     If defined to be "0", then "ev.h" will not define any function
155     prototypes, but still define all the structs and other
156     symbols. This is occasionally useful.
157    
158     EV_MULTIPLICITY
159    
160     If undefined or defined to "1", then all event-loop-specific
161     functions will have the "struct ev_loop *" as first argument, and
162     you can create additional independent event loops. Otherwise there
163     will be no support for multiple event loops and there is no first
164     event loop pointer argument. Instead, all functions act on the
165     single default loop.
166    
167 root 1.20 EV_PERIODICS
168    
169     If undefined or defined to be "1", then periodic timers are
170     supported, otherwise not. This saves a few kb of code.
171    
172     EV_COMMON
173    
174     By default, all watchers have a "void *data" member. By redefining
175     this macro to a something else you can include more and other types
176     of members. You have to define it each time you include one of the
177     files, though, and it must be identical each time.
178    
179     For example, the perl EV module uses this:
180    
181     #define EV_COMMON \
182     SV *self; /* contains this struct */ \
183     SV *cb_sv, *fh /* note no trailing ";" */
184    
185 root 1.15 EV_CB_DECLARE(type)
186     EV_CB_INVOKE(watcher,revents)
187 root 1.17 ev_set_cb(ev,cb)
188 root 1.15
189     Can be used to change the callback member declaration in each
190 root 1.17 watcher, and the way callbacks are invoked and set. Must expand
191     to a struct member definition and a statement, respectively. See
192     the ev.v header file for their default definitions. One possible
193     use for overriding these is to avoid the ev_loop pointer as first
194     argument in all cases, or to use method calls instead of plain
195     function calls in C++.
196 root 1.15
197 root 1.1 EXAMPLES
198    
199 root 1.2 For a real-world example of a program the includes libev
200     verbatim, you can have a look at the EV perl module
201     (http://software.schmorp.de/pkg/EV.html). It has the libev files in
202 root 1.5 the libev/ subdirectory and includes them in the EV/EVAPI.h (public
203     interface) and EV.xs (implementation) files. Only the EV.xs file will
204     be compiled.
205 root 1.1