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 "2012-11-13" "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" |
… | |
… | |
3390 | .ie n .SS """ev_fork"" \- the audacity to resume the event loop after a fork" |
3390 | .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" |
3391 | .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" |
3392 | .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 |
3393 | 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 |
3394 | 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 |
3395 | \&\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, |
3396 | 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 |
3397 | 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 |
3398 | and calls it in the wrong process, the fork handlers will be invoked, too, |
3399 | handlers will be invoked, too, of course. |
3399 | of course. |
3400 | .PP |
3400 | .PP |
3401 | \fIThe special problem of life after fork \- how is it possible?\fR |
3401 | \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?" |
3402 | .IX Subsection "The special problem of life after fork - how is it possible?" |
3403 | .PP |
3403 | .PP |
3404 | Most uses of \f(CW\*(C`fork()\*(C'\fR consist of forking, then some simple calls to set |
3404 | Most uses of \f(CW\*(C`fork()\*(C'\fR consist of forking, then some simple calls to set |
… | |
… | |
4088 | libev sources can be compiled as \*(C+. Therefore, code that uses the C \s-1API\s0 |
4088 | libev sources can be compiled as \*(C+. Therefore, code that uses the C \s-1API\s0 |
4089 | will work fine. |
4089 | will work fine. |
4090 | .PP |
4090 | .PP |
4091 | Proper exception specifications might have to be added to callbacks passed |
4091 | Proper exception specifications might have to be added to callbacks passed |
4092 | to libev: exceptions may be thrown only from watcher callbacks, all |
4092 | to libev: exceptions may be thrown only from watcher callbacks, all |
4093 | other callbacks (allocator, syserr, loop acquire/release and periodioc |
4093 | other callbacks (allocator, syserr, loop acquire/release and periodic |
4094 | reschedule callbacks) must not throw exceptions, and might need a \f(CW\*(C`throw |
4094 | 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 |
4095 | ()\*(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: |
4096 | and \*(C+ you can use the \f(CW\*(C`EV_THROW\*(C'\fR macro for this: |
4097 | .PP |
4097 | .PP |
4098 | .Vb 6 |
4098 | .Vb 6 |
… | |
… | |
4261 | .IX Item "w->set (loop)" |
4261 | .IX Item "w->set (loop)" |
4262 | Associates a different \f(CW\*(C`struct ev_loop\*(C'\fR with this watcher. You can only |
4262 | 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). |
4263 | do this when the watcher is inactive (and not pending either). |
4264 | .IP "w\->set ([arguments])" 4 |
4264 | .IP "w\->set ([arguments])" 4 |
4265 | .IX Item "w->set ([arguments])" |
4265 | .IX Item "w->set ([arguments])" |
4266 | Basically the same as \f(CW\*(C`ev_TYPE_set\*(C'\fR, with the same arguments. Either this |
4266 | 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 |
4267 | with the same arguments. Either this method or a suitable start method |
4268 | C counterpart, an active watcher gets automatically stopped and restarted |
4268 | must be called at least once. Unlike the C counterpart, an active watcher |
4269 | when reconfiguring it with this method. |
4269 | gets automatically stopped and restarted when reconfiguring it with this |
|
|
4270 | method. |
|
|
4271 | .Sp |
|
|
4272 | For \f(CW\*(C`ev::embed\*(C'\fR watchers this method is called \f(CW\*(C`set_embed\*(C'\fR, to avoid |
|
|
4273 | clashing with the \f(CW\*(C`set (loop)\*(C'\fR method. |
4270 | .IP "w\->start ()" 4 |
4274 | .IP "w\->start ()" 4 |
4271 | .IX Item "w->start ()" |
4275 | .IX Item "w->start ()" |
4272 | Starts the watcher. Note that there is no \f(CW\*(C`loop\*(C'\fR argument, as the |
4276 | Starts the watcher. Note that there is no \f(CW\*(C`loop\*(C'\fR argument, as the |
4273 | constructor already stores the event loop. |
4277 | constructor already stores the event loop. |
4274 | .IP "w\->start ([arguments])" 4 |
4278 | .IP "w\->start ([arguments])" 4 |
… | |
… | |
4679 | .IP "\s-1EV_USE_WSASOCKET\s0" 4 |
4683 | .IP "\s-1EV_USE_WSASOCKET\s0" 4 |
4680 | .IX Item "EV_USE_WSASOCKET" |
4684 | .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 |
4685 | 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, |
4686 | 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 |
4687 | the normal \f(CW\*(C`socket\*(C'\fR function will be used, which works better in other |
4684 | enviornments. |
4688 | environments. |
4685 | .IP "\s-1EV_USE_POLL\s0" 4 |
4689 | .IP "\s-1EV_USE_POLL\s0" 4 |
4686 | .IX Item "EV_USE_POLL" |
4690 | .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) |
4691 | 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 |
4692 | backend. Otherwise it will be enabled on non\-win32 platforms. It |
4689 | takes precedence over select. |
4693 | takes precedence over select. |
… | |
… | |
4732 | from different threads, which is a stronger assumption than \f(CW\*(C`EV_NO_SMP\*(C'\fR, |
4736 | 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. |
4737 | above. This reduces dependencies and makes libev faster. |
4734 | .IP "\s-1EV_ATOMIC_T\s0" 4 |
4738 | .IP "\s-1EV_ATOMIC_T\s0" 4 |
4735 | .IX Item "EV_ATOMIC_T" |
4739 | .IX Item "EV_ATOMIC_T" |
4736 | Libev requires an integer type (suitable for storing \f(CW0\fR or \f(CW1\fR) whose |
4740 | 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 |
4741 | 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 |
4742 | 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 |
4743 | 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 |
4744 | 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. |
4745 | watchers. |
4742 | .Sp |
4746 | .Sp |
4743 | In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR |
4747 | 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, |
4748 | (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 |
4749 | .IP "\s-1EV_H\s0 (h)" 4 |
4748 | .IX Item "EV_H (h)" |
4750 | .IX Item "EV_H (h)" |
4749 | The name of the \fIev.h\fR header file used to include it. The default if |
4751 | 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 |
4752 | 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. |
4753 | 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 |
5415 | 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 |
5416 | 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. |
5417 | \&\f(CW\*(C`pthread_sigmask\*(C'\fR could complicate things, however. |
5416 | .Sp |
5418 | .Sp |
5417 | The most portable way to handle signals is to block signals in all threads |
5419 | 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 |
5420 | except the initial one, and run the signal handling loop in the initial |
5419 | well. |
5421 | thread as well. |
5420 | .ie n .IP """long"" must be large enough for common memory allocation sizes" 4 |
5422 | .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 |
5423 | .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" |
5424 | .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 |
5425 | 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 |
5426 | instead of \f(CW\*(C`size_t\*(C'\fR when allocating its data structures. On non-POSIX |