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

Comparing libev/ev.3 (file contents):
Revision 1.100 by root, Tue Oct 29 12:13:37 2013 UTC vs.
Revision 1.103 by root, Fri May 1 17:23:34 2015 UTC

1.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) 1.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.28)
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
… …
131.\} 131.\}
132.rm #[ #] #H #V #F C 132.rm #[ #] #H #V #F C
133.\" ======================================================================== 133.\" ========================================================================
134.\" 134.\"
135.IX Title "LIBEV 3" 135.IX Title "LIBEV 3"
136.TH LIBEV 3 "2013-10-29" "libev-4.15" "libev - high performance full featured event loop" 136.TH LIBEV 3 "2015-05-01" "libev-4.19" "libev - high performance full featured event loop"
137.\" For nroff, turn off justification. Always turn off hyphenation; it makes 137.\" For nroff, turn off justification. Always turn off hyphenation; it makes
138.\" way too many mistakes in technical documents. 138.\" way too many mistakes in technical documents.
139.if n .ad l 139.if n .ad l
140.nh 140.nh
141.SH "NAME" 141.SH "NAME"
… …
810except in the rare occasion where you really need to free its resources. 810except in the rare occasion where you really need to free its resources.
811If you need dynamically allocated loops it is better to use \f(CW\*(C`ev_loop_new\*(C'\fR 811If you need dynamically allocated loops it is better to use \f(CW\*(C`ev_loop_new\*(C'\fR
812and \f(CW\*(C`ev_loop_destroy\*(C'\fR. 812and \f(CW\*(C`ev_loop_destroy\*(C'\fR.
813.IP "ev_loop_fork (loop)" 4 813.IP "ev_loop_fork (loop)" 4
814.IX Item "ev_loop_fork (loop)" 814.IX Item "ev_loop_fork (loop)"
815This function sets a flag that causes subsequent \f(CW\*(C`ev_run\*(C'\fR iterations to 815This function sets a flag that causes subsequent \f(CW\*(C`ev_run\*(C'\fR iterations
816reinitialise the kernel state for backends that have one. Despite the 816to reinitialise the kernel state for backends that have one. Despite
817name, you can call it anytime, but it makes most sense after forking, in 817the name, you can call it anytime you are allowed to start or stop
818the child process. You \fImust\fR call it (or use \f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR) in the 818watchers (except inside an \f(CW\*(C`ev_prepare\*(C'\fR callback), but it makes most
819child before resuming or calling \f(CW\*(C`ev_run\*(C'\fR. 819sense after forking, in the child process. You \fImust\fR call it (or use
820\&\f(CW\*(C`EVFLAG_FORKCHECK\*(C'\fR) in the child before resuming or calling \f(CW\*(C`ev_run\*(C'\fR.
820.Sp 821.Sp
821Again, you \fIhave\fR to call it on \fIany\fR loop that you want to re-use after 822Again, you \fIhave\fR to call it on \fIany\fR loop that you want to re-use after
822a fork, \fIeven if you do not plan to use the loop in the parent\fR. This is 823a fork, \fIeven if you do not plan to use the loop in the parent\fR. This is
823because some kernel interfaces *cough* \fIkqueue\fR *cough* do funny things 824because some kernel interfaces *cough* \fIkqueue\fR *cough* do funny things
824during fork. 825during fork.
… …
2161.PP 2162.PP
2162The relative timeouts are calculated relative to the \f(CW\*(C`ev_now ()\*(C'\fR 2163The relative timeouts are calculated relative to the \f(CW\*(C`ev_now ()\*(C'\fR
2163time. This is usually the right thing as this timestamp refers to the time 2164time. This is usually the right thing as this timestamp refers to the time
2164of the event triggering whatever timeout you are modifying/starting. If 2165of the event triggering whatever timeout you are modifying/starting. If
2165you suspect event processing to be delayed and you \fIneed\fR to base the 2166you suspect event processing to be delayed and you \fIneed\fR to base the
2166timeout on the current time, use something like this to adjust for this: 2167timeout on the current time, use something like the following to adjust
2168for it:
2167.PP 2169.PP
2168.Vb 1 2170.Vb 1
2169\& ev_timer_set (&timer, after + ev_now () \- ev_time (), 0.); 2171\& ev_timer_set (&timer, after + (ev_time () \- ev_now ()), 0.);
2170.Ve 2172.Ve
2171.PP 2173.PP
2172If the event loop is suspended for a long time, you can also force an 2174If the event loop is suspended for a long time, you can also force an
2173update of the time returned by \f(CW\*(C`ev_now ()\*(C'\fR by calling \f(CW\*(C`ev_now_update 2175update of the time returned by \f(CW\*(C`ev_now ()\*(C'\fR by calling \f(CW\*(C`ev_now_update
2174()\*(C'\fR. 2176()\*(C'\fR, although that will push the event time of all outstanding events
2177further into the future.
2175.PP 2178.PP
2176\fIThe special problem of unsynchronised clocks\fR 2179\fIThe special problem of unsynchronised clocks\fR
2177.IX Subsection "The special problem of unsynchronised clocks" 2180.IX Subsection "The special problem of unsynchronised clocks"
2178.PP 2181.PP
2179Modern systems have a variety of clocks \- libev itself uses the normal 2182Modern systems have a variety of clocks \- libev itself uses the normal
… …
2553only within the same loop, i.e. you can watch for \f(CW\*(C`SIGINT\*(C'\fR in your 2556only within the same loop, i.e. you can watch for \f(CW\*(C`SIGINT\*(C'\fR in your
2554default loop and for \f(CW\*(C`SIGIO\*(C'\fR in another loop, but you cannot watch for 2557default loop and for \f(CW\*(C`SIGIO\*(C'\fR in another loop, but you cannot watch for
2555\&\f(CW\*(C`SIGINT\*(C'\fR in both the default loop and another loop at the same time. At 2558\&\f(CW\*(C`SIGINT\*(C'\fR in both the default loop and another loop at the same time. At
2556the moment, \f(CW\*(C`SIGCHLD\*(C'\fR is permanently tied to the default loop. 2559the moment, \f(CW\*(C`SIGCHLD\*(C'\fR is permanently tied to the default loop.
2557.PP 2560.PP
2558When the first watcher gets started will libev actually register something 2561Only after the first watcher for a signal is started will libev actually
2559with the kernel (thus it coexists with your own signal handlers as long as 2562register something with the kernel. It thus coexists with your own signal
2560you don't register any with libev for the same signal). 2563handlers as long as you don't register any with libev for the same signal.
2561.PP 2564.PP
2562If possible and supported, libev will install its handlers with 2565If possible and supported, libev will install its handlers with
2563\&\f(CW\*(C`SA_RESTART\*(C'\fR (or equivalent) behaviour enabled, so system calls should 2566\&\f(CW\*(C`SA_RESTART\*(C'\fR (or equivalent) behaviour enabled, so system calls should
2564not be unduly interrupted. If you have a problem with system calls getting 2567not be unduly interrupted. If you have a problem with system calls getting
2565interrupted by signals you can block all signals in an \f(CW\*(C`ev_check\*(C'\fR watcher 2568interrupted by signals you can block all signals in an \f(CW\*(C`ev_check\*(C'\fR watcher
… …
3048.IX Subsection "ev_prepare and ev_check - customise your event loop!" 3051.IX Subsection "ev_prepare and ev_check - customise your event loop!"
3049Prepare and check watchers are often (but not always) used in pairs: 3052Prepare and check watchers are often (but not always) used in pairs:
3050prepare watchers get invoked before the process blocks and check watchers 3053prepare watchers get invoked before the process blocks and check watchers
3051afterwards. 3054afterwards.
3052.PP 3055.PP
3053You \fImust not\fR call \f(CW\*(C`ev_run\*(C'\fR or similar functions that enter 3056You \fImust not\fR call \f(CW\*(C`ev_run\*(C'\fR (or similar functions that enter the
3054the current event loop from either \f(CW\*(C`ev_prepare\*(C'\fR or \f(CW\*(C`ev_check\*(C'\fR 3057current event loop) or \f(CW\*(C`ev_loop_fork\*(C'\fR from either \f(CW\*(C`ev_prepare\*(C'\fR or
3055watchers. Other loops than the current one are fine, however. The 3058\&\f(CW\*(C`ev_check\*(C'\fR watchers. Other loops than the current one are fine,
3056rationale behind this is that you do not need to check for recursion in 3059however. The rationale behind this is that you do not need to check
3057those watchers, i.e. the sequence will always be \f(CW\*(C`ev_prepare\*(C'\fR, blocking, 3060for recursion in those watchers, i.e. the sequence will always be
3058\&\f(CW\*(C`ev_check\*(C'\fR so if you have one watcher of each kind they will always be 3061\&\f(CW\*(C`ev_prepare\*(C'\fR, blocking, \f(CW\*(C`ev_check\*(C'\fR so if you have one watcher of each
3059called in pairs bracketing the blocking call. 3062kind they will always be called in pairs bracketing the blocking call.
3060.PP 3063.PP
3061Their main purpose is to integrate other event mechanisms into libev and 3064Their main purpose is to integrate other event mechanisms into libev and
3062their use is somewhat advanced. They could be used, for example, to track 3065their use is somewhat advanced. They could be used, for example, to track
3063variable changes, implement your own watchers, integrate net-snmp or a 3066variable changes, implement your own watchers, integrate net-snmp or a
3064coroutine library and lots more. They are also occasionally useful if 3067coroutine library and lots more. They are also occasionally useful if
… …
3358.PP 3361.PP
3359.Vb 3 3362.Vb 3
3360\& struct ev_loop *loop_hi = ev_default_init (0); 3363\& struct ev_loop *loop_hi = ev_default_init (0);
3361\& struct ev_loop *loop_lo = 0; 3364\& struct ev_loop *loop_lo = 0;
3362\& ev_embed embed; 3365\& ev_embed embed;
3363\& 3366\&
3364\& // see if there is a chance of getting one that works 3367\& // see if there is a chance of getting one that works
3365\& // (remember that a flags value of 0 means autodetection) 3368\& // (remember that a flags value of 0 means autodetection)
3366\& loop_lo = ev_embeddable_backends () & ev_recommended_backends () 3369\& loop_lo = ev_embeddable_backends () & ev_recommended_backends ()
3367\& ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ()) 3370\& ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ())
3368\& : 0; 3371\& : 0;
… …
3384.PP 3387.PP
3385.Vb 3 3388.Vb 3
3386\& struct ev_loop *loop = ev_default_init (0); 3389\& struct ev_loop *loop = ev_default_init (0);
3387\& struct ev_loop *loop_socket = 0; 3390\& struct ev_loop *loop_socket = 0;
3388\& ev_embed embed; 3391\& ev_embed embed;
3389\& 3392\&
3390\& if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE) 3393\& if (ev_supported_backends () & ~ev_recommended_backends () & EVBACKEND_KQUEUE)
3391\& if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE)) 3394\& if ((loop_socket = ev_loop_new (EVBACKEND_KQUEUE))
3392\& { 3395\& {
3393\& ev_embed_init (&embed, 0, loop_socket); 3396\& ev_embed_init (&embed, 0, loop_socket);
3394\& ev_embed_start (loop, &embed); 3397\& ev_embed_start (loop, &embed);
… …
3411of course. 3414of course.
3412.PP 3415.PP
3413\fIThe special problem of life after fork \- how is it possible?\fR 3416\fIThe special problem of life after fork \- how is it possible?\fR
3414.IX Subsection "The special problem of life after fork - how is it possible?" 3417.IX Subsection "The special problem of life after fork - how is it possible?"
3415.PP 3418.PP
3416Most uses of \f(CW\*(C`fork()\*(C'\fR consist of forking, then some simple calls to set 3419Most uses of \f(CW\*(C`fork ()\*(C'\fR consist of forking, then some simple calls to set
3417up/change the process environment, followed by a call to \f(CW\*(C`exec()\*(C'\fR. This 3420up/change the process environment, followed by a call to \f(CW\*(C`exec()\*(C'\fR. This
3418sequence should be handled by libev without any problems. 3421sequence should be handled by libev without any problems.
3419.PP 3422.PP
3420This changes when the application actually wants to do event handling 3423This changes when the application actually wants to do event handling
3421in the child, or both parent in child, in effect \*(L"continuing\*(R" after the 3424in the child, or both parent in child, in effect \*(L"continuing\*(R" after the
… …
4049files, \fImy_ev.h\fR and \fImy_ev.c\fR that include the respective libev files: 4052files, \fImy_ev.h\fR and \fImy_ev.c\fR that include the respective libev files:
4050.PP 4053.PP
4051.Vb 4 4054.Vb 4
4052\& // my_ev.h 4055\& // my_ev.h
4053\& #define EV_CB_DECLARE(type) struct my_coro *cb; 4056\& #define EV_CB_DECLARE(type) struct my_coro *cb;
4054\& #define EV_CB_INVOKE(watcher) switch_to ((watcher)\->cb); 4057\& #define EV_CB_INVOKE(watcher) switch_to ((watcher)\->cb)
4055\& #include "../libev/ev.h" 4058\& #include "../libev/ev.h"
4056\& 4059\&
4057\& // my_ev.c 4060\& // my_ev.c
4058\& #define EV_H "my_ev.h" 4061\& #define EV_H "my_ev.h"
4059\& #include "../libev/ev.c" 4062\& #include "../libev/ev.c"
… …
4245\& void operator() (ev::io &w, int revents) 4248\& void operator() (ev::io &w, int revents)
4246\& { 4249\& {
4247\& ... 4250\& ...
4248\& } 4251\& }
4249\& } 4252\& }
4250\& 4253\&
4251\& myfunctor f; 4254\& myfunctor f;
4252\& 4255\&
4253\& ev::io w; 4256\& ev::io w;
4254\& w.set (&f); 4257\& w.set (&f);
4255.Ve 4258.Ve

Diff Legend

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