… | |
… | |
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" |
… | |
… | |
687 | kernel is more efficient (which says nothing about its actual speed, of |
687 | kernel is more efficient (which says nothing about its actual speed, of |
688 | course). While stopping, setting and starting an I/O watcher does never |
688 | course). While stopping, setting and starting an I/O watcher does never |
689 | cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to |
689 | cause an extra system call as with \f(CW\*(C`EVBACKEND_EPOLL\*(C'\fR, it still adds up to |
690 | two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (you |
690 | two event changes per incident. Support for \f(CW\*(C`fork ()\*(C'\fR is very bad (you |
691 | might have to leak fd's on fork, but it's more sane than epoll) and it |
691 | might have to leak fd's on fork, but it's more sane than epoll) and it |
692 | drops fds silently in similarly hard-to-detect cases |
692 | drops fds silently in similarly hard-to-detect cases. |
693 | .Sp |
693 | .Sp |
694 | This backend usually performs well under most conditions. |
694 | This backend usually performs well under most conditions. |
695 | .Sp |
695 | .Sp |
696 | While nominally embeddable in other event loops, this doesn't work |
696 | While nominally embeddable in other event loops, this doesn't work |
697 | everywhere, so you might need to test for this. And since it is broken |
697 | everywhere, so you might need to test for this. And since it is broken |
… | |
… | |
1508 | .IX Subsection "WATCHER STATES" |
1508 | .IX Subsection "WATCHER STATES" |
1509 | There are various watcher states mentioned throughout this manual \- |
1509 | There are various watcher states mentioned throughout this manual \- |
1510 | active, pending and so on. In this section these states and the rules to |
1510 | active, pending and so on. In this section these states and the rules to |
1511 | transition between them will be described in more detail \- and while these |
1511 | transition between them will be described in more detail \- and while these |
1512 | rules might look complicated, they usually do \*(L"the right thing\*(R". |
1512 | rules 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" |
1515 | Before a watcher can be registered with the event loop it has to be |
1515 | Before a watcher can be registered with the event loop it has to be |
1516 | initialised. This can be done with a call to \f(CW\*(C`ev_TYPE_init\*(C'\fR, or calls to |
1516 | initialised. 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 |
1519 | In this state it is simply some block of memory that is suitable for |
1519 | In 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?" |
2743 | This watches a file system path for attribute changes. That is, it calls |
2743 | This 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) |
2745 | and sees if it changed compared to the last time, invoking the callback if |
2745 | and sees if it changed compared to the last time, invoking the callback |
2746 | it did. |
2746 | if it did. Starting the watcher \f(CW\*(C`stat\*(C'\fR's the file, so only changes that |
|
|
2747 | happen after the watcher has been started will be reported. |
2747 | .PP |
2748 | .PP |
2748 | The path does not need to exist: changing from \*(L"path exists\*(R" to \*(L"path does |
2749 | The path does not need to exist: changing from \*(L"path exists\*(R" to \*(L"path does |
2749 | not exist\*(R" is a status change like any other. The condition \*(L"path does not |
2750 | not exist\*(R" is a status change like any other. The condition \*(L"path does not |
2750 | exist\*(R" (or more correctly \*(L"path cannot be stat'ed\*(R") is signified by the |
2751 | exist\*(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 |
3324 | Configures the watcher to embed the given loop, which must be |
3325 | Configures the watcher to embed the given loop, which must be |
3325 | embeddable. If the callback is \f(CW0\fR, then \f(CW\*(C`ev_embed_sweep\*(C'\fR will be |
3326 | embeddable. If the callback is \f(CW0\fR, then \f(CW\*(C`ev_embed_sweep\*(C'\fR will be |
3326 | invoked automatically, otherwise it is the responsibility of the callback |
3327 | invoked automatically, otherwise it is the responsibility of the callback |
3327 | to invoke it (it will continue to be called until the sweep has been done, |
3328 | to invoke it (it will continue to be called until the sweep has been done, |
… | |
… | |
3781 | already been invoked. |
3782 | already been invoked. |
3782 | .PP |
3783 | .PP |
3783 | A common way around all these issues is to make sure that |
3784 | A 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 |
3786 | delay invoking the callback by e.g. using a \f(CW\*(C`prepare\*(C'\fR or \f(CW\*(C`idle\*(C'\fR watcher |
3787 | delay invoking the callback by using a \f(CW\*(C`prepare\*(C'\fR or \f(CW\*(C`idle\*(C'\fR watcher for |
3787 | for example, or more sneakily, by reusing an existing (stopped) watcher |
3788 | example, or more sneakily, by reusing an existing (stopped) watcher and |
3788 | and pushing it into the pending queue: |
3789 | pushing 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 |
3803 | This brings the problem of exiting \- a callback might want to finish the |
3804 | This brings the problem of exiting \- a callback might want to finish the |
3804 | main \f(CW\*(C`ev_run\*(C'\fR call, but not the nested one (e.g. user clicked \*(L"Quit\*(R", but |
3805 | main \f(CW\*(C`ev_run\*(C'\fR call, but not the nested one (e.g. user clicked \*(L"Quit\*(R", but |
3805 | a modal \*(L"Are you sure?\*(R" dialog is still waiting), or just the nested one |
3806 | a modal \*(L"Are you sure?\*(R" dialog is still waiting), or just the nested one |
3806 | and not the main one (e.g. user clocked \*(L"Ok\*(R" in a modal dialog), or some |
3807 | and not the main one (e.g. user clocked \*(L"Ok\*(R" in a modal dialog), or some |
3807 | other combination: In these cases, \f(CW\*(C`ev_break\*(C'\fR will not work alone. |
3808 | other combination: In these cases, a simple \f(CW\*(C`ev_break\*(C'\fR will not work. |
3808 | .PP |
3809 | .PP |
3809 | The solution is to maintain \*(L"break this loop\*(R" variable for each \f(CW\*(C`ev_run\*(C'\fR |
3810 | The solution is to maintain \*(L"break this loop\*(R" variable for each \f(CW\*(C`ev_run\*(C'\fR |
3810 | invocation, and use a loop around \f(CW\*(C`ev_run\*(C'\fR until the condition is |
3811 | invocation, and use a loop around \f(CW\*(C`ev_run\*(C'\fR until the condition is |
3811 | triggered, using \f(CW\*(C`EVRUN_ONCE\*(C'\fR: |
3812 | triggered, using \f(CW\*(C`EVRUN_ONCE\*(C'\fR: |
3812 | .PP |
3813 | .PP |