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

Comparing libev/ev.pod (file contents):
Revision 1.108 by root, Mon Dec 24 10:39:21 2007 UTC vs.
Revision 1.112 by root, Wed Dec 26 08:06:09 2007 UTC

 In general you can register as many read and/or write event watchers per
 fd as you want (as long as you don't confuse yourself). Setting all file
 descriptors to non-blocking mode is also usually a good idea (but not
 required if you know what you are doing).
-You have to be careful with dup'ed file descriptors, though. Some backends
-(the linux epoll backend is a notable example) cannot handle dup'ed file
-descriptors correctly if you register interest in two or more fds pointing
-to the same underlying file/socket/etc. description (that is, they share
-the same underlying "file open").
 If you must do this, then force the use of a known-to-be-good backend
 (at the time of this writing, this includes only C<EVBACKEND_SELECT> and
 C<EVBACKEND_POLL>).
 Another thing you have to watch out for is that it is quite easy to
 =head3 The special problem of dup'ed file descriptors
 Some backends (e.g. epoll), cannot register events for file descriptors,
 but only events for the underlying file descriptions. That means when you
-have C<dup ()>'ed file descriptors and register events for them, only one
+have C<dup ()>'ed file descriptors or weirder constellations, and register
-file descriptor might actually receive events.
+events for them, only one file descriptor might actually receive events.
 There is no workaround possible except not registering events
 for potentially C<dup ()>'ed file descriptors, or to resort to
 C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>.
 =item int events [read-only]
 The events being watched.
 =back
+=head3 Examples
 Example: Call C<stdin_readable_cb> when STDIN_FILENO has become, well
 readable, but only once. Since it is likely line-buffered, you could
 attempt to read a whole line in the callback.
 or C<ev_timer_again> is called and determines the next timeout (if any),
 which is also when any modifications are taken into account.
 =back
+=head3 Examples
 Example: Create a timer that fires after 60 seconds.
   static void
   one_minute_cb (struct ev_loop *loop, struct ev_timer *w, int revents)
   {
 When active, contains the absolute time that the watcher is supposed to
 trigger next.
 =back
+=head3 Examples
 Example: Call a callback every hour, or, more precisely, whenever the
 system clock is divisible by 3600. The callback invocation times have
 potentially a lot of jittering, but good long-term stability.
   static void
 The process exit/trace status caused by C<rpid> (see your systems
 C<waitpid> and C<sys/wait.h> documentation for details).
 =back
+=head3 Examples
 Example: Try to exit cleanly on SIGINT and SIGTERM.
   static void
   sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents)
 kind. There is a C<ev_idle_set> macro, but using it is utterly pointless,
 believe me.
 =back
+=head3 Examples
 Example: Dynamically allocate an C<ev_idle> watcher, start it, and in the
 callback, free it. Also, use no error checking, as usual.
   static void
   idle_cb (struct ev_loop *loop, struct ev_idle *w, int revents)
 parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set>
 macros, but using them is utterly, utterly and completely pointless.
 =back
+=head3 Examples
 There are a number of principal ways to embed other event loops or modules
 into libev. Here are some ideas on how to include libadns into libev
 (there is a Perl module named C<EV::ADNS> that does this, which you could
 use for an actually working example. Another Perl module named C<EV::Glib>
 embeds a Glib main context into libev, and finally, C<Glib::EV> embeds EV
 portable one.
 So when you want to use this feature you will always have to be prepared
 that you cannot get an embeddable loop. The recommended way to get around
 this is to have a separate variables for your embeddable loop, try to
-create it, and if that fails, use the normal loop for everything:
+create it, and if that fails, use the normal loop for everything.
+=head3 Watcher-Specific Functions and Data Members
+=over 4
+=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)
+=item ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)
+Configures the watcher to embed the given loop, which must be
+embeddable. If the callback is C<0>, then C<ev_embed_sweep> will be
+invoked automatically, otherwise it is the responsibility of the callback
+to invoke it (it will continue to be called until the sweep has been done,
+if you do not want thta, you need to temporarily stop the embed watcher).
+=item ev_embed_sweep (loop, ev_embed *)
+Make a single, non-blocking sweep over the embedded loop. This works
+similarly to C<ev_loop (embedded_loop, EVLOOP_NONBLOCK)>, but in the most
+apropriate way for embedded loops.
+=item struct ev_loop *other [read-only]
+The embedded event loop.
+=back
+=head3 Examples
+Example: Try to get an embeddable event loop and embed it into the default
+event loop. If that is not possible, use the default loop. The default
+loop is stored in C<loop_hi>, while the mebeddable loop is stored in
+C<loop_lo> (which is C<loop_hi> in the acse no embeddable loop can be
+used).
   struct ev_loop *loop_hi = ev_default_init (0);
   struct ev_loop *loop_lo = 0;
   struct ev_embed embed;
       ev_embed_start (loop_hi, &embed);
     }
   else
     loop_lo = loop_hi;
