… | |
… | |
130 | .\} |
130 | .\} |
131 | .rm #[ #] #H #V #F C |
131 | .rm #[ #] #H #V #F C |
132 | .\" ======================================================================== |
132 | .\" ======================================================================== |
133 | .\" |
133 | .\" |
134 | .IX Title "LIBEV 3" |
134 | .IX Title "LIBEV 3" |
135 | .TH LIBEV 3 "2008-11-17" "libev-3.49" "libev - high performance full featured event loop" |
135 | .TH LIBEV 3 "2008-12-14" "libev-3.51" "libev - high performance full featured event loop" |
136 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
136 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes |
137 | .\" way too many mistakes in technical documents. |
137 | .\" way too many mistakes in technical documents. |
138 | .if n .ad l |
138 | .if n .ad l |
139 | .nh |
139 | .nh |
140 | .SH "NAME" |
140 | .SH "NAME" |
… | |
… | |
182 | \& |
182 | \& |
183 | \& int |
183 | \& int |
184 | \& main (void) |
184 | \& main (void) |
185 | \& { |
185 | \& { |
186 | \& // use the default event loop unless you have special needs |
186 | \& // use the default event loop unless you have special needs |
187 | \& ev_loop *loop = ev_default_loop (0); |
187 | \& struct ev_loop *loop = ev_default_loop (0); |
188 | \& |
188 | \& |
189 | \& // initialise an io watcher, then start it |
189 | \& // initialise an io watcher, then start it |
190 | \& // this one will watch for stdin to become readable |
190 | \& // this one will watch for stdin to become readable |
191 | \& ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ); |
191 | \& ev_io_init (&stdin_watcher, stdin_cb, /*STDIN_FILENO*/ 0, EV_READ); |
192 | \& ev_io_start (loop, &stdin_watcher); |
192 | \& ev_io_start (loop, &stdin_watcher); |
… | |
… | |
586 | .Sp |
586 | .Sp |
587 | While nominally embeddable in other event loops, this doesn't work |
587 | While nominally embeddable in other event loops, this doesn't work |
588 | everywhere, so you might need to test for this. And since it is broken |
588 | everywhere, so you might need to test for this. And since it is broken |
589 | almost everywhere, you should only use it when you have a lot of sockets |
589 | almost everywhere, you should only use it when you have a lot of sockets |
590 | (for which it usually works), by embedding it into another event loop |
590 | (for which it usually works), by embedding it into another event loop |
591 | (e.g. \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR) and, did I mention it, |
591 | (e.g. \f(CW\*(C`EVBACKEND_SELECT\*(C'\fR or \f(CW\*(C`EVBACKEND_POLL\*(C'\fR (but \f(CW\*(C`poll\*(C'\fR is of course |
592 | using it only for sockets. |
592 | also broken on \s-1OS\s0 X)) and, did I mention it, using it only for sockets. |
593 | .Sp |
593 | .Sp |
594 | This backend maps \f(CW\*(C`EV_READ\*(C'\fR into an \f(CW\*(C`EVFILT_READ\*(C'\fR kevent with |
594 | This backend maps \f(CW\*(C`EV_READ\*(C'\fR into an \f(CW\*(C`EVFILT_READ\*(C'\fR kevent with |
595 | \&\f(CW\*(C`NOTE_EOF\*(C'\fR, and \f(CW\*(C`EV_WRITE\*(C'\fR into an \f(CW\*(C`EVFILT_WRITE\*(C'\fR kevent with |
595 | \&\f(CW\*(C`NOTE_EOF\*(C'\fR, and \f(CW\*(C`EV_WRITE\*(C'\fR into an \f(CW\*(C`EVFILT_WRITE\*(C'\fR kevent with |
596 | \&\f(CW\*(C`NOTE_EOF\*(C'\fR. |
596 | \&\f(CW\*(C`NOTE_EOF\*(C'\fR. |
597 | .ie n .IP """EVBACKEND_DEVPOLL"" (value 16, Solaris 8)" 4 |
597 | .ie n .IP """EVBACKEND_DEVPOLL"" (value 16, Solaris 8)" 4 |
… | |
… | |
2164 | the process. The exception are \f(CW\*(C`ev_stat\*(C'\fR watchers \- those call \f(CW\*(C`stat |
2164 | the process. The exception are \f(CW\*(C`ev_stat\*(C'\fR watchers \- those call \f(CW\*(C`stat |
2165 | ()\*(C'\fR, which is a synchronous operation. |
2165 | ()\*(C'\fR, which is a synchronous operation. |
2166 | .PP |
2166 | .PP |
2167 | For local paths, this usually doesn't matter: unless the system is very |
2167 | For local paths, this usually doesn't matter: unless the system is very |
2168 | busy or the intervals between stat's are large, a stat call will be fast, |
2168 | busy or the intervals between stat's are large, a stat call will be fast, |
2169 | as the path data is suually in memory already (except when starting the |
2169 | as the path data is usually in memory already (except when starting the |
2170 | watcher). |
2170 | watcher). |
2171 | .PP |
2171 | .PP |
2172 | For networked file systems, calling \f(CW\*(C`stat ()\*(C'\fR can block an indefinite |
2172 | For networked file systems, calling \f(CW\*(C`stat ()\*(C'\fR can block an indefinite |
2173 | time due to network issues, and even under good conditions, a stat call |
2173 | time due to network issues, and even under good conditions, a stat call |
2174 | often takes multiple milliseconds. |
2174 | often takes multiple milliseconds. |
… | |
… | |
2580 | some fds have to be watched and handled very quickly (with low latency), |
2580 | some fds have to be watched and handled very quickly (with low latency), |
2581 | and even priorities and idle watchers might have too much overhead. In |
2581 | and even priorities and idle watchers might have too much overhead. In |
2582 | this case you would put all the high priority stuff in one loop and all |
2582 | this case you would put all the high priority stuff in one loop and all |
2583 | the rest in a second one, and embed the second one in the first. |
2583 | the rest in a second one, and embed the second one in the first. |
2584 | .PP |
2584 | .PP |
2585 | As long as the watcher is active, the callback will be invoked every time |
2585 | As long as the watcher is active, the callback will be invoked every |
2586 | there might be events pending in the embedded loop. The callback must then |
2586 | time there might be events pending in the embedded loop. The callback |
2587 | call \f(CW\*(C`ev_embed_sweep (mainloop, watcher)\*(C'\fR to make a single sweep and invoke |
2587 | must then call \f(CW\*(C`ev_embed_sweep (mainloop, watcher)\*(C'\fR to make a single |
2588 | their callbacks (you could also start an idle watcher to give the embedded |
2588 | sweep and invoke their callbacks (the callback doesn't need to invoke the |
2589 | loop strictly lower priority for example). You can also set the callback |
2589 | \&\f(CW\*(C`ev_embed_sweep\*(C'\fR function directly, it could also start an idle watcher |
2590 | to \f(CW0\fR, in which case the embed watcher will automatically execute the |
2590 | to give the embedded loop strictly lower priority for example). |
2591 | embedded loop sweep. |
|
|
2592 | .PP |
2591 | .PP |
2593 | As long as the watcher is started it will automatically handle events. The |
2592 | You can also set the callback to \f(CW0\fR, in which case the embed watcher |
2594 | callback will be invoked whenever some events have been handled. You can |
2593 | will automatically execute the embedded loop sweep whenever necessary. |
2595 | set the callback to \f(CW0\fR to avoid having to specify one if you are not |
|
|
2596 | interested in that. |
|
|
2597 | .PP |
2594 | .PP |
2598 | Also, there have not currently been made special provisions for forking: |
2595 | Fork detection will be handled transparently while the \f(CW\*(C`ev_embed\*(C'\fR watcher |
2599 | when you fork, you not only have to call \f(CW\*(C`ev_loop_fork\*(C'\fR on both loops, |
2596 | is active, i.e., the embedded loop will automatically be forked when the |
2600 | but you will also have to stop and restart any \f(CW\*(C`ev_embed\*(C'\fR watchers |
2597 | embedding loop forks. In other cases, the user is responsible for calling |
2601 | yourself \- but you can use a fork watcher to handle this automatically, |
2598 | \&\f(CW\*(C`ev_loop_fork\*(C'\fR on the embedded loop. |
2602 | and future versions of libev might do just that. |
|
|
2603 | .PP |
2599 | .PP |
2604 | Unfortunately, not all backends are embeddable: only the ones returned by |
2600 | Unfortunately, not all backends are embeddable: only the ones returned by |
2605 | \&\f(CW\*(C`ev_embeddable_backends\*(C'\fR are, which, unfortunately, does not include any |
2601 | \&\f(CW\*(C`ev_embeddable_backends\*(C'\fR are, which, unfortunately, does not include any |
2606 | portable one. |
2602 | portable one. |
2607 | .PP |
2603 | .PP |
… | |
… | |
3016 | \& |
3012 | \& |
3017 | \& myclass obj; |
3013 | \& myclass obj; |
3018 | \& ev::io iow; |
3014 | \& ev::io iow; |
3019 | \& iow.set <myclass, &myclass::io_cb> (&obj); |
3015 | \& iow.set <myclass, &myclass::io_cb> (&obj); |
3020 | .Ve |
3016 | .Ve |
|
|
3017 | .IP "w\->set (object *)" 4 |
|
|
3018 | .IX Item "w->set (object *)" |
|
|
3019 | This is an \fBexperimental\fR feature that might go away in a future version. |
|
|
3020 | .Sp |
|
|
3021 | This is a variation of a method callback \- leaving out the method to call |
|
|
3022 | will default the method to \f(CW\*(C`operator ()\*(C'\fR, which makes it possible to use |
|
|
3023 | functor objects without having to manually specify the \f(CW\*(C`operator ()\*(C'\fR all |
|
|
3024 | the time. Incidentally, you can then also leave out the template argument |
|
|
3025 | list. |
|
|
3026 | .Sp |
|
|
3027 | The \f(CW\*(C`operator ()\*(C'\fR method prototype must be \f(CW\*(C`void operator ()(watcher &w, |
|
|
3028 | int revents)\*(C'\fR. |
|
|
3029 | .Sp |
|
|
3030 | See the method\-\f(CW\*(C`set\*(C'\fR above for more details. |
|
|
3031 | .Sp |
|
|
3032 | Example: use a functor object as callback. |
|
|
3033 | .Sp |
|
|
3034 | .Vb 7 |
|
|
3035 | \& struct myfunctor |
|
|
3036 | \& { |
|
|
3037 | \& void operator() (ev::io &w, int revents) |
|
|
3038 | \& { |
|
|
3039 | \& ... |
|
|
3040 | \& } |
|
|
3041 | \& } |
|
|
3042 | \& |
|
|
3043 | \& myfunctor f; |
|
|
3044 | \& |
|
|
3045 | \& ev::io w; |
|
|
3046 | \& w.set (&f); |
|
|
3047 | .Ve |
3021 | .IP "w\->set<function> (void *data = 0)" 4 |
3048 | .IP "w\->set<function> (void *data = 0)" 4 |
3022 | .IX Item "w->set<function> (void *data = 0)" |
3049 | .IX Item "w->set<function> (void *data = 0)" |
3023 | Also sets a callback, but uses a static method or plain function as |
3050 | Also sets a callback, but uses a static method or plain function as |
3024 | callback. The optional \f(CW\*(C`data\*(C'\fR argument will be stored in the watcher's |
3051 | callback. The optional \f(CW\*(C`data\*(C'\fR argument will be stored in the watcher's |
3025 | \&\f(CW\*(C`data\*(C'\fR member and is free for you to use. |
3052 | \&\f(CW\*(C`data\*(C'\fR member and is free for you to use. |
… | |
… | |
3115 | .IX Item "Ruby" |
3142 | .IX Item "Ruby" |
3116 | Tony Arcieri has written a ruby extension that offers access to a subset |
3143 | Tony Arcieri has written a ruby extension that offers access to a subset |
3117 | of the libev \s-1API\s0 and adds file handle abstractions, asynchronous \s-1DNS\s0 and |
3144 | of the libev \s-1API\s0 and adds file handle abstractions, asynchronous \s-1DNS\s0 and |
3118 | more on top of it. It can be found via gem servers. Its homepage is at |
3145 | more on top of it. It can be found via gem servers. Its homepage is at |
3119 | <http://rev.rubyforge.org/>. |
3146 | <http://rev.rubyforge.org/>. |
|
|
3147 | .Sp |
|
|
3148 | Roger Pack reports that using the link order \f(CW\*(C`\-lws2_32 \-lmsvcrt\-ruby\-190\*(C'\fR |
|
|
3149 | makes rev work even on mingw. |
3120 | .IP "D" 4 |
3150 | .IP "D" 4 |
3121 | .IX Item "D" |
3151 | .IX Item "D" |
3122 | Leandro Lucarella has written a D language binding (\fIev.d\fR) for libev, to |
3152 | Leandro Lucarella has written a D language binding (\fIev.d\fR) for libev, to |
3123 | be found at <http://proj.llucax.com.ar/wiki/evd>. |
3153 | be found at <http://proj.llucax.com.ar/wiki/evd>. |
3124 | .IP "Ocaml" 4 |
3154 | .IP "Ocaml" 4 |
… | |
… | |
3307 | Must always be \f(CW1\fR if you do not use autoconf configuration, which |
3337 | Must always be \f(CW1\fR if you do not use autoconf configuration, which |
3308 | keeps libev from including \fIconfig.h\fR, and it also defines dummy |
3338 | keeps libev from including \fIconfig.h\fR, and it also defines dummy |
3309 | implementations for some libevent functions (such as logging, which is not |
3339 | implementations for some libevent functions (such as logging, which is not |
3310 | supported). It will also not define any of the structs usually found in |
3340 | supported). It will also not define any of the structs usually found in |
3311 | \&\fIevent.h\fR that are not directly supported by the libev core alone. |
3341 | \&\fIevent.h\fR that are not directly supported by the libev core alone. |
|
|
3342 | .Sp |
|
|
3343 | In stanbdalone mode, libev will still try to automatically deduce the |
|
|
3344 | configuration, but has to be more conservative. |
3312 | .IP "\s-1EV_USE_MONOTONIC\s0" 4 |
3345 | .IP "\s-1EV_USE_MONOTONIC\s0" 4 |
3313 | .IX Item "EV_USE_MONOTONIC" |
3346 | .IX Item "EV_USE_MONOTONIC" |
3314 | If defined to be \f(CW1\fR, libev will try to detect the availability of the |
3347 | If defined to be \f(CW1\fR, libev will try to detect the availability of the |
3315 | monotonic clock option at both compile time and runtime. Otherwise no use |
3348 | monotonic clock option at both compile time and runtime. Otherwise no |
3316 | of the monotonic clock option will be attempted. If you enable this, you |
3349 | use of the monotonic clock option will be attempted. If you enable this, |
3317 | usually have to link against librt or something similar. Enabling it when |
3350 | you usually have to link against librt or something similar. Enabling it |
3318 | the functionality isn't available is safe, though, although you have |
3351 | when the functionality isn't available is safe, though, although you have |
3319 | to make sure you link against any libraries where the \f(CW\*(C`clock_gettime\*(C'\fR |
3352 | to make sure you link against any libraries where the \f(CW\*(C`clock_gettime\*(C'\fR |
3320 | function is hiding in (often \fI\-lrt\fR). |
3353 | function is hiding in (often \fI\-lrt\fR). See also \f(CW\*(C`EV_USE_CLOCK_SYSCALL\*(C'\fR. |
3321 | .IP "\s-1EV_USE_REALTIME\s0" 4 |
3354 | .IP "\s-1EV_USE_REALTIME\s0" 4 |
3322 | .IX Item "EV_USE_REALTIME" |
3355 | .IX Item "EV_USE_REALTIME" |
3323 | If defined to be \f(CW1\fR, libev will try to detect the availability of the |
3356 | If defined to be \f(CW1\fR, libev will try to detect the availability of the |
3324 | real-time clock option at compile time (and assume its availability at |
3357 | real-time clock option at compile time (and assume its availability at |
3325 | runtime if successful). Otherwise no use of the real-time clock option will |
3358 | runtime if successful). Otherwise no use of the real-time clock option will |
3326 | be attempted. This effectively replaces \f(CW\*(C`gettimeofday\*(C'\fR by \f(CW\*(C`clock_get |
3359 | be attempted. This effectively replaces \f(CW\*(C`gettimeofday\*(C'\fR by \f(CW\*(C`clock_get |
3327 | (CLOCK_REALTIME, ...)\*(C'\fR and will not normally affect correctness. See the |
3360 | (CLOCK_REALTIME, ...)\*(C'\fR and will not normally affect correctness. See the |
3328 | note about libraries in the description of \f(CW\*(C`EV_USE_MONOTONIC\*(C'\fR, though. |
3361 | note about libraries in the description of \f(CW\*(C`EV_USE_MONOTONIC\*(C'\fR, though. |
|
|
3362 | .IP "\s-1EV_USE_CLOCK_SYSCALL\s0" 4 |
|
|
3363 | .IX Item "EV_USE_CLOCK_SYSCALL" |
|
|
3364 | If defined to be \f(CW1\fR, libev will try to use a direct syscall instead |
|
|
3365 | of calling the system-provided \f(CW\*(C`clock_gettime\*(C'\fR function. This option |
|
|
3366 | exists because on GNU/Linux, \f(CW\*(C`clock_gettime\*(C'\fR is in \f(CW\*(C`librt\*(C'\fR, but \f(CW\*(C`librt\*(C'\fR |
|
|
3367 | unconditionally pulls in \f(CW\*(C`libpthread\*(C'\fR, slowing down single-threaded |
|
|
3368 | programs needlessly. Using a direct syscall is slightly slower (in |
|
|
3369 | theory), because no optimised vdso implementation can be used, but avoids |
|
|
3370 | the pthread dependency. Defaults to \f(CW1\fR on GNU/Linux with glibc 2.x or |
|
|
3371 | higher, as it simplifies linking (no need for \f(CW\*(C`\-lrt\*(C'\fR). |
3329 | .IP "\s-1EV_USE_NANOSLEEP\s0" 4 |
3372 | .IP "\s-1EV_USE_NANOSLEEP\s0" 4 |
3330 | .IX Item "EV_USE_NANOSLEEP" |
3373 | .IX Item "EV_USE_NANOSLEEP" |
3331 | If defined to be \f(CW1\fR, libev will assume that \f(CW\*(C`nanosleep ()\*(C'\fR is available |
3374 | If defined to be \f(CW1\fR, libev will assume that \f(CW\*(C`nanosleep ()\*(C'\fR is available |
3332 | and will use it for delays. Otherwise it will use \f(CW\*(C`select ()\*(C'\fR. |
3375 | and will use it for delays. Otherwise it will use \f(CW\*(C`select ()\*(C'\fR. |
3333 | .IP "\s-1EV_USE_EVENTFD\s0" 4 |
3376 | .IP "\s-1EV_USE_EVENTFD\s0" 4 |
… | |
… | |
3345 | will not be compiled in. |
3388 | will not be compiled in. |
3346 | .IP "\s-1EV_SELECT_USE_FD_SET\s0" 4 |
3389 | .IP "\s-1EV_SELECT_USE_FD_SET\s0" 4 |
3347 | .IX Item "EV_SELECT_USE_FD_SET" |
3390 | .IX Item "EV_SELECT_USE_FD_SET" |
3348 | If defined to \f(CW1\fR, then the select backend will use the system \f(CW\*(C`fd_set\*(C'\fR |
3391 | If defined to \f(CW1\fR, then the select backend will use the system \f(CW\*(C`fd_set\*(C'\fR |
3349 | structure. This is useful if libev doesn't compile due to a missing |
3392 | structure. This is useful if libev doesn't compile due to a missing |
3350 | \&\f(CW\*(C`NFDBITS\*(C'\fR or \f(CW\*(C`fd_mask\*(C'\fR definition or it mis-guesses the bitset layout on |
3393 | \&\f(CW\*(C`NFDBITS\*(C'\fR or \f(CW\*(C`fd_mask\*(C'\fR definition or it mis-guesses the bitset layout |
3351 | exotic systems. This usually limits the range of file descriptors to some |
3394 | on exotic systems. This usually limits the range of file descriptors to |
3352 | low limit such as 1024 or might have other limitations (winsocket only |
3395 | some low limit such as 1024 or might have other limitations (winsocket |
3353 | allows 64 sockets). The \f(CW\*(C`FD_SETSIZE\*(C'\fR macro, set before compilation, might |
3396 | only allows 64 sockets). The \f(CW\*(C`FD_SETSIZE\*(C'\fR macro, set before compilation, |
3354 | influence the size of the \f(CW\*(C`fd_set\*(C'\fR used. |
3397 | configures the maximum size of the \f(CW\*(C`fd_set\*(C'\fR. |
3355 | .IP "\s-1EV_SELECT_IS_WINSOCKET\s0" 4 |
3398 | .IP "\s-1EV_SELECT_IS_WINSOCKET\s0" 4 |
3356 | .IX Item "EV_SELECT_IS_WINSOCKET" |
3399 | .IX Item "EV_SELECT_IS_WINSOCKET" |
3357 | When defined to \f(CW1\fR, the select backend will assume that |
3400 | When defined to \f(CW1\fR, the select backend will assume that |
3358 | select/socket/connect etc. don't understand file descriptors but |
3401 | select/socket/connect etc. don't understand file descriptors but |
3359 | wants osf handles on win32 (this is the case when the select to |
3402 | wants osf handles on win32 (this is the case when the select to |