mirrors
/
libev
mirror of /home/gitosis/repositories/libev.git
1
0
Fork 0
Code Releases Activity

include embedding doc in main doc

Browse Source
master
Marc Alexander Lehmann 16 years ago
parent 669bbc0040
commit b4867eea68
1 changed files with 276 additions and 0 deletions
Show Stats Download Patch File Download Diff File

276
ev.pod
Unescape Escape View File

@ -1416,6 +1416,282 @@ the constructor.
io.start (fd, ev::READ);
}
=head1 EMBEDDING
Libev can (and often is) directly embedded into host
applications. Examples of applications that embed it include the Deliantra
Game Server, the EV perl module, the GNU Virtual Private Ethernet (gvpe)
and rxvt-unicode.
The goal is to enable you to just copy the neecssary files into your
source directory without having to change even a single line in them, so
you can easily upgrade by simply copying (or having a checked-out copy of
libev somewhere in your source tree).
=head2 FILESETS
Depending on what features you need you need to include one or more sets of files
in your app.
=head3 CORE EVENT LOOP
To include only the libev core (all the C<ev_*> functions), with manual
configuration (no autoconf):
#define EV_STANDALONE 1
#include "ev.c"
This will automatically include F<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 F<ev.h> in all files wishing to use this API (best
done by writing a wrapper around F<ev.h> that you can include instead and
where you can put other configuration options):
#define EV_STANDALONE 1
#include "ev.h"
Both header files and implementation files can be compiled with a C++
compiler (at least, thats a stated goal, and breakage will be treated
as a bug).
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
ev_win32.c required on win32 platforms only
ev_select.c only when select backend is enabled (which is is by default)
ev_poll.c only when poll backend is enabled (disabled by default)
ev_epoll.c only when the epoll backend is enabled (disabled by default)
ev_kqueue.c only when the kqueue backend is enabled (disabled by default)
ev_port.c only when the solaris port backend is enabled (disabled by default)
F<ev.c> includes the backend files directly when enabled, so you only need
to compile a single file.
=head3 LIBEVENT COMPATIBILITY API
To include the libevent compatibility API, also include:
#include "event.c"
in the file including F<ev.c>, and:
#include "event.h"
in the files that want to use the libevent API. This also includes F<ev.h>.
You need the following additional files for this:
event.h
event.c
=head3 AUTOCONF SUPPORT
Instead of using C<EV_STANDALONE=1> and providing your config in
whatever way you want, you can also C<m4_include([libev.m4])> in your
F<configure.ac> and leave C<EV_STANDALONE> off. F<ev.c> will then include
F<config.h> and configure itself accordingly.
For this of course you need the m4 file:
libev.m4
=head2 PREPROCESSOR SYMBOLS/MACROS
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 multiplicity
and only include the select backend.
=over 4
=item EV_STANDALONE
Must always be C<1> if you do not use autoconf configuration, which
keeps libev from including F<config.h>, 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
F<event.h> that are not directly supported by the libev core alone.
=item EV_USE_MONOTONIC
If defined to be C<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. If you enable this, you
usually have to link against librt or something similar. Enabling it when
the functionality isn't available is safe, though, althoguh you have
to make sure you link against any libraries where the C<clock_gettime>
function is hiding in (often F<-lrt>).
=item EV_USE_REALTIME
If defined to be C<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 C<gettimeofday> by C<clock_get
(CLOCK_REALTIME, ...)> and will not normally affect correctness. See tzhe note about libraries
in the description of C<EV_USE_MONOTONIC>, though.
=item EV_USE_SELECT
If undefined or defined to be C<1>, libev will compile in support for the
C<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.
=item EV_SELECT_USE_FD_SET
If defined to C<1>, then the select backend will use the system C<fd_set>
structure. This is useful if libev doesn't compile due to a missing
C<NFDBITS> or C<fd_mask> definition or it misguesses the bitset layout on
exotic systems. This usually limits the range of file descriptors to some
low limit such as 1024 or might have other limitations (winsocket only
allows 64 sockets). The C<FD_SETSIZE> macro, set before compilation, might
influence the size of the C<fd_set> used.
=item EV_SELECT_IS_WINSOCKET
When defined to C<1>, the select backend will assume that
select/socket/connect etc. don't understand file descriptors but
wants osf handles on win32 (this is the case when the select to
be used is the winsock select). This means that it will call
C<_get_osfhandle> on the fd to convert it to an OS handle. Otherwise,
it is assumed that all these functions actually work on fds, even
on win32. Should not be defined on non-win32 platforms.
=item EV_USE_POLL
If defined to be C<1>, libev will compile in support for the C<poll>(2)
backend. Otherwise it will be enabled on non-win32 platforms. It
takes precedence over select.
=item EV_USE_EPOLL
If defined to be C<1>, libev will compile in support for the Linux
C<epoll>(7) 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.
=item EV_USE_KQUEUE
If defined to be C<1>, libev will compile in support for the BSD style
C<kqueue>(2) backend. Its actual 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, although on most BSDs kqueue only
supports some types of fds correctly (the only platform we found that
supports ptys for example was NetBSD), so kqueue might be compiled in, but
not be used unless explicitly requested. The best way to use it is to find
out wether kqueue supports your type of fd properly and use an embedded
kqueue loop.
=item EV_USE_PORT
If defined to be C<1>, libev will compile in support for the Solaris
10 port style backend. Its availability will be detected at runtime,
otherwise another method will be used as fallback. This is the preferred
backend for Solaris 10 systems.
=item EV_USE_DEVPOLL
reserved for future expansion, works like the USE symbols above.
=item EV_H
The name of the F<ev.h> header file used to include it. The default if
undefined is C<< <ev.h> >> in F<event.h> and C<"ev.h"> in F<ev.c>. This
can be used to virtually rename the F<ev.h> header file in case of conflicts.
=item EV_CONFIG_H
If C<EV_STANDALONE> isn't C<1>, this variable can be used to override
F<ev.c>'s idea of where to find the F<config.h> file, similarly to
C<EV_H>, above.
=item EV_EVENT_H
Similarly to C<EV_H>, this macro can be used to override F<event.c>'s idea
of how the F<event.h> header can be found.
=item EV_PROTOTYPES
If defined to be C<0>, then F<ev.h> will not define any function
prototypes, but still define all the structs and other symbols. This is
occasionally useful if you want to provide your own wrapper functions
around libev functions.
=item EV_MULTIPLICITY
If undefined or defined to C<1>, then all event-loop-specific functions
will have the C<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.
=item EV_PERIODICS
If undefined or defined to be C<1>, then periodic timers are supported,
otherwise not. This saves a few kb of code.
=item EV_COMMON
By default, all watchers have a C<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 something like this:
#define EV_COMMON \
SV *self; /* contains this struct */ \
SV *cb_sv, *fh /* note no trailing ";" */
=item EV_CB_DECLARE(type)
=item EV_CB_INVOKE(watcher,revents)
=item ev_set_cb(ev,cb)
Can be used to change the callback member declaration in each watcher,
and the way callbacks are invoked and set. Must expand to a struct member
definition and a statement, respectively. See the F<ev.v> header file for
their default definitions. One possible use for overriding these is to
avoid the ev_loop pointer as first argument in all cases, or to use method
calls instead of plain function calls in C++.
=head2 EXAMPLES
For a real-world example of a program the includes libev
verbatim, you can have a look at the EV perl module
(L<http://software.schmorp.de/pkg/EV.html>). It has the libev files in
the F<libev/> subdirectory and includes them in the F<EV/EVAPI.h> (public
interface) and F<EV.xs> (implementation) files. Only the F<EV.xs> file
will be compiled. It is pretty complex because it provides its own header
file.
The usage in rxvt-unicode is simpler. It has a F<ev_cpp.h> header file
that everybody includes and which overrides some autoconf choices:
#define EV_USE_POLL 0
#define EV_MULTIPLICITY 0
#define EV_PERIODICS 0
#define EV_CONFIG_H <config.h>
#include "ev++.h"
And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
#include "rxvttoolkit.h"
/* darwin has problems with its header files in C++, requiring this namespace juggling */
using namespace ev;
#include "ev.c"
=head1 AUTHOR
Marc Lehmann <libev@schmorp.de>.

Write Preview
Loading…
Cancel
Save