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

Comparing libev/ev.3 (file contents):
Revision 1.85 by root, Tue Jan 11 13:45:28 2011 UTC vs.
Revision 1.86 by root, Wed Feb 16 08:07:25 2011 UTC

 .\}
 .rm #[ #] #H #V #F C
 .\" ========================================================================
 .\"
 .IX Title "LIBEV 3"
-.TH LIBEV 3 "2011-01-11" "libev-4.03" "libev - high performance full featured event loop"
+.TH LIBEV 3 "2011-01-31" "libev-4.04" "libev - high performance full featured event loop"
 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 .\" way too many mistakes in technical documents.
 .if n .ad l
 .nh
 .SH "NAME"
 \&     ev_timer_start (loop, &timeout_watcher);
 \&
 \&     // now wait for events to arrive
 \&     ev_run (loop, 0);
 \&
-\&     // unloop was called, so exit
+\&     // break was called, so exit
 \&     return 0;
 \&   }
 .Ve
 .SH "ABOUT THIS DOCUMENT"
 .IX Header "ABOUT THIS DOCUMENT"
 when you want to receive them.
 .Sp
 This behaviour is useful when you want to do your own signal handling, or
 want to handle signals only in specific threads and want to avoid libev
 unblocking the signals.
+.Sp
+It's also required by \s-1POSIX\s0 in a threaded program, as libev calls
+\&\f(CW\*(C`sigprocmask\*(C'\fR, whose behaviour is officially unspecified.
 .Sp
 This flag's behaviour will become the default in future versions of libev.
 .ie n .IP """EVBACKEND_SELECT""  (value 1, portable select backend)" 4
 .el .IP "\f(CWEVBACKEND_SELECT\fR  (value 1, portable select backend)" 4
 .IX Item "EVBACKEND_SELECT  (value 1, portable select backend)"
 .Sp
 .Vb 4
 \&   ... queue jobs here, make sure they register event watchers as long
 \&   ... as they still have work to do (even an idle watcher will do..)
 \&   ev_run (my_loop, 0);
-\&   ... jobs done or somebody called unloop. yeah!
+\&   ... jobs done or somebody called break. yeah!
 .Ve
 .IP "ev_break (loop, how)" 4
 .IX Item "ev_break (loop, how)"
 Can be used to make a call to \f(CW\*(C`ev_run\*(C'\fR return early (but only after it
 has processed all outstanding events). The \f(CW\*(C`how\*(C'\fR argument must be either
 .IX Item "initialiased"
 Before a watcher can be registered with the event looop it has to be
 initialised. This can be done with a call to \f(CW\*(C`ev_TYPE_init\*(C'\fR, or calls to
 \&\f(CW\*(C`ev_init\*(C'\fR followed by the watcher-specific \f(CW\*(C`ev_TYPE_set\*(C'\fR function.
 .Sp
-In this state it is simply some block of memory that is suitable for use
+In this state it is simply some block of memory that is suitable for
-in an event loop. It can be moved around, freed, reused etc. at will.
+use in an event loop. It can be moved around, freed, reused etc. at
+will \- as long as you either keep the memory contents intact, or call
+\&\f(CW\*(C`ev_TYPE_init\*(C'\fR again.
 .IP "started/running/active" 4
 .IX Item "started/running/active"
 Once a watcher has been started with a call to \f(CW\*(C`ev_TYPE_start\*(C'\fR it becomes
 property of the event loop, and is actively waiting for events. While in
 this state it cannot be accessed (except in a few documented ways), moved,
 latter will clear any pending state the watcher might be in, regardless
 of whether it was active or not, so stopping a watcher explicitly before
 freeing it is often a good idea.
 .Sp
 While stopped (and not pending) the watcher is essentially in the
-initialised state, that is it can be reused, moved, modified in any way
+initialised state, that is, it can be reused, moved, modified in any way
-you wish.
+you wish (but when you trash the memory block, you need to \f(CW\*(C`ev_TYPE_init\*(C'\fR
+it again).
 .SS "\s-1WATCHER\s0 \s-1PRIORITY\s0 \s-1MODELS\s0"
 .IX Subsection "WATCHER PRIORITY MODELS"
 Many event loops support \fIwatcher priorities\fR, which are usually small
 integers that influence the ordering of event callback invocation
 between watchers in some way, all else being equal.
 .IX Subsection "The special problem of inheritance over fork/execve/pthread_create"
 .PP
 Both the signal mask (\f(CW\*(C`sigprocmask\*(C'\fR) and the signal disposition
 (\f(CW\*(C`sigaction\*(C'\fR) are unspecified after starting a signal watcher (and after
 stopping it again), that is, libev might or might not block the signal,
-and might or might not set or restore the installed signal handler.
+and might or might not set or restore the installed signal handler (but
+see \f(CW\*(C`EVFLAG_NOSIGMASK\*(C'\fR).
 .PP
 While this does not matter for the signal disposition (libev never
 sets signals to \f(CW\*(C`SIG_IGN\*(C'\fR, so handlers will be reset to \f(CW\*(C`SIG_DFL\*(C'\fR on
 \&\f(CW\*(C`execve\*(C'\fR), this matters for the signal mask: many programs do not expect
 certain signals to be blocked.
 \&   atexit (program_exits);
 .Ve
 .ie n .SS """ev_async"" \- how to wake up an event loop"
 .el .SS "\f(CWev_async\fP \- how to wake up an event loop"
 .IX Subsection "ev_async - how to wake up an event loop"
-In general, you cannot use an \f(CW\*(C`ev_run\*(C'\fR from multiple threads or other
+In general, you cannot use an \f(CW\*(C`ev_loop\*(C'\fR from multiple threads or other
 asynchronous sources such as signal handlers (as opposed to multiple event
 loops \- those are of course safe to use in different threads).
 .PP
 Sometimes, however, you need to wake up an event loop you do not control,
 for example because it belongs to another thread. This is what \f(CW\*(C`ev_async\*(C'\fR
 kind. There is a \f(CW\*(C`ev_async_set\*(C'\fR macro, but using it is utterly pointless,
 trust me.
 .IP "ev_async_send (loop, ev_async *)" 4
 .IX Item "ev_async_send (loop, ev_async *)"
 Sends/signals/activates the given \f(CW\*(C`ev_async\*(C'\fR watcher, that is, feeds
-an \f(CW\*(C`EV_ASYNC\*(C'\fR event on the watcher into the event loop. Unlike
+an \f(CW\*(C`EV_ASYNC\*(C'\fR event on the watcher into the event loop, and instantly
+returns.
+.Sp
-\&\f(CW\*(C`ev_feed_event\*(C'\fR, this call is safe to do from other threads, signal or
+Unlike \f(CW\*(C`ev_feed_event\*(C'\fR, this call is safe to do from other threads,
-similar contexts (see the discussion of \f(CW\*(C`EV_ATOMIC_T\*(C'\fR in the embedding
+signal or similar contexts (see the discussion of \f(CW\*(C`EV_ATOMIC_T\*(C'\fR in the
-section below on what exactly this means).
+embedding section below on what exactly this means).
 .Sp
 Note that, as with other watchers in libev, multiple events might get
 compressed into a single callback invocation (another way to look at this
 is that \f(CW\*(C`ev_async\*(C'\fR watchers are level-triggered, set on \f(CW\*(C`ev_async_send\*(C'\fR,
 reset when the event loop detects that).
 \&      // now associate this with the loop
 \&      ev_set_userdata (EV_A_ u);
 \&      ev_set_invoke_pending_cb (EV_A_ l_invoke);
 \&      ev_set_loop_release_cb (EV_A_ l_release, l_acquire);
 \&
-\&      // then create the thread running ev_loop
+\&      // then create the thread running ev_run
 \&      pthread_create (&u\->tid, 0, l_run, EV_A);
 \&   }
 .Ve
 .PP
 The callback for the \f(CW\*(C`ev_async\*(C'\fR watcher does nothing: the watcher is used
 A data structure that describes interest in certain events. Watchers need
 to be started (attached to an event loop) before they can receive events.
 .SH "AUTHOR"
 .IX Header "AUTHOR"
 Marc Lehmann <libev@schmorp.de>, with repeated corrections by Mikael
-Magnusson and Emanuele Giaquinta.
+Magnusson and Emanuele Giaquinta, and minor corrections by many others.

Diff Legend

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

Comparing libev/ev.3 (file contents): Revision 1.85 by root, Tue Jan 11 13:45:28 2011 UTC vs. Revision 1.86 by root, Wed Feb 16 08:07:25 2011 UTC

Diff Legend

Comparing libev/ev.3 (file contents):
Revision 1.85 by root, Tue Jan 11 13:45:28 2011 UTC vs.
Revision 1.86 by root, Wed Feb 16 08:07:25 2011 UTC