-=head3 Watcher-Specific Functions and Data Members
+Example: Check if kqueue is available but not recommended and create
+a kqueue backend for use with sockets (which usually work with any
+kqueue implementation). Store the kqueue/socket-only event loop in
+C<loop_socket>. (One might optionally use C<EVFLAG_NOENV>, too).
-=over 4
+  struct ev_loop *loop = ev_default_init (0);
+  struct ev_loop *loop_socket = 0;
+  struct ev_embed embed;
+  if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE)
+    if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE))
+      {
+        ev_embed_init (&embed, 0, loop_socket);
+        ev_embed_start (loop, &embed);
+      }
-=item ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)
+  if (!loop_socket)
+    loop_socket = loop;
-=item ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)
+  // now use loop_socket for all sockets, and loop for everything else
-Configures the watcher to embed the given loop, which must be
-embeddable. If the callback is C<0>, then C<ev_embed_sweep> will be
-invoked automatically, otherwise it is the responsibility of the callback
-to invoke it (it will continue to be called until the sweep has been done,
-if you do not want thta, you need to temporarily stop the embed watcher).
-=item ev_embed_sweep (loop, ev_embed *)
-Make a single, non-blocking sweep over the embedded loop. This works
-similarly to C<ev_loop (embedded_loop, EVLOOP_NONBLOCK)>, but in the most
-apropriate way for embedded loops.
-=item struct ev_loop *other [read-only]
-The embedded event loop.
-=back
 =head2 C<ev_fork> - the audacity to resume the event loop after a fork
 Fork watchers are called when a C<fork ()> was detected (usually because
 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_FD_TO_WIN32_HANDLE
+If C<EV_SELECT_IS_WINSOCKET> is enabled, then libev needs a way to map
+file descriptors to socket handles. When not defining this symbol (the
+default), then libev will call C<_get_osfhandle>, which is usually
+correct. In some cases, programs use their own file descriptor management,
+in which case they can provide this function to map fds to socket handles.
 =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
 be detected at runtime.
 =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
+undefined is C<"ev.h"> in F<event.h> and F<ev.c>. This can be used to
-can be used to virtually rename the F<ev.h> header file in case of conflicts.
+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.
+of how the F<event.h> header can be found, the dfeault is C<"event.h">.
 =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
 watchers becomes O(1) w.r.t. prioritiy handling.
 =back
+=head1 Win32 platform limitations and workarounds
+Win32 doesn't support any of the standards (e.g. POSIX) that libev
+requires, and its I/O model is fundamentally incompatible with the POSIX
+model. Libev still offers limited functionality on this platform in
+the form of the C<EVBACKEND_SELECT> backend, and only supports socket
+descriptors. This only applies when using Win32 natively, not when using
+e.g. cygwin.
+There is no supported compilation method available on windows except
+embedding it into other applications.
+Due to the many, low, and arbitrary limits on the win32 platform and the
+abysmal performance of winsockets, using a large number of sockets is not
+recommended (and not reasonable). If your program needs to use more than
+a hundred or so sockets, then likely it needs to use a totally different
+implementation for windows, as libev offers the POSIX model, which cannot
+be implemented efficiently on windows (microsoft monopoly games).
+=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>. This makes select
+very inefficient, and also requires a mapping from file descriptors
+to socket handles. 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:
+  #define EV_USE_SELECT 1
+  #define EV_SELECT_IS_WINSOCKET 1   /* forces EV_SELECT_USE_FD_SET, too */
+Note that winsockets handling of fd sets is O(n), so you can easily get a
+complexity in the O(n²) range when using win32.
+=item Limited number of file descriptors
+Windows has numerous arbitrary (and low) limits on things. Early versions
+of winsocket's select only supported waiting for a max. of C<64> handles
+(probably owning to the fact that all windows kernels can only wait for
+C<64> things at the same time internally; microsoft recommends spawning a
+chain of threads and wait for 63 handles and the previous thread in each).
+Newer versions support more handles, but you need to define C<FD_SETSIZE>
+to some high number (e.g. C<2048>) before compiling the winsocket select
+call (which might be in libev or elsewhere, for example, perl does its own
+select emulation on windows).
+Another limit is the number of file descriptors in the microsoft runtime
+libraries, which by default is C<64> (there must be a hidden I<64> fetish
+or something like this inside microsoft). You can increase this by calling
+C<_setmaxstdio>, which can increase this limit to C<2048> (another
+arbitrary limit), but is broken in many versions of the microsoft runtime
+libraries.
+This might get you to about C<512> or C<2048> sockets (depending on
+windows version and/or the phase of the moon). To get more, you need to
+wrap all I/O functions and provide your own fd management, but the cost of
+calling select (O(n²)) will likely make this unworkable.
+=back
 =head1 AUTHOR
 Marc Lehmann <libev@schmorp.de>.

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.108 by root, Mon Dec 24 10:39:21 2007 UTC vs. Revision 1.112 by root, Wed Dec 26 08:06:09 2007 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.108 by root, Mon Dec 24 10:39:21 2007 UTC vs.
Revision 1.112 by root, Wed Dec 26 08:06:09 2007 UTC