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.97 by root, Mon Feb 18 03:20:28 2013 UTC

… …
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-02-18" "libev-4.11" "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"
… …
687kernel is more efficient (which says nothing about its actual speed, of 687kernel is more efficient (which says nothing about its actual speed, of
688course). While stopping, setting and starting an I/O watcher does never 688course). 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 689cause 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 690two 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 691might 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 692drops fds silently in similarly hard-to-detect cases.
693.Sp 693.Sp
694This backend usually performs well under most conditions. 694This backend usually performs well under most conditions.
695.Sp 695.Sp
696While nominally embeddable in other event loops, this doesn't work 696While nominally embeddable in other event loops, this doesn't work
697everywhere, so you might need to test for this. And since it is broken 697everywhere, so you might need to test for this. And since it is broken
… …
1508.IX Subsection "WATCHER STATES" 1508.IX Subsection "WATCHER STATES"
1509There are various watcher states mentioned throughout this manual \- 1509There are various watcher states mentioned throughout this manual \-
1510active, pending and so on. In this section these states and the rules to 1510active, 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 1511transition between them will be described in more detail \- and while these
1512rules might look complicated, they usually do \*(L"the right thing\*(R". 1512rules might look complicated, they usually do \*(L"the right thing\*(R".
1513.IP "initialiased" 4 1513.IP "initialised" 4
1514.IX Item "initialiased" 1514.IX Item "initialised"
1515Before a watcher can be registered with the event loop it has to be 1515Before 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 1516initialised. 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. 1517\&\f(CW\*(C`ev_init\*(C'\fR followed by the watcher-specific \f(CW\*(C`ev_TYPE_set\*(C'\fR function.
1518.Sp 1518.Sp
1519In this state it is simply some block of memory that is suitable for 1519In 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?" 2740.ie n .SS """ev_stat"" \- did the file attributes just change?"
2741.el .SS "\f(CWev_stat\fP \- did the file attributes just change?" 2741.el .SS "\f(CWev_stat\fP \- did the file attributes just change?"
2742.IX Subsection "ev_stat - did the file attributes just change?" 2742.IX Subsection "ev_stat - did the file attributes just change?"
2743This watches a file system path for attribute changes. That is, it calls 2743This 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) 2744\&\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 2745and sees if it changed compared to the last time, invoking the callback
2746it did. 2746if it did. Starting the watcher \f(CW\*(C`stat\*(C'\fR's the file, so only changes that
2747happen after the watcher has been started will be reported.
2747.PP 2748.PP
2748The path does not need to exist: changing from \*(L"path exists\*(R" to \*(L"path does 2749The 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 2750not 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 2751exist\*(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 2752\&\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 3317\fIWatcher-Specific Functions and Data Members\fR
3317.IX Subsection "Watcher-Specific Functions and Data Members" 3318.IX Subsection "Watcher-Specific Functions and Data Members"
3318.IP "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)" 4 3319.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)" 3320.IX Item "ev_embed_init (ev_embed *, callback, struct ev_loop *embedded_loop)"
3320.PD 0 3321.PD 0
3321.IP "ev_embed_set (ev_embed *, callback, struct ev_loop *embedded_loop)" 4 3322.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)" 3323.IX Item "ev_embed_set (ev_embed *, struct ev_loop *embedded_loop)"
3323.PD 3324.PD
3324Configures the watcher to embed the given loop, which must be 3325Configures 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 3326embeddable. 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 3327invoked automatically, otherwise it is the responsibility of the callback
3327to invoke it (it will continue to be called until the sweep has been done, 3328to invoke it (it will continue to be called until the sweep has been done,
… …
3781already been invoked. 3782already been invoked.
3782.PP 3783.PP
3783A common way around all these issues is to make sure that 3784A 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 3785\&\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 3786\&\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 3787delay 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 3788example, or more sneakily, by reusing an existing (stopped) watcher and
3788and pushing it into the pending queue: 3789pushing it into the pending queue:
3789.PP 3790.PP
3790.Vb 2 3791.Vb 2
3791\& ev_set_cb (watcher, callback); 3792\& ev_set_cb (watcher, callback);
3792\& ev_feed_event (EV_A_ watcher, 0); 3793\& ev_feed_event (EV_A_ watcher, 0);
3793.Ve 3794.Ve
… …
3802.PP 3803.PP
3803This brings the problem of exiting \- a callback might want to finish the 3804This 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 3805main \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 3806a 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 3807and 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. 3808other combination: In these cases, a simple \f(CW\*(C`ev_break\*(C'\fR will not work.
3808.PP 3809.PP
3809The solution is to maintain \*(L"break this loop\*(R" variable for each \f(CW\*(C`ev_run\*(C'\fR 3810The 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 3811invocation, 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: 3812triggered, using \f(CW\*(C`EVRUN_ONCE\*(C'\fR:
3812.PP 3813.PP

Diff Legend

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