1 | .\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14) |
1 | .\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) |
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-05-06" "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, |
… | |
… | |
3390 | .ie n .SS """ev_fork"" \- the audacity to resume the event loop after a fork" |
3391 | .ie n .SS """ev_fork"" \- the audacity to resume the event loop after a fork" |
3391 | .el .SS "\f(CWev_fork\fP \- the audacity to resume the event loop after a fork" |
3392 | .el .SS "\f(CWev_fork\fP \- the audacity to resume the event loop after a fork" |
3392 | .IX Subsection "ev_fork - the audacity to resume the event loop after a fork" |
3393 | .IX Subsection "ev_fork - the audacity to resume the event loop after a fork" |
3393 | Fork watchers are called when a \f(CW\*(C`fork ()\*(C'\fR was detected (usually because |
3394 | Fork watchers are called when a \f(CW\*(C`fork ()\*(C'\fR was detected (usually because |
3394 | whoever is a good citizen cared to tell libev about it by calling |
3395 | whoever is a good citizen cared to tell libev about it by calling |
3395 | \&\f(CW\*(C`ev_default_fork\*(C'\fR or \f(CW\*(C`ev_loop_fork\*(C'\fR). The invocation is done before the |
3396 | \&\f(CW\*(C`ev_loop_fork\*(C'\fR). The invocation is done before the event loop blocks next |
3396 | event loop blocks next and before \f(CW\*(C`ev_check\*(C'\fR watchers are being called, |
3397 | and before \f(CW\*(C`ev_check\*(C'\fR watchers are being called, and only in the child |
3397 | and only in the child after the fork. If whoever good citizen calling |
3398 | after the fork. If whoever good citizen calling \f(CW\*(C`ev_default_fork\*(C'\fR cheats |
3398 | \&\f(CW\*(C`ev_default_fork\*(C'\fR cheats and calls it in the wrong process, the fork |
3399 | and calls it in the wrong process, the fork handlers will be invoked, too, |
3399 | handlers will be invoked, too, of course. |
3400 | of course. |
3400 | .PP |
3401 | .PP |
3401 | \fIThe special problem of life after fork \- how is it possible?\fR |
3402 | \fIThe special problem of life after fork \- how is it possible?\fR |
3402 | .IX Subsection "The special problem of life after fork - how is it possible?" |
3403 | .IX Subsection "The special problem of life after fork - how is it possible?" |
3403 | .PP |
3404 | .PP |
3404 | Most uses of \f(CW\*(C`fork()\*(C'\fR consist of forking, then some simple calls to set |
3405 | Most uses of \f(CW\*(C`fork()\*(C'\fR consist of forking, then some simple calls to set |
… | |
… | |
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 |
… | |
… | |
4088 | libev sources can be compiled as \*(C+. Therefore, code that uses the C \s-1API\s0 |
4089 | libev sources can be compiled as \*(C+. Therefore, code that uses the C \s-1API\s0 |
4089 | will work fine. |
4090 | will work fine. |
4090 | .PP |
4091 | .PP |
4091 | Proper exception specifications might have to be added to callbacks passed |
4092 | Proper exception specifications might have to be added to callbacks passed |
4092 | to libev: exceptions may be thrown only from watcher callbacks, all |
4093 | to libev: exceptions may be thrown only from watcher callbacks, all |
4093 | other callbacks (allocator, syserr, loop acquire/release and periodioc |
4094 | other callbacks (allocator, syserr, loop acquire/release and periodic |
4094 | reschedule callbacks) must not throw exceptions, and might need a \f(CW\*(C`throw |
4095 | reschedule callbacks) must not throw exceptions, and might need a \f(CW\*(C`throw |
4095 | ()\*(C'\fR specification. If you have code that needs to be compiled as both C |
4096 | ()\*(C'\fR specification. If you have code that needs to be compiled as both C |
4096 | and \*(C+ you can use the \f(CW\*(C`EV_THROW\*(C'\fR macro for this: |
4097 | and \*(C+ you can use the \f(CW\*(C`EV_THROW\*(C'\fR macro for this: |
4097 | .PP |
4098 | .PP |
4098 | .Vb 6 |
4099 | .Vb 6 |
… | |
… | |
4261 | .IX Item "w->set (loop)" |
4262 | .IX Item "w->set (loop)" |
4262 | Associates a different \f(CW\*(C`struct ev_loop\*(C'\fR with this watcher. You can only |
4263 | Associates a different \f(CW\*(C`struct ev_loop\*(C'\fR with this watcher. You can only |
4263 | do this when the watcher is inactive (and not pending either). |
4264 | do this when the watcher is inactive (and not pending either). |
4264 | .IP "w\->set ([arguments])" 4 |
4265 | .IP "w\->set ([arguments])" 4 |
4265 | .IX Item "w->set ([arguments])" |
4266 | .IX Item "w->set ([arguments])" |
4266 | Basically the same as \f(CW\*(C`ev_TYPE_set\*(C'\fR, with the same arguments. Either this |
4267 | Basically the same as \f(CW\*(C`ev_TYPE_set\*(C'\fR (except for \f(CW\*(C`ev::embed\*(C'\fR watchers>), |
4267 | method or a suitable start method must be called at least once. Unlike the |
4268 | with the same arguments. Either this method or a suitable start method |
4268 | C counterpart, an active watcher gets automatically stopped and restarted |
4269 | must be called at least once. Unlike the C counterpart, an active watcher |
4269 | when reconfiguring it with this method. |
4270 | gets automatically stopped and restarted when reconfiguring it with this |
|
|
4271 | method. |
|
|
4272 | .Sp |
|
|
4273 | For \f(CW\*(C`ev::embed\*(C'\fR watchers this method is called \f(CW\*(C`set_embed\*(C'\fR, to avoid |
|
|
4274 | clashing with the \f(CW\*(C`set (loop)\*(C'\fR method. |
4270 | .IP "w\->start ()" 4 |
4275 | .IP "w\->start ()" 4 |
4271 | .IX Item "w->start ()" |
4276 | .IX Item "w->start ()" |
4272 | Starts the watcher. Note that there is no \f(CW\*(C`loop\*(C'\fR argument, as the |
4277 | Starts the watcher. Note that there is no \f(CW\*(C`loop\*(C'\fR argument, as the |
4273 | constructor already stores the event loop. |
4278 | constructor already stores the event loop. |
4274 | .IP "w\->start ([arguments])" 4 |
4279 | .IP "w\->start ([arguments])" 4 |
… | |
… | |
4679 | .IP "\s-1EV_USE_WSASOCKET\s0" 4 |
4684 | .IP "\s-1EV_USE_WSASOCKET\s0" 4 |
4680 | .IX Item "EV_USE_WSASOCKET" |
4685 | .IX Item "EV_USE_WSASOCKET" |
4681 | If defined to be \f(CW1\fR, libev will use \f(CW\*(C`WSASocket\*(C'\fR to create its internal |
4686 | If defined to be \f(CW1\fR, libev will use \f(CW\*(C`WSASocket\*(C'\fR to create its internal |
4682 | communication socket, which works better in some environments. Otherwise, |
4687 | communication socket, which works better in some environments. Otherwise, |
4683 | the normal \f(CW\*(C`socket\*(C'\fR function will be used, which works better in other |
4688 | the normal \f(CW\*(C`socket\*(C'\fR function will be used, which works better in other |
4684 | enviornments. |
4689 | environments. |
4685 | .IP "\s-1EV_USE_POLL\s0" 4 |
4690 | .IP "\s-1EV_USE_POLL\s0" 4 |
4686 | .IX Item "EV_USE_POLL" |
4691 | .IX Item "EV_USE_POLL" |
4687 | If defined to be \f(CW1\fR, libev will compile in support for the \f(CW\*(C`poll\*(C'\fR(2) |
4692 | If defined to be \f(CW1\fR, libev will compile in support for the \f(CW\*(C`poll\*(C'\fR(2) |
4688 | backend. Otherwise it will be enabled on non\-win32 platforms. It |
4693 | backend. Otherwise it will be enabled on non\-win32 platforms. It |
4689 | takes precedence over select. |
4694 | takes precedence over select. |
… | |
… | |
4732 | from different threads, which is a stronger assumption than \f(CW\*(C`EV_NO_SMP\*(C'\fR, |
4737 | from different threads, which is a stronger assumption than \f(CW\*(C`EV_NO_SMP\*(C'\fR, |
4733 | above. This reduces dependencies and makes libev faster. |
4738 | above. This reduces dependencies and makes libev faster. |
4734 | .IP "\s-1EV_ATOMIC_T\s0" 4 |
4739 | .IP "\s-1EV_ATOMIC_T\s0" 4 |
4735 | .IX Item "EV_ATOMIC_T" |
4740 | .IX Item "EV_ATOMIC_T" |
4736 | Libev requires an integer type (suitable for storing \f(CW0\fR or \f(CW1\fR) whose |
4741 | Libev requires an integer type (suitable for storing \f(CW0\fR or \f(CW1\fR) whose |
4737 | access is atomic and serialised with respect to other threads or signal |
4742 | access is atomic with respect to other threads or signal contexts. No |
4738 | contexts. No such type is easily found in the C language, so you can |
4743 | such type is easily found in the C language, so you can provide your own |
4739 | provide your own type that you know is safe for your purposes. It is used |
4744 | type that you know is safe for your purposes. It is used both for signal |
4740 | both for signal handler \*(L"locking\*(R" as well as for signal and thread safety |
4745 | handler \*(L"locking\*(R" as well as for signal and thread safety in \f(CW\*(C`ev_async\*(C'\fR |
4741 | in \f(CW\*(C`ev_async\*(C'\fR watchers. |
4746 | watchers. |
4742 | .Sp |
4747 | .Sp |
4743 | In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR |
4748 | In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR |
4744 | (from \fIsignal.h\fR), which is usually good enough on most platforms, |
4749 | (from \fIsignal.h\fR), which is usually good enough on most platforms. |
4745 | although strictly speaking using a type that also implies a memory fence |
|
|
4746 | is required. |
|
|
4747 | .IP "\s-1EV_H\s0 (h)" 4 |
4750 | .IP "\s-1EV_H\s0 (h)" 4 |
4748 | .IX Item "EV_H (h)" |
4751 | .IX Item "EV_H (h)" |
4749 | The name of the \fIev.h\fR header file used to include it. The default if |
4752 | The name of the \fIev.h\fR header file used to include it. The default if |
4750 | undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be |
4753 | undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be |
4751 | used to virtually rename the \fIev.h\fR header file in case of conflicts. |
4754 | used to virtually rename the \fIev.h\fR header file in case of conflicts. |
… | |
… | |
5413 | thread\*(R" or will block signals process-wide, both behaviours would |
5416 | thread\*(R" or will block signals process-wide, both behaviours would |
5414 | be compatible with libev. Interaction between \f(CW\*(C`sigprocmask\*(C'\fR and |
5417 | be compatible with libev. Interaction between \f(CW\*(C`sigprocmask\*(C'\fR and |
5415 | \&\f(CW\*(C`pthread_sigmask\*(C'\fR could complicate things, however. |
5418 | \&\f(CW\*(C`pthread_sigmask\*(C'\fR could complicate things, however. |
5416 | .Sp |
5419 | .Sp |
5417 | The most portable way to handle signals is to block signals in all threads |
5420 | The most portable way to handle signals is to block signals in all threads |
5418 | except the initial one, and run the default loop in the initial thread as |
5421 | except the initial one, and run the signal handling loop in the initial |
5419 | well. |
5422 | thread as well. |
5420 | .ie n .IP """long"" must be large enough for common memory allocation sizes" 4 |
5423 | .ie n .IP """long"" must be large enough for common memory allocation sizes" 4 |
5421 | .el .IP "\f(CWlong\fR must be large enough for common memory allocation sizes" 4 |
5424 | .el .IP "\f(CWlong\fR must be large enough for common memory allocation sizes" 4 |
5422 | .IX Item "long must be large enough for common memory allocation sizes" |
5425 | .IX Item "long must be large enough for common memory allocation sizes" |
5423 | To improve portability and simplify its \s-1API\s0, libev uses \f(CW\*(C`long\*(C'\fR internally |
5426 | To improve portability and simplify its \s-1API\s0, libev uses \f(CW\*(C`long\*(C'\fR internally |
5424 | instead of \f(CW\*(C`size_t\*(C'\fR when allocating its data structures. On non-POSIX |
5427 | instead of \f(CW\*(C`size_t\*(C'\fR when allocating its data structures. On non-POSIX |