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

Comparing libev/ev.3 (file contents):
Revision 1.94 by root, Sun May 6 19:51:52 2012 UTC vs.
Revision 1.99 by root, Mon Jun 10 00:14:23 2013 UTC

-.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14)
+.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.20)
 .\"
 .\" Standard preamble:
 .\" ========================================================================
 .de Sp \" Vertical space (when we can't use .PP)
 .if t .sp .5v
 .\}
 .rm #[ #] #H #V #F C
 .\" ========================================================================
 .\"
 .IX Title "LIBEV 3"
-.TH LIBEV 3 "2012-05-06" "libev-4.11" "libev - high performance full featured event loop"
+.TH LIBEV 3 "2013-06-07" "libev-4.15" "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"
 .IX Item "EVFLAG_NOENV"
 If this flag bit is or'ed into the flag value (or the program runs setuid
 or setgid) then libev will \fInot\fR look at the environment variable
 \&\f(CW\*(C`LIBEV_FLAGS\*(C'\fR. Otherwise (the default), this environment variable will
 override the flags completely if it is found in the environment. This is
-useful to try out specific backends to test their performance, or to work
+useful to try out specific backends to test their performance, to work
-around bugs.
+around bugs, or to make libev threadsafe (accessing environment variables
+cannot be done in a threadsafe way, but usually it works if no other
+thread modifies them).
 .ie n .IP """EVFLAG_FORKCHECK""" 4
 .el .IP "\f(CWEVFLAG_FORKCHECK\fR" 4
 .IX Item "EVFLAG_FORKCHECK"
 Instead of calling \f(CW\*(C`ev_loop_fork\*(C'\fR manually after a fork, you can also
 make libev check for a fork in each iteration by enabling this flag.
 kernel is more efficient (which says nothing about its actual speed, of
 course). While stopping, setting and starting an I/O watcher does never
 cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to
 two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (you
 might have to leak fd's on fork, but it's more sane than epoll) and it
-drops fds silently in similarly hard-to-detect cases
+drops fds silently in similarly hard-to-detect cases.
 .Sp
 This backend usually performs well under most conditions.
 .Sp
 While nominally embeddable in other event loops, this doesn't work
 everywhere, so you might need to test for this. And since it is broken
 .IX Subsection "WATCHER STATES"
 There are various watcher states mentioned throughout this manual \-
 active, pending and so on. In this section these states and the rules to
 transition between them will be described in more detail \- and while these
 rules might look complicated, they usually do \*(L"the right thing\*(R".
-.IP "initialiased" 4
+.IP "initialised" 4
-.IX Item "initialiased"
+.IX Item "initialised"
 Before a watcher can be registered with the event loop 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
 .ie n .SS """ev_stat"" \- did the file attributes just change?"
 .el .SS "\f(CWev_stat\fP \- did the file attributes just change?"
 .IX Subsection "ev_stat - did the file attributes just change?"
 This watches a file system path for attribute changes. That is, it calls
 \&\f(CW\*(C`stat\*(C'\fR on that path in regular intervals (or when the \s-1OS\s0 says it changed)
-and sees if it changed compared to the last time, invoking the callback if
+and sees if it changed compared to the last time, invoking the callback
-it did.
+if it did. Starting the watcher \f(CW\*(C`stat\*(C'\fR's the file, so only changes that
+happen after the watcher has been started will be reported.
 .PP
 The path does not need to exist: changing from \*(L"path exists\*(R" to \*(L"path does
 not exist\*(R" is a status change like any other. The condition \*(L"path does not
 exist\*(R" (or more correctly \*(L"path cannot be stat'ed\*(R") is signified by the
 \&\f(CW\*(C`st_nlink\*(C'\fR field being zero (which is otherwise always forced to be at
 \fIWatcher-Specific Functions and Data Members\fR
 .IX Subsection "Watcher-Specific Functions and Data Members"
 .IP "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" 4
 .IX Item "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)"
 .PD 0
-.IP "ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)" 4
+.IP "ev_embed_set (ev_embed *, struct ev_loop *embedded_loop)" 4
-.IX Item "ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)"
+.IX Item "ev_embed_set (ev_embed *, struct ev_loop *embedded_loop)"
 .PD
 Configures the watcher to embed the given loop, which must be
 embeddable. If the callback is \f(CW0\fR, then \f(CW\*(C`ev_embed_sweep\*(C'\fR 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,
 .ie n .SS """ev_fork"" \- the audacity to resume the event loop after a fork"
 .el .SS "\f(CWev_fork\fP \- the audacity to resume the event loop after a fork"
 .IX Subsection "ev_fork - the audacity to resume the event loop after a fork"
 Fork watchers are called when a \f(CW\*(C`fork ()\*(C'\fR was detected (usually because
 whoever is a good citizen cared to tell libev about it by calling
-\&\f(CW\*(C`ev_default_fork\*(C'\fR or \f(CW\*(C`ev_loop_fork\*(C'\fR). The invocation is done before the
+\&\f(CW\*(C`ev_loop_fork\*(C'\fR). The invocation is done before the event loop blocks next
-event loop blocks next and before \f(CW\*(C`ev_check\*(C'\fR watchers are being called,
+and before \f(CW\*(C`ev_check\*(C'\fR watchers are being called, and only in the child
-and only in the child after the fork. If whoever good citizen calling
+after the fork. If whoever good citizen calling \f(CW\*(C`ev_default_fork\*(C'\fR cheats
-\&\f(CW\*(C`ev_default_fork\*(C'\fR cheats and calls it in the wrong process, the fork
+and calls it in the wrong process, the fork handlers will be invoked, too,
-handlers will be invoked, too, of course.
+of course.
 .PP
 \fIThe special problem of life after fork \- how is it possible?\fR
 .IX Subsection "The special problem of life after fork - how is it possible?"
 .PP
 Most uses of \f(CW\*(C`fork()\*(C'\fR consist of forking, then some simple calls to set
 already been invoked.
 .PP
 A common way around all these issues is to make sure that
 \&\f(CW\*(C`start_new_request\*(C'\fR \fIalways\fR returns before the callback is invoked. If
 \&\f(CW\*(C`start_new_request\*(C'\fR immediately knows the result, it can artificially
-delay invoking the callback by e.g. using a \f(CW\*(C`prepare\*(C'\fR or \f(CW\*(C`idle\*(C'\fR watcher
+delay invoking the callback by using a \f(CW\*(C`prepare\*(C'\fR or \f(CW\*(C`idle\*(C'\fR watcher for
-for example, or more sneakily, by reusing an existing (stopped) watcher
+example, or more sneakily, by reusing an existing (stopped) watcher and
-and pushing it into the pending queue:
+pushing it into the pending queue:
 .PP
 .Vb 2
 \&   ev_set_cb (watcher, callback);
 \&   ev_feed_event (EV_A_ watcher, 0);
 .Ve
 .PP
 This brings the problem of exiting \- a callback might want to finish the
 main \f(CW\*(C`ev_run\*(C'\fR call, but not the nested one (e.g. user clicked \*(L"Quit\*(R", but
 a modal \*(L"Are you sure?\*(R" dialog is still waiting), or just the nested one
 and not the main one (e.g. user clocked \*(L"Ok\*(R" in a modal dialog), or some
-other combination: In these cases, \f(CW\*(C`ev_break\*(C'\fR will not work alone.
+other combination: In these cases, a simple \f(CW\*(C`ev_break\*(C'\fR will not work.
 .PP
 The solution is to maintain \*(L"break this loop\*(R" variable for each \f(CW\*(C`ev_run\*(C'\fR
 invocation, and use a loop around \f(CW\*(C`ev_run\*(C'\fR until the condition is
 triggered, using \f(CW\*(C`EVRUN_ONCE\*(C'\fR:
 .PP
 libev sources can be compiled as \*(C+. Therefore, code that uses the C \s-1API\s0
 will work fine.
 .PP
 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 \f(CW\*(C`throw
 ()\*(C'\fR specification. If you have code that needs to be compiled as both C
 and \*(C+ you can use the \f(CW\*(C`EV_THROW\*(C'\fR macro for this:
 .PP
 .Vb 6
 .IX Item "w->set (loop)"
 Associates a different \f(CW\*(C`struct ev_loop\*(C'\fR with this watcher. You can only
 do this when the watcher is inactive (and not pending either).
 .IP "w\->set ([arguments])" 4
 .IX Item "w->set ([arguments])"
-Basically the same as \f(CW\*(C`ev_TYPE_set\*(C'\fR, with the same arguments. Either this
+Basically the same as \f(CW\*(C`ev_TYPE_set\*(C'\fR (except for \f(CW\*(C`ev::embed\*(C'\fR 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.
+.Sp
+For \f(CW\*(C`ev::embed\*(C'\fR watchers this method is called \f(CW\*(C`set_embed\*(C'\fR, to avoid
+clashing with the \f(CW\*(C`set (loop)\*(C'\fR method.
 .IP "w\->start ()" 4
 .IX Item "w->start ()"
 Starts the watcher. Note that there is no \f(CW\*(C`loop\*(C'\fR argument, as the
 constructor already stores the event loop.
 .IP "w\->start ([arguments])" 4
 .IP "\s-1EV_USE_WSASOCKET\s0" 4
 .IX Item "EV_USE_WSASOCKET"
 If defined to be \f(CW1\fR, libev will use \f(CW\*(C`WSASocket\*(C'\fR to create its internal
 communication socket, which works better in some environments. Otherwise,
 the normal \f(CW\*(C`socket\*(C'\fR function will be used, which works better in other
-enviornments.
+environments.
 .IP "\s-1EV_USE_POLL\s0" 4
 .IX Item "EV_USE_POLL"
 If defined to be \f(CW1\fR, libev will compile in support for the \f(CW\*(C`poll\*(C'\fR(2)
 backend. Otherwise it will be enabled on non\-win32 platforms. It
 takes precedence over select.
 between threads, that is, threads can be used, but threads never run on
 different cpus (or different cpu cores). This reduces dependencies
 and makes libev faster.
 .IP "\s-1EV_NO_THREADS\s0" 4
 .IX Item "EV_NO_THREADS"
-If defined to be \f(CW1\fR, libev will assume that it will never be called
+If defined to be \f(CW1\fR, libev will assume that it will never be called from
-from different threads, which is a stronger assumption than \f(CW\*(C`EV_NO_SMP\*(C'\fR,
+different threads (that includes signal handlers), which is a stronger
-above. This reduces dependencies and makes libev faster.
+assumption than \f(CW\*(C`EV_NO_SMP\*(C'\fR, above. This reduces dependencies and makes
+libev faster.
 .IP "\s-1EV_ATOMIC_T\s0" 4
 .IX Item "EV_ATOMIC_T"
 Libev requires an integer type (suitable for storing \f(CW0\fR or \f(CW1\fR) whose
-access is atomic and serialised with respect to other threads or signal
+access is atomic with respect to other threads or signal contexts. No
-contexts. No such type is easily found in the C language, so you can
+such type is easily found in the C language, so you can provide your own
-provide your own type that you know is safe for your purposes. It is used
+type that you know is safe for your purposes. It is used both for signal
-both for signal handler \*(L"locking\*(R" as well as for signal and thread safety
+handler \*(L"locking\*(R" as well as for signal and thread safety in \f(CW\*(C`ev_async\*(C'\fR
-in \f(CW\*(C`ev_async\*(C'\fR watchers.
+watchers.
 .Sp
 In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR
-(from \fIsignal.h\fR), which is usually good enough on most platforms,
+(from \fIsignal.h\fR), which is usually good enough on most platforms.
-although strictly speaking using a type that also implies a memory fence
-is required.
 .IP "\s-1EV_H\s0 (h)" 4
 .IX Item "EV_H (h)"
 The name of the \fIev.h\fR header file used to include it. The default if
 undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be
 used to virtually rename the \fIev.h\fR header file in case of conflicts.
 thread\*(R" or will block signals process-wide, both behaviours would
 be compatible with libev. Interaction between \f(CW\*(C`sigprocmask\*(C'\fR and
 \&\f(CW\*(C`pthread_sigmask\*(C'\fR could complicate things, however.
 .Sp
 The most portable way to handle signals is to block signals in all threads
-except the initial one, and run the default loop in the initial thread as
+except the initial one, and run the signal handling loop in the initial
-well.
+thread as well.
 .ie n .IP """long"" must be large enough for common memory allocation sizes" 4
 .el .IP "\f(CWlong\fR must be large enough for common memory allocation sizes" 4
 .IX Item "long must be large enough for common memory allocation sizes"
 To improve portability and simplify its \s-1API\s0, libev uses \f(CW\*(C`long\*(C'\fR internally
 instead of \f(CW\*(C`size_t\*(C'\fR when allocating its data structures. On non-POSIX

Diff Legend

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

Comparing libev/ev.3 (file contents): Revision 1.94 by root, Sun May 6 19:51:52 2012 UTC vs. Revision 1.99 by root, Mon Jun 10 00:14:23 2013 UTC

Diff Legend

Comparing libev/ev.3 (file contents):
Revision 1.94 by root, Sun May 6 19:51:52 2012 UTC vs.
Revision 1.99 by root, Mon Jun 10 00:14:23 2013 UTC