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

Comparing libev/ev.pod (file contents):
Revision 1.406 by root, Thu May 3 16:00:47 2012 UTC vs.
Revision 1.419 by root, Sun Jun 24 14:30:40 2012 UTC

 =head1 WHAT TO READ WHEN IN A HURRY
 This manual tries to be very detailed, but unfortunately, this also makes
 it very long. If you just want to know the basics of libev, I suggest
-reading L<ANATOMY OF A WATCHER>, then the L<EXAMPLE PROGRAM> above and
+reading L</ANATOMY OF A WATCHER>, then the L</EXAMPLE PROGRAM> above and
-look up the missing functions in L<GLOBAL FUNCTIONS> and the C<ev_io> and
+look up the missing functions in L</GLOBAL FUNCTIONS> and the C<ev_io> and
-C<ev_timer> sections in L<WATCHER TYPES>.
+C<ev_timer> sections in L</WATCHER TYPES>.
 =head1 ABOUT LIBEV
 Libev is an event loop: you register interest in certain events (such as a
 file descriptor being readable or a timeout occurring), and it will manage
 This function is rarely useful, but when some event callback runs for a
 very long time without entering the event loop, updating libev's idea of
 the current time is a good idea.
-See also L<The special problem of time updates> in the C<ev_timer> section.
+See also L</The special problem of time updates> in the C<ev_timer> section.
 =item ev_suspend (loop)
 =item ev_resume (loop)
 =item callback ev_cb (ev_TYPE *watcher)
 Returns the callback currently set on the watcher.
-=item ev_cb_set (ev_TYPE *watcher, callback)
+=item ev_set_cb (ev_TYPE *watcher, callback)
 Change the callback. You can change the callback at virtually any time
 (modulo threads).
 =item ev_set_priority (ev_TYPE *watcher, int priority)
 or might not have been clamped to the valid range.
 The default priority used by watchers when no priority has been set is
 always C<0>, which is supposed to not be too high and not be too low :).
-See L<WATCHER PRIORITY MODELS>, below, for a more thorough treatment of
+See L</WATCHER PRIORITY MODELS>, below, for a more thorough treatment of
 priorities.
 =item ev_invoke (loop, ev_TYPE *watcher, int revents)
 Invoke the C<watcher> with the given C<loop> and C<revents>. Neither
 See also C<ev_feed_fd_event> and C<ev_feed_signal_event> for related
 functions that do not need a watcher.
 =back
-See also the L<ASSOCIATING CUSTOM DATA WITH A WATCHER> and L<BUILDING YOUR
+See also the L</ASSOCIATING CUSTOM DATA WITH A WATCHER> and L</BUILDING YOUR
 OWN COMPOSITE WATCHERS> idioms.
 =head2 WATCHER STATES
 There are various watcher states mentioned throughout this manual -
 =item If the timer is repeating, make the C<repeat> value the new timeout
 and start the timer, if necessary.
 =back
-This sounds a bit complicated, see L<Be smart about timeouts>, above, for a
+This sounds a bit complicated, see L</Be smart about timeouts>, above, for a
 usage example.
 =item ev_tstamp ev_timer_remaining (loop, ev_timer *)
 Returns the remaining time until a timer fires. If the timer is active,
 This mode of operation can be useful together with an C<ev_check> watcher,
 to do something on each event loop iteration - for example to balance load
 between different connections.
-See L<Abusing an C<ev_check> watcher for its side-effect> for a longer
+See L</Abusing an ev_check watcher for its side-effect> for a longer
 example.
 =head3 Watcher-Specific Functions and Data Members
 =over 4
 callback, free it. Also, use no error checking, as usual.
    static void
    idle_cb (struct ev_loop *loop, ev_idle *w, int revents)
    {
+     // stop the watcher
+     ev_idle_stop (loop, w);
+     // now we can free it
      free (w);
      // now do something you wanted to do when the program has
      // no longer anything immediate to do.
    }
    ev_idle *idle_watcher = malloc (sizeof (ev_idle));
 called):
    void
    wait_for_event (ev_watcher *w)
    {
-     ev_cb_set (w) = current_coro;
+     ev_set_cb (w, current_coro);
      switch_to (libev_coro);
    }
 That basically suspends the coroutine inside C<wait_for_event> and
 continues the libev coroutine, which, when appropriate, switches back to
 You can do similar tricks if you have, say, threads with an event queue -
 instead of storing a coroutine, you store the queue object and instead of
 switching to a coroutine, you push the watcher onto the queue and notify
 any waiters.
