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

Comparing libev/ev.3 (file contents):
Revision 1.93 by root, Sun May 6 13:05:35 2012 UTC vs.
Revision 1.96 by root, Thu Nov 15 01:39:45 2012 UTC

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"
3393Fork watchers are called when a \f(CW\*(C`fork ()\*(C'\fR was detected (usually because 3393Fork watchers are called when a \f(CW\*(C`fork ()\*(C'\fR was detected (usually because
3394whoever is a good citizen cared to tell libev about it by calling 3394whoever 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
3396event loop blocks next and before \f(CW\*(C`ev_check\*(C'\fR watchers are being called, 3396and before \f(CW\*(C`ev_check\*(C'\fR watchers are being called, and only in the child
3397and only in the child after the fork. If whoever good citizen calling 3397after 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 3398and calls it in the wrong process, the fork handlers will be invoked, too,
3399handlers will be invoked, too, of course. 3399of 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
3404Most uses of \f(CW\*(C`fork()\*(C'\fR consist of forking, then some simple calls to set 3404Most uses of \f(CW\*(C`fork()\*(C'\fR consist of forking, then some simple calls to set
… …
4088libev sources can be compiled as \*(C+. Therefore, code that uses the C \s-1API\s0 4088libev sources can be compiled as \*(C+. Therefore, code that uses the C \s-1API\s0
4089will work fine. 4089will work fine.
4090.PP 4090.PP
4091Proper exception specifications might have to be added to callbacks passed 4091Proper exception specifications might have to be added to callbacks passed
4092to libev: exceptions may be thrown only from watcher callbacks, all 4092to libev: exceptions may be thrown only from watcher callbacks, all
4093other callbacks (allocator, syserr, loop acquire/release and periodioc 4093other callbacks (allocator, syserr, loop acquire/release and periodic
4094reschedule callbacks) must not throw exceptions, and might need a \f(CW\*(C`throw 4094reschedule 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
4096and \*(C+ you can use the \f(CW\*(C`EV_THROW\*(C'\fR macro for this: 4096and \*(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)"
4262Associates a different \f(CW\*(C`struct ev_loop\*(C'\fR with this watcher. You can only 4262Associates a different \f(CW\*(C`struct ev_loop\*(C'\fR with this watcher. You can only
4263do this when the watcher is inactive (and not pending either). 4263do 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])"
4266Basically the same as \f(CW\*(C`ev_TYPE_set\*(C'\fR, with the same arguments. Either this 4266Basically the same as \f(CW\*(C`ev_TYPE_set\*(C'\fR (except for \f(CW\*(C`ev::embed\*(C'\fR watchers>),
4267method or a suitable start method must be called at least once. Unlike the 4267with the same arguments. Either this method or a suitable start method
4268C counterpart, an active watcher gets automatically stopped and restarted 4268must be called at least once. Unlike the C counterpart, an active watcher
4269when reconfiguring it with this method. 4269gets automatically stopped and restarted when reconfiguring it with this
4270method.
4271.Sp
4272For \f(CW\*(C`ev::embed\*(C'\fR watchers this method is called \f(CW\*(C`set_embed\*(C'\fR, to avoid
4273clashing 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 ()"
4272Starts the watcher. Note that there is no \f(CW\*(C`loop\*(C'\fR argument, as the 4276Starts the watcher. Note that there is no \f(CW\*(C`loop\*(C'\fR argument, as the
4273constructor already stores the event loop. 4277constructor already stores the event loop.
4274.IP "w\->start ([arguments])" 4 4278.IP "w\->start ([arguments])" 4
… …
4364.IP "Lua" 4 4368.IP "Lua" 4
4365.IX Item "Lua" 4369.IX Item "Lua"
4366Brian Maher has written a partial interface to libev for lua (at the 4370Brian Maher has written a partial interface to libev for lua (at the
4367time of this writing, only \f(CW\*(C`ev_io\*(C'\fR and \f(CW\*(C`ev_timer\*(C'\fR), to be found at 4371time of this writing, only \f(CW\*(C`ev_io\*(C'\fR and \f(CW\*(C`ev_timer\*(C'\fR), to be found at
4368http://github.com/brimworks/lua\-ev <http://github.com/brimworks/lua-ev>. 4372http://github.com/brimworks/lua\-ev <http://github.com/brimworks/lua-ev>.
4373.IP "Javascript" 4
4374.IX Item "Javascript"
4375Node.js (<http://nodejs.org>) uses libev as the underlying event library.
4376.IP "Others" 4
4377.IX Item "Others"
4378There are others, and I stopped counting.
4369.SH "MACRO MAGIC" 4379.SH "MACRO MAGIC"
4370.IX Header "MACRO MAGIC" 4380.IX Header "MACRO MAGIC"
4371Libev can be compiled with a variety of options, the most fundamental 4381Libev can be compiled with a variety of options, the most fundamental
4372of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most) 4382of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most)
4373functions and callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument. 4383functions and callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument.
… …
4668.IX Item "EV_WIN32_CLOSE_FD(fd)" 4678.IX Item "EV_WIN32_CLOSE_FD(fd)"
4669If programs implement their own fd to handle mapping on win32, then this 4679If programs implement their own fd to handle mapping on win32, then this
4670macro can be used to override the \f(CW\*(C`close\*(C'\fR function, useful to unregister 4680macro can be used to override the \f(CW\*(C`close\*(C'\fR function, useful to unregister
4671file descriptors again. Note that the replacement function has to close 4681file descriptors again. Note that the replacement function has to close
4672the underlying \s-1OS\s0 handle. 4682the underlying \s-1OS\s0 handle.
4683.IP "\s-1EV_USE_WSASOCKET\s0" 4
4684.IX Item "EV_USE_WSASOCKET"
4685If defined to be \f(CW1\fR, libev will use \f(CW\*(C`WSASocket\*(C'\fR to create its internal
4686communication socket, which works better in some environments. Otherwise,
4687the normal \f(CW\*(C`socket\*(C'\fR function will be used, which works better in other
4688environments.
4673.IP "\s-1EV_USE_POLL\s0" 4 4689.IP "\s-1EV_USE_POLL\s0" 4
4674.IX Item "EV_USE_POLL" 4690.IX Item "EV_USE_POLL"
4675If defined to be \f(CW1\fR, libev will compile in support for the \f(CW\*(C`poll\*(C'\fR(2) 4691If defined to be \f(CW1\fR, libev will compile in support for the \f(CW\*(C`poll\*(C'\fR(2)
4676backend. Otherwise it will be enabled on non\-win32 platforms. It 4692backend. Otherwise it will be enabled on non\-win32 platforms. It
4677takes precedence over select. 4693takes precedence over select.
… …
4720from different threads, which is a stronger assumption than \f(CW\*(C`EV_NO_SMP\*(C'\fR, 4736from different threads, which is a stronger assumption than \f(CW\*(C`EV_NO_SMP\*(C'\fR,
4721above. This reduces dependencies and makes libev faster. 4737above. This reduces dependencies and makes libev faster.
4722.IP "\s-1EV_ATOMIC_T\s0" 4 4738.IP "\s-1EV_ATOMIC_T\s0" 4
4723.IX Item "EV_ATOMIC_T" 4739.IX Item "EV_ATOMIC_T"
4724Libev requires an integer type (suitable for storing \f(CW0\fR or \f(CW1\fR) whose 4740Libev requires an integer type (suitable for storing \f(CW0\fR or \f(CW1\fR) whose
4725access is atomic and serialised with respect to other threads or signal 4741access is atomic with respect to other threads or signal contexts. No
4726contexts. No such type is easily found in the C language, so you can 4742such type is easily found in the C language, so you can provide your own
4727provide your own type that you know is safe for your purposes. It is used 4743type that you know is safe for your purposes. It is used both for signal
4728both for signal handler \*(L"locking\*(R" as well as for signal and thread safety 4744handler \*(L"locking\*(R" as well as for signal and thread safety in \f(CW\*(C`ev_async\*(C'\fR
4729in \f(CW\*(C`ev_async\*(C'\fR watchers. 4745watchers.
4730.Sp 4746.Sp
4731In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR 4747In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR
4732(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.
4733although strictly speaking using a type that also implies a memory fence
4734is required.
4735.IP "\s-1EV_H\s0 (h)" 4 4749.IP "\s-1EV_H\s0 (h)" 4
4736.IX Item "EV_H (h)" 4750.IX Item "EV_H (h)"
4737The name of the \fIev.h\fR header file used to include it. The default if 4751The name of the \fIev.h\fR header file used to include it. The default if
4738undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be 4752undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be
4739used to virtually rename the \fIev.h\fR header file in case of conflicts. 4753used to virtually rename the \fIev.h\fR header file in case of conflicts.
… …
5401thread\*(R" or will block signals process-wide, both behaviours would 5415thread\*(R" or will block signals process-wide, both behaviours would
5402be compatible with libev. Interaction between \f(CW\*(C`sigprocmask\*(C'\fR and 5416be compatible with libev. Interaction between \f(CW\*(C`sigprocmask\*(C'\fR and
5403\&\f(CW\*(C`pthread_sigmask\*(C'\fR could complicate things, however. 5417\&\f(CW\*(C`pthread_sigmask\*(C'\fR could complicate things, however.
5404.Sp 5418.Sp
5405The most portable way to handle signals is to block signals in all threads 5419The most portable way to handle signals is to block signals in all threads
5406except the initial one, and run the default loop in the initial thread as 5420except the initial one, and run the signal handling loop in the initial
5407well. 5421thread as well.
5408.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
5409.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
5410.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"
5411To improve portability and simplify its \s-1API\s0, libev uses \f(CW\*(C`long\*(C'\fR internally 5425To improve portability and simplify its \s-1API\s0, libev uses \f(CW\*(C`long\*(C'\fR internally
5412instead of \f(CW\*(C`size_t\*(C'\fR when allocating its data structures. On non-POSIX 5426instead of \f(CW\*(C`size_t\*(C'\fR when allocating its data structures. On non-POSIX

Diff Legend

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