ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libev/ev.3
(Generate patch)

Comparing libev/ev.3 (file contents):
Revision 1.96 by root, Thu Nov 15 01:39:45 2012 UTC vs.
Revision 1.99 by root, Mon Jun 10 00:14:23 2013 UTC

1.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) 1.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.20)
2.\" 2.\"
3.\" Standard preamble: 3.\" Standard preamble:
4.\" ======================================================================== 4.\" ========================================================================
5.de Sp \" Vertical space (when we can't use .PP) 5.de Sp \" Vertical space (when we can't use .PP)
6.if t .sp .5v 6.if t .sp .5v
… …
122.\} 122.\}
123.rm #[ #] #H #V #F C 123.rm #[ #] #H #V #F C
124.\" ======================================================================== 124.\" ========================================================================
125.\" 125.\"
126.IX Title "LIBEV 3" 126.IX Title "LIBEV 3"
127.TH LIBEV 3 "2012-11-13" "libev-4.11" "libev - high performance full featured event loop" 127.TH LIBEV 3 "2013-06-07" "libev-4.15" "libev - high performance full featured event loop"
128.\" For nroff, turn off justification. Always turn off hyphenation; it makes 128.\" For nroff, turn off justification. Always turn off hyphenation; it makes
129.\" way too many mistakes in technical documents. 129.\" way too many mistakes in technical documents.
130.if n .ad l 130.if n .ad l
131.nh 131.nh
132.SH "NAME" 132.SH "NAME"
… …
514.IX Item "EVFLAG_NOENV" 514.IX Item "EVFLAG_NOENV"
515If this flag bit is or'ed into the flag value (or the program runs setuid 515If this flag bit is or'ed into the flag value (or the program runs setuid
516or setgid) then libev will \fInot\fR look at the environment variable 516or setgid) then libev will \fInot\fR look at the environment variable
517\&\f(CW\*(C`LIBEV_FLAGS\*(C'\fR. Otherwise (the default), this environment variable will 517\&\f(CW\*(C`LIBEV_FLAGS\*(C'\fR. Otherwise (the default), this environment variable will
518override the flags completely if it is found in the environment. This is 518override the flags completely if it is found in the environment. This is
519useful to try out specific backends to test their performance, or to work 519useful to try out specific backends to test their performance, to work
520around bugs. 520around bugs, or to make libev threadsafe (accessing environment variables
521cannot be done in a threadsafe way, but usually it works if no other
522thread modifies them).
521.ie n .IP """EVFLAG_FORKCHECK""" 4 523.ie n .IP """EVFLAG_FORKCHECK""" 4
522.el .IP "\f(CWEVFLAG_FORKCHECK\fR" 4 524.el .IP "\f(CWEVFLAG_FORKCHECK\fR" 4
523.IX Item "EVFLAG_FORKCHECK" 525.IX Item "EVFLAG_FORKCHECK"
524Instead of calling \f(CW\*(C`ev_loop_fork\*(C'\fR manually after a fork, you can also 526Instead of calling \f(CW\*(C`ev_loop_fork\*(C'\fR manually after a fork, you can also
525make libev check for a fork in each iteration by enabling this flag. 527make libev check for a fork in each iteration by enabling this flag.
… …
687kernel is more efficient (which says nothing about its actual speed, of 689kernel is more efficient (which says nothing about its actual speed, of
688course). While stopping, setting and starting an I/O watcher does never 690course). While stopping, setting and starting an I/O watcher does never
689cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to 691cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to
690two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (you 692two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (you
691might have to leak fd's on fork, but it's more sane than epoll) and it 693might have to leak fd's on fork, but it's more sane than epoll) and it
692drops fds silently in similarly hard-to-detect cases 694drops fds silently in similarly hard-to-detect cases.
693.Sp 695.Sp
694This backend usually performs well under most conditions. 696This backend usually performs well under most conditions.
695.Sp 697.Sp
696While nominally embeddable in other event loops, this doesn't work 698While nominally embeddable in other event loops, this doesn't work
697everywhere, so you might need to test for this. And since it is broken 699everywhere, so you might need to test for this. And since it is broken
… …
1508.IX Subsection "WATCHER STATES" 1510.IX Subsection "WATCHER STATES"
1509There are various watcher states mentioned throughout this manual \- 1511There are various watcher states mentioned throughout this manual \-
1510active, pending and so on. In this section these states and the rules to 1512active, pending and so on. In this section these states and the rules to
1511transition between them will be described in more detail \- and while these 1513transition between them will be described in more detail \- and while these
1512rules might look complicated, they usually do \*(L"the right thing\*(R". 1514rules might look complicated, they usually do \*(L"the right thing\*(R".
1513.IP "initialiased" 4 1515.IP "initialised" 4
1514.IX Item "initialiased" 1516.IX Item "initialised"
1515Before a watcher can be registered with the event loop it has to be 1517Before a watcher can be registered with the event loop it has to be
1516initialised. This can be done with a call to \f(CW\*(C`ev_TYPE_init\*(C'\fR, or calls to 1518initialised. This can be done with a call to \f(CW\*(C`ev_TYPE_init\*(C'\fR, or calls to
1517\&\f(CW\*(C`ev_init\*(C'\fR followed by the watcher-specific \f(CW\*(C`ev_TYPE_set\*(C'\fR function. 1519\&\f(CW\*(C`ev_init\*(C'\fR followed by the watcher-specific \f(CW\*(C`ev_TYPE_set\*(C'\fR function.
1518.Sp 1520.Sp
1519In this state it is simply some block of memory that is suitable for 1521In this state it is simply some block of memory that is suitable for
… …
2740.ie n .SS """ev_stat"" \- did the file attributes just change?" 2742.ie n .SS """ev_stat"" \- did the file attributes just change?"
2741.el .SS "\f(CWev_stat\fP \- did the file attributes just change?" 2743.el .SS "\f(CWev_stat\fP \- did the file attributes just change?"
2742.IX Subsection "ev_stat - did the file attributes just change?" 2744.IX Subsection "ev_stat - did the file attributes just change?"
2743This watches a file system path for attribute changes. That is, it calls 2745This watches a file system path for attribute changes. That is, it calls
2744\&\f(CW\*(C`stat\*(C'\fR on that path in regular intervals (or when the \s-1OS\s0 says it changed) 2746\&\f(CW\*(C`stat\*(C'\fR on that path in regular intervals (or when the \s-1OS\s0 says it changed)
2745and sees if it changed compared to the last time, invoking the callback if 2747and sees if it changed compared to the last time, invoking the callback
2746it did. 2748if it did. Starting the watcher \f(CW\*(C`stat\*(C'\fR's the file, so only changes that
2749happen after the watcher has been started will be reported.
2747.PP 2750.PP
2748The path does not need to exist: changing from \*(L"path exists\*(R" to \*(L"path does 2751The path does not need to exist: changing from \*(L"path exists\*(R" to \*(L"path does
2749not exist\*(R" is a status change like any other. The condition \*(L"path does not 2752not exist\*(R" is a status change like any other. The condition \*(L"path does not
2750exist\*(R" (or more correctly \*(L"path cannot be stat'ed\*(R") is signified by the 2753exist\*(R" (or more correctly \*(L"path cannot be stat'ed\*(R") is signified by the
2751\&\f(CW\*(C`st_nlink\*(C'\fR field being zero (which is otherwise always forced to be at 2754\&\f(CW\*(C`st_nlink\*(C'\fR field being zero (which is otherwise always forced to be at
… …
3316\fIWatcher-Specific Functions and Data Members\fR 3319\fIWatcher-Specific Functions and Data Members\fR
3317.IX Subsection "Watcher-Specific Functions and Data Members" 3320.IX Subsection "Watcher-Specific Functions and Data Members"
3318.IP "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" 4 3321.IP "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" 4
3319.IX Item "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" 3322.IX Item "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)"
3320.PD 0 3323.PD 0
3321.IP "ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)" 4 3324.IP "ev_embed_set (ev_embed *, struct ev_loop *embedded_loop)" 4
3322.IX Item "ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)" 3325.IX Item "ev_embed_set (ev_embed *, struct ev_loop *embedded_loop)"
3323.PD 3326.PD
3324Configures the watcher to embed the given loop, which must be 3327Configures the watcher to embed the given loop, which must be
3325embeddable. If the callback is \f(CW0\fR, then \f(CW\*(C`ev_embed_sweep\*(C'\fR will be 3328embeddable. If the callback is \f(CW0\fR, then \f(CW\*(C`ev_embed_sweep\*(C'\fR will be
3326invoked automatically, otherwise it is the responsibility of the callback 3329invoked automatically, otherwise it is the responsibility of the callback
3327to invoke it (it will continue to be called until the sweep has been done, 3330to invoke it (it will continue to be called until the sweep has been done,
… …
3781already been invoked. 3784already been invoked.
3782.PP 3785.PP
3783A common way around all these issues is to make sure that 3786A common way around all these issues is to make sure that
3784\&\f(CW\*(C`start_new_request\*(C'\fR \fIalways\fR returns before the callback is invoked. If 3787\&\f(CW\*(C`start_new_request\*(C'\fR \fIalways\fR returns before the callback is invoked. If
3785\&\f(CW\*(C`start_new_request\*(C'\fR immediately knows the result, it can artificially 3788\&\f(CW\*(C`start_new_request\*(C'\fR immediately knows the result, it can artificially
3786delay invoking the callback by e.g. using a \f(CW\*(C`prepare\*(C'\fR or \f(CW\*(C`idle\*(C'\fR watcher 3789delay invoking the callback by using a \f(CW\*(C`prepare\*(C'\fR or \f(CW\*(C`idle\*(C'\fR watcher for
3787for example, or more sneakily, by reusing an existing (stopped) watcher 3790example, or more sneakily, by reusing an existing (stopped) watcher and
3788and pushing it into the pending queue: 3791pushing it into the pending queue:
3789.PP 3792.PP
3790.Vb 2 3793.Vb 2
3791\& ev_set_cb (watcher, callback); 3794\& ev_set_cb (watcher, callback);
3792\& ev_feed_event (EV_A_ watcher, 0); 3795\& ev_feed_event (EV_A_ watcher, 0);
3793.Ve 3796.Ve
… …
3802.PP 3805.PP
3803This brings the problem of exiting \- a callback might want to finish the 3806This brings the problem of exiting \- a callback might want to finish the
3804main \f(CW\*(C`ev_run\*(C'\fR call, but not the nested one (e.g. user clicked \*(L"Quit\*(R", but 3807main \f(CW\*(C`ev_run\*(C'\fR call, but not the nested one (e.g. user clicked \*(L"Quit\*(R", but
3805a modal \*(L"Are you sure?\*(R" dialog is still waiting), or just the nested one 3808a modal \*(L"Are you sure?\*(R" dialog is still waiting), or just the nested one
3806and not the main one (e.g. user clocked \*(L"Ok\*(R" in a modal dialog), or some 3809and not the main one (e.g. user clocked \*(L"Ok\*(R" in a modal dialog), or some
3807other combination: In these cases, \f(CW\*(C`ev_break\*(C'\fR will not work alone. 3810other combination: In these cases, a simple \f(CW\*(C`ev_break\*(C'\fR will not work.
3808.PP 3811.PP
3809The solution is to maintain \*(L"break this loop\*(R" variable for each \f(CW\*(C`ev_run\*(C'\fR 3812The solution is to maintain \*(L"break this loop\*(R" variable for each \f(CW\*(C`ev_run\*(C'\fR
3810invocation, and use a loop around \f(CW\*(C`ev_run\*(C'\fR until the condition is 3813invocation, and use a loop around \f(CW\*(C`ev_run\*(C'\fR until the condition is
3811triggered, using \f(CW\*(C`EVRUN_ONCE\*(C'\fR: 3814triggered, using \f(CW\*(C`EVRUN_ONCE\*(C'\fR:
3812.PP 3815.PP
… …
4730between threads, that is, threads can be used, but threads never run on 4733between threads, that is, threads can be used, but threads never run on
4731different cpus (or different cpu cores). This reduces dependencies 4734different cpus (or different cpu cores). This reduces dependencies
4732and makes libev faster. 4735and makes libev faster.
4733.IP "\s-1EV_NO_THREADS\s0" 4 4736.IP "\s-1EV_NO_THREADS\s0" 4
4734.IX Item "EV_NO_THREADS" 4737.IX Item "EV_NO_THREADS"
4735If defined to be \f(CW1\fR, libev will assume that it will never be called 4738If defined to be \f(CW1\fR, libev will assume that it will never be called from
4736from different threads, which is a stronger assumption than \f(CW\*(C`EV_NO_SMP\*(C'\fR, 4739different threads (that includes signal handlers), which is a stronger
4737above. This reduces dependencies and makes libev faster. 4740assumption than \f(CW\*(C`EV_NO_SMP\*(C'\fR, above. This reduces dependencies and makes
4741libev faster.
4738.IP "\s-1EV_ATOMIC_T\s0" 4 4742.IP "\s-1EV_ATOMIC_T\s0" 4
4739.IX Item "EV_ATOMIC_T" 4743.IX Item "EV_ATOMIC_T"
4740Libev requires an integer type (suitable for storing \f(CW0\fR or \f(CW1\fR) whose 4744Libev requires an integer type (suitable for storing \f(CW0\fR or \f(CW1\fR) whose
4741access is atomic with respect to other threads or signal contexts. No 4745access is atomic with respect to other threads or signal contexts. No
4742such type is easily found in the C language, so you can provide your own 4746such type is easily found in the C language, so you can provide your own

Diff Legend

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