ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libev/README.embed
Revision: 1.5
Committed: Tue Nov 6 19:45:29 2007 UTC (16 years, 6 months ago) by root
Branch: MAIN
Changes since 1.4: +7 -3 lines
Log Message:
*** empty log message ***

File Contents

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