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

Comparing libev/ev.3 (file contents):
Revision 1.95 by root, Sat May 26 08:52:09 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-05-26" "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,
… …
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"
3393Fork watchers are called when a \f(CW\*(C`fork ()\*(C'\fR was detected (usually because 3394Fork 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 3395whoever 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
3396event loop blocks next and before \f(CW\*(C`ev_check\*(C'\fR watchers are being called, 3397and 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 3398after 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 3399and calls it in the wrong process, the fork handlers will be invoked, too,
3399handlers will be invoked, too, of course. 3400of 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
3404Most uses of \f(CW\*(C`fork()\*(C'\fR consist of forking, then some simple calls to set 3405Most uses of \f(CW\*(C`fork()\*(C'\fR consist of forking, then some simple calls to set
… …
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
… …
4261.IX Item "w->set (loop)" 4262.IX Item "w->set (loop)"
4262Associates a different \f(CW\*(C`struct ev_loop\*(C'\fR with this watcher. You can only 4263Associates 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). 4264do 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])"
4266Basically the same as \f(CW\*(C`ev_TYPE_set\*(C'\fR, with the same arguments. Either this 4267Basically 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 4268with the same arguments. Either this method or a suitable start method
4268C counterpart, an active watcher gets automatically stopped and restarted 4269must be called at least once. Unlike the C counterpart, an active watcher
4269when reconfiguring it with this method. 4270gets automatically stopped and restarted when reconfiguring it with this
4271method.
4272.Sp
4273For \f(CW\*(C`ev::embed\*(C'\fR watchers this method is called \f(CW\*(C`set_embed\*(C'\fR, to avoid
4274clashing 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 ()"
4272Starts the watcher. Note that there is no \f(CW\*(C`loop\*(C'\fR argument, as the 4277Starts the watcher. Note that there is no \f(CW\*(C`loop\*(C'\fR argument, as the
4273constructor already stores the event loop. 4278constructor already stores the event loop.
4274.IP "w\->start ([arguments])" 4 4279.IP "w\->start ([arguments])" 4
… …
4732from different threads, which is a stronger assumption than \f(CW\*(C`EV_NO_SMP\*(C'\fR, 4737from different threads, which is a stronger assumption than \f(CW\*(C`EV_NO_SMP\*(C'\fR,
4733above. This reduces dependencies and makes libev faster. 4738above. 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"
4736Libev requires an integer type (suitable for storing \f(CW0\fR or \f(CW1\fR) whose 4741Libev requires an integer type (suitable for storing \f(CW0\fR or \f(CW1\fR) whose
4737access is atomic and serialised with respect to other threads or signal 4742access is atomic with respect to other threads or signal contexts. No
4738contexts. No such type is easily found in the C language, so you can 4743such type is easily found in the C language, so you can provide your own
4739provide your own type that you know is safe for your purposes. It is used 4744type that you know is safe for your purposes. It is used both for signal
4740both for signal handler \*(L"locking\*(R" as well as for signal and thread safety 4745handler \*(L"locking\*(R" as well as for signal and thread safety in \f(CW\*(C`ev_async\*(C'\fR
4741in \f(CW\*(C`ev_async\*(C'\fR watchers. 4746watchers.
4742.Sp 4747.Sp
4743In the absence of this define, libev will use \f(CW\*(C`sig_atomic_t volatile\*(C'\fR 4748In 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.
4745although strictly speaking using a type that also implies a memory fence
4746is 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)"
4749The name of the \fIev.h\fR header file used to include it. The default if 4752The name of the \fIev.h\fR header file used to include it. The default if
4750undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be 4753undefined is \f(CW"ev.h"\fR in \fIevent.h\fR, \fIev.c\fR and \fIev++.h\fR. This can be
4751used to virtually rename the \fIev.h\fR header file in case of conflicts. 4754used to virtually rename the \fIev.h\fR header file in case of conflicts.
… …
5413thread\*(R" or will block signals process-wide, both behaviours would 5416thread\*(R" or will block signals process-wide, both behaviours would
5414be compatible with libev. Interaction between \f(CW\*(C`sigprocmask\*(C'\fR and 5417be 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
5417The most portable way to handle signals is to block signals in all threads 5420The most portable way to handle signals is to block signals in all threads
5418except the initial one, and run the default loop in the initial thread as 5421except the initial one, and run the signal handling loop in the initial
5419well. 5422thread 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"
5423To improve portability and simplify its \s-1API\s0, libev uses \f(CW\*(C`long\*(C'\fR internally 5426To improve portability and simplify its \s-1API\s0, libev uses \f(CW\*(C`long\*(C'\fR internally
5424instead of \f(CW\*(C`size_t\*(C'\fR when allocating its data structures. On non-POSIX 5427instead 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