[ViewVC] Diff of: cvs/libev/ev.pod

Comparing libev/ev.pod (file contents):
Revision 1.164 by root, Sat May 31 23:22:23 2008 UTC vs.
Revision 1.170 by root, Sat Jul 5 02:25:40 2008 UTC

 will be no polling.
 =head3 ABI Issues (Largefile Support)
 Libev by default (unless the user overrides this) uses the default
-compilation environment, which means that on systems with optionally
+compilation environment, which means that on systems with large file
-disabled large file support, you get the 32 bit version of the stat
+support disabled by default, you get the 32 bit version of the stat
 structure. When using the library from programs that change the ABI to
 use 64 bit file offsets the programs will fail. In that case you have to
 compile libev with the same flags to get binary compatibility. This is
 obviously the case with any flags that change the ABI, but the problem is
-most noticeably with ev_stat and large file support.
+most noticeably disabled with ev_stat and large file support.
+The solution for this is to lobby your distribution maker to make large
+file interfaces available by default (as e.g. FreeBSD does) and not
+optional. Libev cannot simply switch on large file support because it has
+to exchange stat structures with application programs compiled using the
+default compilation environment.
 =head3 Inotify
 When C<inotify (7)> support has been compiled into libev (generally only
 available on Linux) and present at runtime, it will be used to speed up
 libev. EV is developed together with libev. Apart from the EV core module,
 there are additional modules that implement libev-compatible interfaces
 to C<libadns> (C<EV::ADNS>), C<Net::SNMP> (C<Net::SNMP::EV>) and the
 C<libglib> event core (C<Glib::EV> and C<EV::Glib>).
-It can be found and installed via CPAN, its homepage is found at
+It can be found and installed via CPAN, its homepage is at
 L<http://software.schmorp.de/pkg/EV>.
+=item Python
+Python bindings can be found at L<http://code.google.com/p/pyev/>. It
+seems to be quite complete and well-documented. Note, however, that the
+patch they require for libev is outright dangerous as it breaks the ABI
+for everybody else, and therefore, should never be applied in an installed
+libev (if python requires an incompatible ABI then it needs to embed
+libev).
 =item Ruby
 Tony Arcieri has written a ruby extension that offers access to a subset
 of the libev API and adds file handle abstractions, asynchronous DNS and
 parallel from multiple threads, calls with the same loop parameter must be
 done serially (but can be done from different threads, as long as only one
 thread ever is inside a call at any point in time, e.g. by using a mutex
 per loop).
-If you want to know which design is best for your problem, then I cannot
+If you want to know which design (one loop, locking, or multiple loops
-help you but by giving some generic advice:
+without or something else still) is best for your problem, then I cannot
+help you. I can give some generic advice however:
 =over 4
 =item * most applications have a main thread: use the default libev loop
 in that thread, or create a separate thread running only the default loop.
 more than a hundred or so sockets, then likely it needs to use a totally
 different implementation for windows, as libev offers the POSIX readiness
 notification model, which cannot be implemented efficiently on windows
 (Microsoft monopoly games).
+A typical way to use libev under windows is to embed it (see the embedding
+section for details) and use the following F<evwrap.h> header file instead
+of F<ev.h>:
+   #define EV_STANDALONE              /* keeps ev from requiring config.h */
+   #define EV_SELECT_IS_WINSOCKET 1   /* configure libev for windows select */
+   #include "ev.h"
+And compile the following F<evwrap.c> file into your project (make sure
+you do I<not> compile the F<ev.c> or any other embedded soruce files!):
+   #include "evwrap.h"
+   #include "ev.c"
 =over 4
 =item The winsocket select function
 The winsocket C<select> function doesn't follow POSIX in that it
 requires socket I<handles> and not socket I<file descriptors> (it is
 also extremely buggy). This makes select very inefficient, and also
-requires a mapping from file descriptors to socket handles. See the
+requires a mapping from file descriptors to socket handles (the Microsoft
+C runtime provides the function C<_open_osfhandle> for this). See the
 discussion of the C<EV_SELECT_USE_FD_SET>, C<EV_SELECT_IS_WINSOCKET> and
 C<EV_FD_TO_WIN32_HANDLE> preprocessor symbols for more info.
 The configuration for a "naked" win32 using the Microsoft runtime
 libraries and raw winsocket select is:
 In addition to a working ISO-C implementation, libev relies on a few
 additional extensions:
 =over 4
+=item C<void (*)(ev_watcher_type *, int revents)> must have compatible
+calling conventions regardless of C<ev_watcher_type *>.
+Libev assumes not only that all watcher pointers have the same internal
+structure (guaranteed by POSIX but not by ISO C for example), but it also
+assumes that the same (machine) code can be used to call any watcher
+callback: The watcher callbacks have different type signatures, but libev
+calls them using an C<ev_watcher *> internally.
 =item C<sig_atomic_t volatile> must be thread-atomic as well
 The type C<sig_atomic_t volatile> (or whatever is defined as
 C<EV_ATOMIC_T>) must be atomic w.r.t. accesses from different
 threads. This is not part of the specification for C<sig_atomic_t>, but is

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing libev/ev.pod (file contents): Revision 1.164 by root, Sat May 31 23:22:23 2008 UTC vs. Revision 1.170 by root, Sat Jul 5 02:25:40 2008 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.164 by root, Sat May 31 23:22:23 2008 UTC vs.
Revision 1.170 by root, Sat Jul 5 02:25:40 2008 UTC