-To embed libev, see L<EMBEDDING>, but in short, it's easiest to create two
+To embed libev, see L</EMBEDDING>, but in short, it's easiest to create two
 files, F<my_ev.h> and F<my_ev.c> that include the respective libev files:
    // my_ev.h
    #define EV_CB_DECLARE(type)   struct my_coro *cb;
    #define EV_CB_INVOKE(watcher) switch_to ((watcher)->cb);
 libev sources can be compiled as C++. Therefore, code that uses the C API
 will work fine.
 Proper exception specifications might have to be added to callbacks passed
 to libev: exceptions may be thrown only from watcher callbacks, all
-other callbacks (allocator, syserr, loop acquire/release and periodioc
+other callbacks (allocator, syserr, loop acquire/release and periodic
 reschedule callbacks) must not throw exceptions, and might need a C<throw
 ()> specification. If you have code that needs to be compiled as both C
 and C++ you can use the C<EV_THROW> macro for this:
    static void
 Associates a different C<struct ev_loop> with this watcher. You can only
 do this when the watcher is inactive (and not pending either).
 =item w->set ([arguments])
-Basically the same as C<ev_TYPE_set>, with the same arguments. Either this
+Basically the same as C<ev_TYPE_set> (except for C<ev::embed> watchers>),
-method or a suitable start method must be called at least once. Unlike the
+with the same arguments. Either this method or a suitable start method
-C counterpart, an active watcher gets automatically stopped and restarted
+must be called at least once. Unlike the C counterpart, an active watcher
-when reconfiguring it with this method.
+gets automatically stopped and restarted when reconfiguring it with this
+method.
+For C<ev::embed> watchers this method is called C<set_embed>, to avoid
+clashing with the C<set (loop)> method.
 =item w->start ()
 Starts the watcher. Note that there is no C<loop> argument, as the
 constructor already stores the event loop.
 =item Lua
 Brian Maher has written a partial interface to libev for lua (at the
 time of this writing, only C<ev_io> and C<ev_timer>), to be found at
 L<http://github.com/brimworks/lua-ev>.
+=item Javascript
+Node.js (L<http://nodejs.org>) uses libev as the underlying event library.
+=item Others
+There are others, and I stopped counting.
 =back
 =head1 MACRO MAGIC
 If programs implement their own fd to handle mapping on win32, then this
 macro can be used to override the C<close> function, useful to unregister
 file descriptors again. Note that the replacement function has to close
 the underlying OS handle.
+=item EV_USE_WSASOCKET
+If defined to be C<1>, libev will use C<WSASocket> to create its internal
+communication socket, which works better in some environments. Otherwise,
+the normal C<socket> function will be used, which works better in other
+environments.
 =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
 default loop and triggering an C<ev_async> watcher from the default loop
 watcher callback into the event loop interested in the signal.
 =back
-See also L<THREAD LOCKING EXAMPLE>.
+See also L</THREAD LOCKING EXAMPLE>.
 =head3 COROUTINES
 Libev is very accommodating to coroutines ("cooperative threads"):
 libev fully supports nesting calls to its functions from different
 =over 4
 =item C<EV_COMPAT3> backwards compatibility mechanism
 The backward compatibility mechanism can be controlled by
-C<EV_COMPAT3>. See L<PREPROCESSOR SYMBOLS/MACROS> in the L<EMBEDDING>
+C<EV_COMPAT3>. See L</PREPROCESSOR SYMBOLS/MACROS> in the L</EMBEDDING>
 section.
 =item C<ev_default_destroy> and C<ev_default_fork> have been removed
 These calls can be replaced easily by their C<ev_loop_xxx> counterparts:
 =over 4
 =item active
 A watcher is active as long as it has been started and not yet stopped.
-See L<WATCHER STATES> for details.
+See L</WATCHER STATES> for details.
 =item application
 In this document, an application is whatever is using libev.
 watchers and events.
 =item pending
 A watcher is pending as soon as the corresponding event has been
-detected. See L<WATCHER STATES> for details.
+detected. See L</WATCHER STATES> for details.
 =item real time
 The physical time that is observed. It is apparently strictly monotonic :)

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.406 by root, Thu May 3 16:00:47 2012 UTC vs. Revision 1.419 by root, Sun Jun 24 14:30:40 2012 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.406 by root, Thu May 3 16:00:47 2012 UTC vs.
Revision 1.419 by root, Sun Jun 24 14:30:40 2012 UTC