summaryrefslogtreecommitdiff
path: root/README.embed
diff options
context:
space:
mode:
Diffstat (limited to 'README.embed')
-rw-r--r--README.embed140
1 files changed, 140 insertions, 0 deletions
diff --git a/README.embed b/README.embed
new file mode 100644
index 0000000..3e37f05
--- /dev/null
+++ b/README.embed
@@ -0,0 +1,140 @@
+EMBEDDING THE LIBEV CODE INTO YOUR OWN PROGRAMS
+
+ Instead of building the libev library you cna also include the code
+ as-is into your programs. To update, you only have to copy a few files
+ into your source tree.
+
+ This is how it works:
+
+FILESETS
+
+ To include only the libev core (all the ev_* functions):
+
+ #define EV_STANDALONE 1
+ #include "ev.c"
+
+ This will automatically include ev.h, too, and should be done in a
+ single C source file only to provide the function implementations. To
+ use it, do the same for ev.h in all users:
+
+ #define EV_STANDALONE 1
+ #include "ev.h"
+
+ You need the following files in your source tree, or in a directory
+ in your include path (e.g. in libev/ when using -Ilibev):
+
+ ev.h
+ ev.c
+ ev_vars.h
+ ev_wrap.h
+
+ To include the libevent compatibility API, also include:
+
+ #include "event.c"
+
+ in the file including "ev.c", and:
+
+ #include "event.h"
+
+ in the files that want to use the libevent API. This also includes "ev.h".
+
+ You need the following additional files for this:
+
+ event.h
+ event.c
+
+PREPROCESSOR SYMBOLS
+
+ Libev can be configured via a variety of preprocessor symbols you have to define
+ before including any of its files. The default is not to build for mulciplicity
+ and only include the select backend.
+
+ EV_STANDALONE
+
+ Must always be "1", which keeps libev from including config.h or
+ other files, and it also defines dummy implementations for some
+ libevent functions (such as logging, which is not supported). It
+ will also not define any of the structs usually found in "event.h"
+ that are not directly supported by libev code alone.
+
+ EV_USE_MONOTONIC
+
+ If undefined or defined to be "1", libev will try to detect the
+ availability of the monotonic clock option at both compiletime and
+ runtime. Otherwise no use of the monotonic clock option will be
+ attempted.
+
+ EV_USE_REALTIME
+
+ If defined to be "1", libev will try to detect the availability
+ of the realtime clock option at compiletime (and assume its
+ availability at runtime if successful). Otherwise no use of the
+ realtime clock option will be attempted. This effectively replaces
+ gettimeofday by clock_get (CLOCK_REALTIME, ...) and will not normally
+ affect correctness.
+
+ EV_USE_SELECT
+
+ If undefined or defined to be "1", libev will compile in support
+ for the select(2) backend. No attempt at autodetection will be
+ done: if no other method takes over, select will be it. Otherwise
+ the select backend will not be compiled in.
+
+ EV_USE_POLL
+
+ If defined to be "1", libev will compile in support for the poll(2)
+ backend. No attempt at autodetection will be done. poll usually
+ performs worse than select, so its not enabled by default (it is
+ also slightly less portable).
+
+ EV_USE_EPOLL
+
+ If defined to be "1", libev will compile in support for the Linux
+ epoll backend. Its availability will be detected at runtime,
+ otherwise another method will be used as fallback. This is the
+ preferred backend for GNU/Linux systems.
+
+ EV_USE_KQUEUE
+
+ If defined to be "1", libev will compile in support for the BSD
+ style kqueue backend. Its availability will be detected at runtime,
+ otherwise another method will be used as fallback. This is the
+ preferred backend for BSD and BSd-like systems. Darwin brokenness
+ will be detected at runtime and routed around by disabling this
+ backend.
+
+ EV_COMMON
+
+ By default, all watchers have a "void *data" member. By redefining
+ this macro to a something else you can include more and other types
+ of members. You have to define it each time you include one of the
+ files, though, and it must be identical each time.
+
+ For example, the perl EV module uses this:
+
+ #define EV_COMMON \
+ SV *self; /* contains this struct */ \
+ SV *cb_sv, *fh;
+
+ EV_PROTOTYPES
+
+ If defined to be "0", then "ev.h" will not define any function
+ prototypes, but still define all the structs and other
+ symbols. This is occasionally useful.
+
+ EV_MULTIPLICITY
+
+ If undefined or defined to "1", then all event-loop-specific
+ functions will have the "struct ev_loop *" as first argument, and
+ you can create additional independent event loops. Otherwise there
+ will be no support for multiple event loops and there is no first
+ event loop pointer argument. Instead, all functions act on the
+ single default loop.
+
+EXAMPLES
+
+ For a real-world example of a program the includes libev verbatim, you
+ can have a look at the EV perl module (http://software.schmorp.de/pkg/EV.html).
+ It has the libev files in the liev/ subdirectory and includes them in the
+ EV.xs files. Only this file will be compiled.
+