… | |
… | |
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 "2009-07-15" "libev-3.7" "libev - high performance full featured event loop" |
127 | .TH LIBEV 3 "2009-12-31" "libev-3.9" "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" |
… | |
… | |
227 | .SS "\s-1FEATURES\s0" |
227 | .SS "\s-1FEATURES\s0" |
228 | .IX Subsection "FEATURES" |
228 | .IX Subsection "FEATURES" |
229 | Libev supports \f(CW\*(C`select\*(C'\fR, \f(CW\*(C`poll\*(C'\fR, the Linux-specific \f(CW\*(C`epoll\*(C'\fR, the |
229 | Libev supports \f(CW\*(C`select\*(C'\fR, \f(CW\*(C`poll\*(C'\fR, the Linux-specific \f(CW\*(C`epoll\*(C'\fR, the |
230 | BSD-specific \f(CW\*(C`kqueue\*(C'\fR and the Solaris-specific event port mechanisms |
230 | BSD-specific \f(CW\*(C`kqueue\*(C'\fR and the Solaris-specific event port mechanisms |
231 | for file descriptor events (\f(CW\*(C`ev_io\*(C'\fR), the Linux \f(CW\*(C`inotify\*(C'\fR interface |
231 | for file descriptor events (\f(CW\*(C`ev_io\*(C'\fR), the Linux \f(CW\*(C`inotify\*(C'\fR interface |
232 | (for \f(CW\*(C`ev_stat\*(C'\fR), relative timers (\f(CW\*(C`ev_timer\*(C'\fR), absolute timers |
232 | (for \f(CW\*(C`ev_stat\*(C'\fR), Linux eventfd/signalfd (for faster and cleaner |
233 | with customised rescheduling (\f(CW\*(C`ev_periodic\*(C'\fR), synchronous signals |
233 | inter-thread wakeup (\f(CW\*(C`ev_async\*(C'\fR)/signal handling (\f(CW\*(C`ev_signal\*(C'\fR)) relative |
234 | (\f(CW\*(C`ev_signal\*(C'\fR), process status change events (\f(CW\*(C`ev_child\*(C'\fR), and event |
234 | timers (\f(CW\*(C`ev_timer\*(C'\fR), absolute timers with customised rescheduling |
235 | watchers dealing with the event loop mechanism itself (\f(CW\*(C`ev_idle\*(C'\fR, |
235 | (\f(CW\*(C`ev_periodic\*(C'\fR), synchronous signals (\f(CW\*(C`ev_signal\*(C'\fR), process status |
236 | \&\f(CW\*(C`ev_embed\*(C'\fR, \f(CW\*(C`ev_prepare\*(C'\fR and \f(CW\*(C`ev_check\*(C'\fR watchers) as well as |
236 | change events (\f(CW\*(C`ev_child\*(C'\fR), and event watchers dealing with the event |
237 | file watchers (\f(CW\*(C`ev_stat\*(C'\fR) and even limited support for fork events |
237 | loop mechanism itself (\f(CW\*(C`ev_idle\*(C'\fR, \f(CW\*(C`ev_embed\*(C'\fR, \f(CW\*(C`ev_prepare\*(C'\fR and |
238 | (\f(CW\*(C`ev_fork\*(C'\fR). |
238 | \&\f(CW\*(C`ev_check\*(C'\fR watchers) as well as file watchers (\f(CW\*(C`ev_stat\*(C'\fR) and even |
|
|
239 | limited support for fork events (\f(CW\*(C`ev_fork\*(C'\fR). |
239 | .PP |
240 | .PP |
240 | It also is quite fast (see this |
241 | It also is quite fast (see this |
241 | <benchmark> comparing it to libevent |
242 | <benchmark> comparing it to libevent |
242 | for example). |
243 | for example). |
243 | .SS "\s-1CONVENTIONS\s0" |
244 | .SS "\s-1CONVENTIONS\s0" |
… | |
… | |
245 | Libev is very configurable. In this manual the default (and most common) |
246 | Libev is very configurable. In this manual the default (and most common) |
246 | configuration will be described, which supports multiple event loops. For |
247 | configuration will be described, which supports multiple event loops. For |
247 | more info about various configuration options please have a look at |
248 | more info about various configuration options please have a look at |
248 | \&\fB\s-1EMBED\s0\fR section in this manual. If libev was configured without support |
249 | \&\fB\s-1EMBED\s0\fR section in this manual. If libev was configured without support |
249 | for multiple event loops, then all functions taking an initial argument of |
250 | for multiple event loops, then all functions taking an initial argument of |
250 | name \f(CW\*(C`loop\*(C'\fR (which is always of type \f(CW\*(C`ev_loop *\*(C'\fR) will not have |
251 | name \f(CW\*(C`loop\*(C'\fR (which is always of type \f(CW\*(C`struct ev_loop *\*(C'\fR) will not have |
251 | this argument. |
252 | this argument. |
252 | .SS "\s-1TIME\s0 \s-1REPRESENTATION\s0" |
253 | .SS "\s-1TIME\s0 \s-1REPRESENTATION\s0" |
253 | .IX Subsection "TIME REPRESENTATION" |
254 | .IX Subsection "TIME REPRESENTATION" |
254 | Libev represents time as a single floating point number, representing |
255 | Libev represents time as a single floating point number, representing |
255 | the (fractional) number of seconds since the (\s-1POSIX\s0) epoch (somewhere |
256 | the (fractional) number of seconds since the (\s-1POSIX\s0) epoch (somewhere |
… | |
… | |
478 | forget about forgetting to tell libev about forking) when you use this |
479 | forget about forgetting to tell libev about forking) when you use this |
479 | flag. |
480 | flag. |
480 | .Sp |
481 | .Sp |
481 | This flag setting cannot be overridden or specified in the \f(CW\*(C`LIBEV_FLAGS\*(C'\fR |
482 | This flag setting cannot be overridden or specified in the \f(CW\*(C`LIBEV_FLAGS\*(C'\fR |
482 | environment variable. |
483 | environment variable. |
|
|
484 | .ie n .IP """EVFLAG_NOINOTIFY""" 4 |
|
|
485 | .el .IP "\f(CWEVFLAG_NOINOTIFY\fR" 4 |
|
|
486 | .IX Item "EVFLAG_NOINOTIFY" |
|
|
487 | When this flag is specified, then libev will not attempt to use the |
|
|
488 | \&\fIinotify\fR \s-1API\s0 for it's \f(CW\*(C`ev_stat\*(C'\fR watchers. Apart from debugging and |
|
|
489 | testing, this flag can be useful to conserve inotify file descriptors, as |
|
|
490 | otherwise each loop using \f(CW\*(C`ev_stat\*(C'\fR watchers consumes one inotify handle. |
|
|
491 | .ie n .IP """EVFLAG_SIGNALFD""" 4 |
|
|
492 | .el .IP "\f(CWEVFLAG_SIGNALFD\fR" 4 |
|
|
493 | .IX Item "EVFLAG_SIGNALFD" |
|
|
494 | When this flag is specified, then libev will attempt to use the |
|
|
495 | \&\fIsignalfd\fR \s-1API\s0 for it's \f(CW\*(C`ev_signal\*(C'\fR (and \f(CW\*(C`ev_child\*(C'\fR) watchers. This \s-1API\s0 |
|
|
496 | delivers signals synchronously, which makes it both faster and might make |
|
|
497 | it possible to get the queued signal data. It can also simplify signal |
|
|
498 | handling with threads, as long as you properly block signals in your |
|
|
499 | threads that are not interested in handling them. |
|
|
500 | .Sp |
|
|
501 | Signalfd will not be used by default as this changes your signal mask, and |
|
|
502 | there are a lot of shoddy libraries and programs (glib's threadpool for |
|
|
503 | example) that can't properly initialise their signal masks. |
483 | .ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4 |
504 | .ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4 |
484 | .el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4 |
505 | .el .IP "\f(CWEVBACKEND_SELECT\fR (value 1, portable select backend)" 4 |
485 | .IX Item "EVBACKEND_SELECT (value 1, portable select backend)" |
506 | .IX Item "EVBACKEND_SELECT (value 1, portable select backend)" |
486 | This is your standard \fIselect\fR\|(2) backend. Not \fIcompletely\fR standard, as |
507 | This is your standard \fIselect\fR\|(2) backend. Not \fIcompletely\fR standard, as |
487 | libev tries to roll its own fd_set with no limits on the number of fds, |
508 | libev tries to roll its own fd_set with no limits on the number of fds, |
… | |
… | |
512 | This backend maps \f(CW\*(C`EV_READ\*(C'\fR to \f(CW\*(C`POLLIN | POLLERR | POLLHUP\*(C'\fR, and |
533 | This backend maps \f(CW\*(C`EV_READ\*(C'\fR to \f(CW\*(C`POLLIN | POLLERR | POLLHUP\*(C'\fR, and |
513 | \&\f(CW\*(C`EV_WRITE\*(C'\fR to \f(CW\*(C`POLLOUT | POLLERR | POLLHUP\*(C'\fR. |
534 | \&\f(CW\*(C`EV_WRITE\*(C'\fR to \f(CW\*(C`POLLOUT | POLLERR | POLLHUP\*(C'\fR. |
514 | .ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4 |
535 | .ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4 |
515 | .el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4 |
536 | .el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4 |
516 | .IX Item "EVBACKEND_EPOLL (value 4, Linux)" |
537 | .IX Item "EVBACKEND_EPOLL (value 4, Linux)" |
|
|
538 | Use the linux-specific \fIepoll\fR\|(7) interface (for both pre\- and post\-2.6.9 |
|
|
539 | kernels). |
|
|
540 | .Sp |
517 | For few fds, this backend is a bit little slower than poll and select, |
541 | For few fds, this backend is a bit little slower than poll and select, |
518 | but it scales phenomenally better. While poll and select usually scale |
542 | but it scales phenomenally better. While poll and select usually scale |
519 | like O(total_fds) where n is the total number of fds (or the highest fd), |
543 | like O(total_fds) where n is the total number of fds (or the highest fd), |
520 | epoll scales either O(1) or O(active_fds). |
544 | epoll scales either O(1) or O(active_fds). |
521 | .Sp |
545 | .Sp |
… | |
… | |
635 | .Sp |
659 | .Sp |
636 | It is definitely not recommended to use this flag. |
660 | It is definitely not recommended to use this flag. |
637 | .RE |
661 | .RE |
638 | .RS 4 |
662 | .RS 4 |
639 | .Sp |
663 | .Sp |
640 | If one or more of these are or'ed into the flags value, then only these |
664 | If one or more of the backend flags are or'ed into the flags value, |
641 | backends will be tried (in the reverse order as listed here). If none are |
665 | then only these backends will be tried (in the reverse order as listed |
642 | specified, all backends in \f(CW\*(C`ev_recommended_backends ()\*(C'\fR will be tried. |
666 | here). If none are specified, all backends in \f(CW\*(C`ev_recommended_backends |
|
|
667 | ()\*(C'\fR will be tried. |
643 | .Sp |
668 | .Sp |
644 | Example: This is the most typical usage. |
669 | Example: This is the most typical usage. |
645 | .Sp |
670 | .Sp |
646 | .Vb 2 |
671 | .Vb 2 |
647 | \& if (!ev_default_loop (0)) |
672 | \& if (!ev_default_loop (0)) |
… | |
… | |
697 | as signal and child watchers) would need to be stopped manually. |
722 | as signal and child watchers) would need to be stopped manually. |
698 | .Sp |
723 | .Sp |
699 | In general it is not advisable to call this function except in the |
724 | In general it is not advisable to call this function except in the |
700 | rare occasion where you really need to free e.g. the signal handling |
725 | rare occasion where you really need to free e.g. the signal handling |
701 | pipe fds. If you need dynamically allocated loops it is better to use |
726 | pipe fds. If you need dynamically allocated loops it is better to use |
702 | \&\f(CW\*(C`ev_loop_new\*(C'\fR and \f(CW\*(C`ev_loop_destroy\*(C'\fR). |
727 | \&\f(CW\*(C`ev_loop_new\*(C'\fR and \f(CW\*(C`ev_loop_destroy\*(C'\fR. |
703 | .IP "ev_loop_destroy (loop)" 4 |
728 | .IP "ev_loop_destroy (loop)" 4 |
704 | .IX Item "ev_loop_destroy (loop)" |
729 | .IX Item "ev_loop_destroy (loop)" |
705 | Like \f(CW\*(C`ev_default_destroy\*(C'\fR, but destroys an event loop created by an |
730 | Like \f(CW\*(C`ev_default_destroy\*(C'\fR, but destroys an event loop created by an |
706 | earlier call to \f(CW\*(C`ev_loop_new\*(C'\fR. |
731 | earlier call to \f(CW\*(C`ev_loop_new\*(C'\fR. |
707 | .IP "ev_default_fork ()" 4 |
732 | .IP "ev_default_fork ()" 4 |
… | |
… | |
804 | Calling \f(CW\*(C`ev_suspend\*(C'\fR/\f(CW\*(C`ev_resume\*(C'\fR has the side effect of updating the |
829 | Calling \f(CW\*(C`ev_suspend\*(C'\fR/\f(CW\*(C`ev_resume\*(C'\fR has the side effect of updating the |
805 | event loop time (see \f(CW\*(C`ev_now_update\*(C'\fR). |
830 | event loop time (see \f(CW\*(C`ev_now_update\*(C'\fR). |
806 | .IP "ev_loop (loop, int flags)" 4 |
831 | .IP "ev_loop (loop, int flags)" 4 |
807 | .IX Item "ev_loop (loop, int flags)" |
832 | .IX Item "ev_loop (loop, int flags)" |
808 | Finally, this is it, the event handler. This function usually is called |
833 | Finally, this is it, the event handler. This function usually is called |
809 | after you initialised all your watchers and you want to start handling |
834 | after you have initialised all your watchers and you want to start |
810 | events. |
835 | handling events. |
811 | .Sp |
836 | .Sp |
812 | If the flags argument is specified as \f(CW0\fR, it will not return until |
837 | If the flags argument is specified as \f(CW0\fR, it will not return until |
813 | either no event watchers are active anymore or \f(CW\*(C`ev_unloop\*(C'\fR was called. |
838 | either no event watchers are active anymore or \f(CW\*(C`ev_unloop\*(C'\fR was called. |
814 | .Sp |
839 | .Sp |
815 | Please note that an explicit \f(CW\*(C`ev_unloop\*(C'\fR is usually better than |
840 | Please note that an explicit \f(CW\*(C`ev_unloop\*(C'\fR is usually better than |
… | |
… | |
893 | .PD |
918 | .PD |
894 | Ref/unref can be used to add or remove a reference count on the event |
919 | Ref/unref can be used to add or remove a reference count on the event |
895 | loop: Every watcher keeps one reference, and as long as the reference |
920 | loop: Every watcher keeps one reference, and as long as the reference |
896 | count is nonzero, \f(CW\*(C`ev_loop\*(C'\fR will not return on its own. |
921 | count is nonzero, \f(CW\*(C`ev_loop\*(C'\fR will not return on its own. |
897 | .Sp |
922 | .Sp |
898 | If you have a watcher you never unregister that should not keep \f(CW\*(C`ev_loop\*(C'\fR |
923 | This is useful when you have a watcher that you never intend to |
899 | from returning, call \fIev_unref()\fR after starting, and \fIev_ref()\fR before |
924 | unregister, but that nevertheless should not keep \f(CW\*(C`ev_loop\*(C'\fR from |
|
|
925 | returning. In such a case, call \f(CW\*(C`ev_unref\*(C'\fR after starting, and \f(CW\*(C`ev_ref\*(C'\fR |
900 | stopping it. |
926 | before stopping it. |
901 | .Sp |
927 | .Sp |
902 | As an example, libev itself uses this for its internal signal pipe: It |
928 | As an example, libev itself uses this for its internal signal pipe: It |
903 | is not visible to the libev user and should not keep \f(CW\*(C`ev_loop\*(C'\fR from |
929 | is not visible to the libev user and should not keep \f(CW\*(C`ev_loop\*(C'\fR from |
904 | exiting if no event watchers registered by it are active. It is also an |
930 | exiting if no event watchers registered by it are active. It is also an |
905 | excellent way to do this for generic recurring timers or from within |
931 | excellent way to do this for generic recurring timers or from within |
… | |
… | |
1023 | .Sp |
1049 | .Sp |
1024 | While event loop modifications are allowed between invocations of |
1050 | While event loop modifications are allowed between invocations of |
1025 | \&\f(CW\*(C`release\*(C'\fR and \f(CW\*(C`acquire\*(C'\fR (that's their only purpose after all), no |
1051 | \&\f(CW\*(C`release\*(C'\fR and \f(CW\*(C`acquire\*(C'\fR (that's their only purpose after all), no |
1026 | modifications done will affect the event loop, i.e. adding watchers will |
1052 | modifications done will affect the event loop, i.e. adding watchers will |
1027 | have no effect on the set of file descriptors being watched, or the time |
1053 | have no effect on the set of file descriptors being watched, or the time |
1028 | waited. USe an \f(CW\*(C`ev_async\*(C'\fR watcher to wake up \f(CW\*(C`ev_loop\*(C'\fR when you want it |
1054 | waited. Use an \f(CW\*(C`ev_async\*(C'\fR watcher to wake up \f(CW\*(C`ev_loop\*(C'\fR when you want it |
1029 | to take note of any changes you made. |
1055 | to take note of any changes you made. |
1030 | .Sp |
1056 | .Sp |
1031 | In theory, threads executing \f(CW\*(C`ev_loop\*(C'\fR will be async-cancel safe between |
1057 | In theory, threads executing \f(CW\*(C`ev_loop\*(C'\fR will be async-cancel safe between |
1032 | invocations of \f(CW\*(C`release\*(C'\fR and \f(CW\*(C`acquire\*(C'\fR. |
1058 | invocations of \f(CW\*(C`release\*(C'\fR and \f(CW\*(C`acquire\*(C'\fR. |
1033 | .Sp |
1059 | .Sp |
… | |
… | |
1228 | .Vb 3 |
1254 | .Vb 3 |
1229 | \& ev_io w; |
1255 | \& ev_io w; |
1230 | \& ev_init (&w, my_cb); |
1256 | \& ev_init (&w, my_cb); |
1231 | \& ev_io_set (&w, STDIN_FILENO, EV_READ); |
1257 | \& ev_io_set (&w, STDIN_FILENO, EV_READ); |
1232 | .Ve |
1258 | .Ve |
1233 | .ie n .IP """ev_TYPE_set"" (ev_TYPE *, [args])" 4 |
1259 | .ie n .IP """ev_TYPE_set"" (ev_TYPE *watcher, [args])" 4 |
1234 | .el .IP "\f(CWev_TYPE_set\fR (ev_TYPE *, [args])" 4 |
1260 | .el .IP "\f(CWev_TYPE_set\fR (ev_TYPE *watcher, [args])" 4 |
1235 | .IX Item "ev_TYPE_set (ev_TYPE *, [args])" |
1261 | .IX Item "ev_TYPE_set (ev_TYPE *watcher, [args])" |
1236 | This macro initialises the type-specific parts of a watcher. You need to |
1262 | This macro initialises the type-specific parts of a watcher. You need to |
1237 | call \f(CW\*(C`ev_init\*(C'\fR at least once before you call this macro, but you can |
1263 | call \f(CW\*(C`ev_init\*(C'\fR at least once before you call this macro, but you can |
1238 | call \f(CW\*(C`ev_TYPE_set\*(C'\fR any number of times. You must not, however, call this |
1264 | call \f(CW\*(C`ev_TYPE_set\*(C'\fR any number of times. You must not, however, call this |
1239 | macro on a watcher that is active (it can be pending, however, which is a |
1265 | macro on a watcher that is active (it can be pending, however, which is a |
1240 | difference to the \f(CW\*(C`ev_init\*(C'\fR macro). |
1266 | difference to the \f(CW\*(C`ev_init\*(C'\fR macro). |
… | |
… | |
1253 | Example: Initialise and set an \f(CW\*(C`ev_io\*(C'\fR watcher in one step. |
1279 | Example: Initialise and set an \f(CW\*(C`ev_io\*(C'\fR watcher in one step. |
1254 | .Sp |
1280 | .Sp |
1255 | .Vb 1 |
1281 | .Vb 1 |
1256 | \& ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ); |
1282 | \& ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ); |
1257 | .Ve |
1283 | .Ve |
1258 | .ie n .IP """ev_TYPE_start"" (loop *, ev_TYPE *watcher)" 4 |
1284 | .ie n .IP """ev_TYPE_start"" (loop, ev_TYPE *watcher)" 4 |
1259 | .el .IP "\f(CWev_TYPE_start\fR (loop *, ev_TYPE *watcher)" 4 |
1285 | .el .IP "\f(CWev_TYPE_start\fR (loop, ev_TYPE *watcher)" 4 |
1260 | .IX Item "ev_TYPE_start (loop *, ev_TYPE *watcher)" |
1286 | .IX Item "ev_TYPE_start (loop, ev_TYPE *watcher)" |
1261 | Starts (activates) the given watcher. Only active watchers will receive |
1287 | Starts (activates) the given watcher. Only active watchers will receive |
1262 | events. If the watcher is already active nothing will happen. |
1288 | events. If the watcher is already active nothing will happen. |
1263 | .Sp |
1289 | .Sp |
1264 | Example: Start the \f(CW\*(C`ev_io\*(C'\fR watcher that is being abused as example in this |
1290 | Example: Start the \f(CW\*(C`ev_io\*(C'\fR watcher that is being abused as example in this |
1265 | whole section. |
1291 | whole section. |
1266 | .Sp |
1292 | .Sp |
1267 | .Vb 1 |
1293 | .Vb 1 |
1268 | \& ev_io_start (EV_DEFAULT_UC, &w); |
1294 | \& ev_io_start (EV_DEFAULT_UC, &w); |
1269 | .Ve |
1295 | .Ve |
1270 | .ie n .IP """ev_TYPE_stop"" (loop *, ev_TYPE *watcher)" 4 |
1296 | .ie n .IP """ev_TYPE_stop"" (loop, ev_TYPE *watcher)" 4 |
1271 | .el .IP "\f(CWev_TYPE_stop\fR (loop *, ev_TYPE *watcher)" 4 |
1297 | .el .IP "\f(CWev_TYPE_stop\fR (loop, ev_TYPE *watcher)" 4 |
1272 | .IX Item "ev_TYPE_stop (loop *, ev_TYPE *watcher)" |
1298 | .IX Item "ev_TYPE_stop (loop, ev_TYPE *watcher)" |
1273 | Stops the given watcher if active, and clears the pending status (whether |
1299 | Stops the given watcher if active, and clears the pending status (whether |
1274 | the watcher was active or not). |
1300 | the watcher was active or not). |
1275 | .Sp |
1301 | .Sp |
1276 | It is possible that stopped watchers are pending \- for example, |
1302 | It is possible that stopped watchers are pending \- for example, |
1277 | non-repeating timers are being stopped when they become pending \- but |
1303 | non-repeating timers are being stopped when they become pending \- but |
… | |
… | |
1296 | Returns the callback currently set on the watcher. |
1322 | Returns the callback currently set on the watcher. |
1297 | .IP "ev_cb_set (ev_TYPE *watcher, callback)" 4 |
1323 | .IP "ev_cb_set (ev_TYPE *watcher, callback)" 4 |
1298 | .IX Item "ev_cb_set (ev_TYPE *watcher, callback)" |
1324 | .IX Item "ev_cb_set (ev_TYPE *watcher, callback)" |
1299 | Change the callback. You can change the callback at virtually any time |
1325 | Change the callback. You can change the callback at virtually any time |
1300 | (modulo threads). |
1326 | (modulo threads). |
1301 | .IP "ev_set_priority (ev_TYPE *watcher, priority)" 4 |
1327 | .IP "ev_set_priority (ev_TYPE *watcher, int priority)" 4 |
1302 | .IX Item "ev_set_priority (ev_TYPE *watcher, priority)" |
1328 | .IX Item "ev_set_priority (ev_TYPE *watcher, int priority)" |
1303 | .PD 0 |
1329 | .PD 0 |
1304 | .IP "int ev_priority (ev_TYPE *watcher)" 4 |
1330 | .IP "int ev_priority (ev_TYPE *watcher)" 4 |
1305 | .IX Item "int ev_priority (ev_TYPE *watcher)" |
1331 | .IX Item "int ev_priority (ev_TYPE *watcher)" |
1306 | .PD |
1332 | .PD |
1307 | Set and query the priority of the watcher. The priority is a small |
1333 | Set and query the priority of the watcher. The priority is a small |
… | |
… | |
1337 | returns its \f(CW\*(C`revents\*(C'\fR bitset (as if its callback was invoked). If the |
1363 | returns its \f(CW\*(C`revents\*(C'\fR bitset (as if its callback was invoked). If the |
1338 | watcher isn't pending it does nothing and returns \f(CW0\fR. |
1364 | watcher isn't pending it does nothing and returns \f(CW0\fR. |
1339 | .Sp |
1365 | .Sp |
1340 | Sometimes it can be useful to \*(L"poll\*(R" a watcher instead of waiting for its |
1366 | Sometimes it can be useful to \*(L"poll\*(R" a watcher instead of waiting for its |
1341 | callback to be invoked, which can be accomplished with this function. |
1367 | callback to be invoked, which can be accomplished with this function. |
|
|
1368 | .IP "ev_feed_event (loop, ev_TYPE *watcher, int revents)" 4 |
|
|
1369 | .IX Item "ev_feed_event (loop, ev_TYPE *watcher, int revents)" |
|
|
1370 | Feeds the given event set into the event loop, as if the specified event |
|
|
1371 | had happened for the specified watcher (which must be a pointer to an |
|
|
1372 | initialised but not necessarily started event watcher). Obviously you must |
|
|
1373 | not free the watcher as long as it has pending events. |
|
|
1374 | .Sp |
|
|
1375 | Stopping the watcher, letting libev invoke it, or calling |
|
|
1376 | \&\f(CW\*(C`ev_clear_pending\*(C'\fR will clear the pending event, even if the watcher was |
|
|
1377 | not started in the first place. |
|
|
1378 | .Sp |
|
|
1379 | See also \f(CW\*(C`ev_feed_fd_event\*(C'\fR and \f(CW\*(C`ev_feed_signal_event\*(C'\fR for related |
|
|
1380 | functions that do not need a watcher. |
1342 | .SS "\s-1ASSOCIATING\s0 \s-1CUSTOM\s0 \s-1DATA\s0 \s-1WITH\s0 A \s-1WATCHER\s0" |
1381 | .SS "\s-1ASSOCIATING\s0 \s-1CUSTOM\s0 \s-1DATA\s0 \s-1WITH\s0 A \s-1WATCHER\s0" |
1343 | .IX Subsection "ASSOCIATING CUSTOM DATA WITH A WATCHER" |
1382 | .IX Subsection "ASSOCIATING CUSTOM DATA WITH A WATCHER" |
1344 | Each watcher has, by default, a member \f(CW\*(C`void *data\*(C'\fR that you can change |
1383 | Each watcher has, by default, a member \f(CW\*(C`void *data\*(C'\fR that you can change |
1345 | and read at any time: libev will completely ignore it. This can be used |
1384 | and read at any time: libev will completely ignore it. This can be used |
1346 | to associate arbitrary data with your watcher. If you need more data and |
1385 | to associate arbitrary data with your watcher. If you need more data and |
… | |
… | |
1957 | If the timer is repeating, either start it if necessary (with the |
1996 | If the timer is repeating, either start it if necessary (with the |
1958 | \&\f(CW\*(C`repeat\*(C'\fR value), or reset the running timer to the \f(CW\*(C`repeat\*(C'\fR value. |
1997 | \&\f(CW\*(C`repeat\*(C'\fR value), or reset the running timer to the \f(CW\*(C`repeat\*(C'\fR value. |
1959 | .Sp |
1998 | .Sp |
1960 | This sounds a bit complicated, see \*(L"Be smart about timeouts\*(R", above, for a |
1999 | This sounds a bit complicated, see \*(L"Be smart about timeouts\*(R", above, for a |
1961 | usage example. |
2000 | usage example. |
1962 | .IP "ev_timer_remaining (loop, ev_timer *)" 4 |
2001 | .IP "ev_tstamp ev_timer_remaining (loop, ev_timer *)" 4 |
1963 | .IX Item "ev_timer_remaining (loop, ev_timer *)" |
2002 | .IX Item "ev_tstamp ev_timer_remaining (loop, ev_timer *)" |
1964 | Returns the remaining time until a timer fires. If the timer is active, |
2003 | Returns the remaining time until a timer fires. If the timer is active, |
1965 | then this time is relative to the current event loop time, otherwise it's |
2004 | then this time is relative to the current event loop time, otherwise it's |
1966 | the timeout value currently configured. |
2005 | the timeout value currently configured. |
1967 | .Sp |
2006 | .Sp |
1968 | That is, after an \f(CW\*(C`ev_timer_set (w, 5, 7)\*(C'\fR, \f(CW\*(C`ev_timer_remaining\*(C'\fR returns |
2007 | That is, after an \f(CW\*(C`ev_timer_set (w, 5, 7)\*(C'\fR, \f(CW\*(C`ev_timer_remaining\*(C'\fR returns |
… | |
… | |
2217 | Signal watchers will trigger an event when the process receives a specific |
2256 | Signal watchers will trigger an event when the process receives a specific |
2218 | signal one or more times. Even though signals are very asynchronous, libev |
2257 | signal one or more times. Even though signals are very asynchronous, libev |
2219 | will try it's best to deliver signals synchronously, i.e. as part of the |
2258 | will try it's best to deliver signals synchronously, i.e. as part of the |
2220 | normal event processing, like any other event. |
2259 | normal event processing, like any other event. |
2221 | .PP |
2260 | .PP |
2222 | If you want signals asynchronously, just use \f(CW\*(C`sigaction\*(C'\fR as you would |
2261 | If you want signals to be delivered truly asynchronously, just use |
2223 | do without libev and forget about sharing the signal. You can even use |
2262 | \&\f(CW\*(C`sigaction\*(C'\fR as you would do without libev and forget about sharing |
2224 | \&\f(CW\*(C`ev_async\*(C'\fR from a signal handler to synchronously wake up an event loop. |
2263 | the signal. You can even use \f(CW\*(C`ev_async\*(C'\fR from a signal handler to |
|
|
2264 | synchronously wake up an event loop. |
2225 | .PP |
2265 | .PP |
2226 | You can configure as many watchers as you like per signal. Only when the |
2266 | You can configure as many watchers as you like for the same signal, but |
|
|
2267 | only within the same loop, i.e. you can watch for \f(CW\*(C`SIGINT\*(C'\fR in your |
|
|
2268 | default loop and for \f(CW\*(C`SIGIO\*(C'\fR in another loop, but you cannot watch for |
|
|
2269 | \&\f(CW\*(C`SIGINT\*(C'\fR in both the default loop and another loop at the same time. At |
|
|
2270 | the moment, \f(CW\*(C`SIGCHLD\*(C'\fR is permanently tied to the default loop. |
|
|
2271 | .PP |
2227 | first watcher gets started will libev actually register a signal handler |
2272 | When the first watcher gets started will libev actually register something |
2228 | with the kernel (thus it coexists with your own signal handlers as long as |
2273 | with the kernel (thus it coexists with your own signal handlers as long as |
2229 | you don't register any with libev for the same signal). Similarly, when |
2274 | you don't register any with libev for the same signal). |
2230 | the last signal watcher for a signal is stopped, libev will reset the |
|
|
2231 | signal handler to \s-1SIG_DFL\s0 (regardless of what it was set to before). |
|
|
2232 | .PP |
2275 | .PP |
2233 | If possible and supported, libev will install its handlers with |
2276 | If possible and supported, libev will install its handlers with |
2234 | \&\f(CW\*(C`SA_RESTART\*(C'\fR behaviour enabled, so system calls should not be unduly |
2277 | \&\f(CW\*(C`SA_RESTART\*(C'\fR (or equivalent) behaviour enabled, so system calls should |
2235 | interrupted. If you have a problem with system calls getting interrupted by |
2278 | not be unduly interrupted. If you have a problem with system calls getting |
2236 | signals you can block all signals in an \f(CW\*(C`ev_check\*(C'\fR watcher and unblock |
2279 | interrupted by signals you can block all signals in an \f(CW\*(C`ev_check\*(C'\fR watcher |
2237 | them in an \f(CW\*(C`ev_prepare\*(C'\fR watcher. |
2280 | and unblock them in an \f(CW\*(C`ev_prepare\*(C'\fR watcher. |
|
|
2281 | .PP |
|
|
2282 | \fIThe special problem of inheritance over fork/execve/pthread_create\fR |
|
|
2283 | .IX Subsection "The special problem of inheritance over fork/execve/pthread_create" |
|
|
2284 | .PP |
|
|
2285 | Both the signal mask (\f(CW\*(C`sigprocmask\*(C'\fR) and the signal disposition |
|
|
2286 | (\f(CW\*(C`sigaction\*(C'\fR) are unspecified after starting a signal watcher (and after |
|
|
2287 | stopping it again), that is, libev might or might not block the signal, |
|
|
2288 | and might or might not set or restore the installed signal handler. |
|
|
2289 | .PP |
|
|
2290 | While this does not matter for the signal disposition (libev never |
|
|
2291 | sets signals to \f(CW\*(C`SIG_IGN\*(C'\fR, so handlers will be reset to \f(CW\*(C`SIG_DFL\*(C'\fR on |
|
|
2292 | \&\f(CW\*(C`execve\*(C'\fR), this matters for the signal mask: many programs do not expect |
|
|
2293 | certain signals to be blocked. |
|
|
2294 | .PP |
|
|
2295 | This means that before calling \f(CW\*(C`exec\*(C'\fR (from the child) you should reset |
|
|
2296 | the signal mask to whatever \*(L"default\*(R" you expect (all clear is a good |
|
|
2297 | choice usually). |
|
|
2298 | .PP |
|
|
2299 | The simplest way to ensure that the signal mask is reset in the child is |
|
|
2300 | to install a fork handler with \f(CW\*(C`pthread_atfork\*(C'\fR that resets it. That will |
|
|
2301 | catch fork calls done by libraries (such as the libc) as well. |
|
|
2302 | .PP |
|
|
2303 | In current versions of libev, the signal will not be blocked indefinitely |
|
|
2304 | unless you use the \f(CW\*(C`signalfd\*(C'\fR \s-1API\s0 (\f(CW\*(C`EV_SIGNALFD\*(C'\fR). While this reduces |
|
|
2305 | the window of opportunity for problems, it will not go away, as libev |
|
|
2306 | \&\fIhas\fR to modify the signal mask, at least temporarily. |
|
|
2307 | .PP |
|
|
2308 | So I can't stress this enough: \fIIf you do not reset your signal mask when |
|
|
2309 | you expect it to be empty, you have a race condition in your code\fR. This |
|
|
2310 | is not a libev-specific thing, this is true for most event libraries. |
2238 | .PP |
2311 | .PP |
2239 | \fIWatcher-Specific Functions and Data Members\fR |
2312 | \fIWatcher-Specific Functions and Data Members\fR |
2240 | .IX Subsection "Watcher-Specific Functions and Data Members" |
2313 | .IX Subsection "Watcher-Specific Functions and Data Members" |
2241 | .IP "ev_signal_init (ev_signal *, callback, int signum)" 4 |
2314 | .IP "ev_signal_init (ev_signal *, callback, int signum)" 4 |
2242 | .IX Item "ev_signal_init (ev_signal *, callback, int signum)" |
2315 | .IX Item "ev_signal_init (ev_signal *, callback, int signum)" |
… | |
… | |
2287 | .PP |
2360 | .PP |
2288 | \fIProcess Interaction\fR |
2361 | \fIProcess Interaction\fR |
2289 | .IX Subsection "Process Interaction" |
2362 | .IX Subsection "Process Interaction" |
2290 | .PP |
2363 | .PP |
2291 | Libev grabs \f(CW\*(C`SIGCHLD\*(C'\fR as soon as the default event loop is |
2364 | Libev grabs \f(CW\*(C`SIGCHLD\*(C'\fR as soon as the default event loop is |
2292 | initialised. This is necessary to guarantee proper behaviour even if |
2365 | initialised. This is necessary to guarantee proper behaviour even if the |
2293 | the first child watcher is started after the child exits. The occurrence |
2366 | first child watcher is started after the child exits. The occurrence |
2294 | of \f(CW\*(C`SIGCHLD\*(C'\fR is recorded asynchronously, but child reaping is done |
2367 | of \f(CW\*(C`SIGCHLD\*(C'\fR is recorded asynchronously, but child reaping is done |
2295 | synchronously as part of the event loop processing. Libev always reaps all |
2368 | synchronously as part of the event loop processing. Libev always reaps all |
2296 | children, even ones not watched. |
2369 | children, even ones not watched. |
2297 | .PP |
2370 | .PP |
2298 | \fIOverriding the Built-In Processing\fR |
2371 | \fIOverriding the Built-In Processing\fR |
… | |
… | |
2310 | .IX Subsection "Stopping the Child Watcher" |
2383 | .IX Subsection "Stopping the Child Watcher" |
2311 | .PP |
2384 | .PP |
2312 | Currently, the child watcher never gets stopped, even when the |
2385 | Currently, the child watcher never gets stopped, even when the |
2313 | child terminates, so normally one needs to stop the watcher in the |
2386 | child terminates, so normally one needs to stop the watcher in the |
2314 | callback. Future versions of libev might stop the watcher automatically |
2387 | callback. Future versions of libev might stop the watcher automatically |
2315 | when a child exit is detected. |
2388 | when a child exit is detected (calling \f(CW\*(C`ev_child_stop\*(C'\fR twice is not a |
|
|
2389 | problem). |
2316 | .PP |
2390 | .PP |
2317 | \fIWatcher-Specific Functions and Data Members\fR |
2391 | \fIWatcher-Specific Functions and Data Members\fR |
2318 | .IX Subsection "Watcher-Specific Functions and Data Members" |
2392 | .IX Subsection "Watcher-Specific Functions and Data Members" |
2319 | .IP "ev_child_init (ev_child *, callback, int pid, int trace)" 4 |
2393 | .IP "ev_child_init (ev_child *, callback, int pid, int trace)" 4 |
2320 | .IX Item "ev_child_init (ev_child *, callback, int pid, int trace)" |
2394 | .IX Item "ev_child_init (ev_child *, callback, int pid, int trace)" |
… | |
… | |
3058 | .IX Subsection "Queueing" |
3132 | .IX Subsection "Queueing" |
3059 | .PP |
3133 | .PP |
3060 | \&\f(CW\*(C`ev_async\*(C'\fR does not support queueing of data in any way. The reason |
3134 | \&\f(CW\*(C`ev_async\*(C'\fR does not support queueing of data in any way. The reason |
3061 | is that the author does not know of a simple (or any) algorithm for a |
3135 | is that the author does not know of a simple (or any) algorithm for a |
3062 | multiple-writer-single-reader queue that works in all cases and doesn't |
3136 | multiple-writer-single-reader queue that works in all cases and doesn't |
3063 | need elaborate support such as pthreads. |
3137 | need elaborate support such as pthreads or unportable memory access |
|
|
3138 | semantics. |
3064 | .PP |
3139 | .PP |
3065 | That means that if you want to queue data, you have to provide your own |
3140 | That means that if you want to queue data, you have to provide your own |
3066 | queue. But at least I can tell you how to implement locking around your |
3141 | queue. But at least I can tell you how to implement locking around your |
3067 | queue: |
3142 | queue: |
3068 | .IP "queueing from a signal handler context" 4 |
3143 | .IP "queueing from a signal handler context" 4 |
… | |
… | |
3213 | \& /* doh, nothing entered */; |
3288 | \& /* doh, nothing entered */; |
3214 | \& } |
3289 | \& } |
3215 | \& |
3290 | \& |
3216 | \& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); |
3291 | \& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); |
3217 | .Ve |
3292 | .Ve |
3218 | .IP "ev_feed_event (struct ev_loop *, watcher *, int revents)" 4 |
|
|
3219 | .IX Item "ev_feed_event (struct ev_loop *, watcher *, int revents)" |
|
|
3220 | Feeds the given event set into the event loop, as if the specified event |
|
|
3221 | had happened for the specified watcher (which must be a pointer to an |
|
|
3222 | initialised but not necessarily started event watcher). |
|
|
3223 | .IP "ev_feed_fd_event (struct ev_loop *, int fd, int revents)" 4 |
3293 | .IP "ev_feed_fd_event (loop, int fd, int revents)" 4 |
3224 | .IX Item "ev_feed_fd_event (struct ev_loop *, int fd, int revents)" |
3294 | .IX Item "ev_feed_fd_event (loop, int fd, int revents)" |
3225 | Feed an event on the given fd, as if a file descriptor backend detected |
3295 | Feed an event on the given fd, as if a file descriptor backend detected |
3226 | the given events it. |
3296 | the given events it. |
3227 | .IP "ev_feed_signal_event (struct ev_loop *loop, int signum)" 4 |
3297 | .IP "ev_feed_signal_event (loop, int signum)" 4 |
3228 | .IX Item "ev_feed_signal_event (struct ev_loop *loop, int signum)" |
3298 | .IX Item "ev_feed_signal_event (loop, int signum)" |
3229 | Feed an event as if the given signal occurred (\f(CW\*(C`loop\*(C'\fR must be the default |
3299 | Feed an event as if the given signal occurred (\f(CW\*(C`loop\*(C'\fR must be the default |
3230 | loop!). |
3300 | loop!). |
3231 | .SH "LIBEVENT EMULATION" |
3301 | .SH "LIBEVENT EMULATION" |
3232 | .IX Header "LIBEVENT EMULATION" |
3302 | .IX Header "LIBEVENT EMULATION" |
3233 | Libev offers a compatibility emulation layer for libevent. It cannot |
3303 | Libev offers a compatibility emulation layer for libevent. It cannot |
… | |
… | |
3302 | All of those classes have these methods: |
3372 | All of those classes have these methods: |
3303 | .RS 4 |
3373 | .RS 4 |
3304 | .IP "ev::TYPE::TYPE ()" 4 |
3374 | .IP "ev::TYPE::TYPE ()" 4 |
3305 | .IX Item "ev::TYPE::TYPE ()" |
3375 | .IX Item "ev::TYPE::TYPE ()" |
3306 | .PD 0 |
3376 | .PD 0 |
3307 | .IP "ev::TYPE::TYPE (struct ev_loop *)" 4 |
3377 | .IP "ev::TYPE::TYPE (loop)" 4 |
3308 | .IX Item "ev::TYPE::TYPE (struct ev_loop *)" |
3378 | .IX Item "ev::TYPE::TYPE (loop)" |
3309 | .IP "ev::TYPE::~TYPE" 4 |
3379 | .IP "ev::TYPE::~TYPE" 4 |
3310 | .IX Item "ev::TYPE::~TYPE" |
3380 | .IX Item "ev::TYPE::~TYPE" |
3311 | .PD |
3381 | .PD |
3312 | The constructor (optionally) takes an event loop to associate the watcher |
3382 | The constructor (optionally) takes an event loop to associate the watcher |
3313 | with. If it is omitted, it will use \f(CW\*(C`EV_DEFAULT\*(C'\fR. |
3383 | with. If it is omitted, it will use \f(CW\*(C`EV_DEFAULT\*(C'\fR. |
… | |
… | |
3392 | .Sp |
3462 | .Sp |
3393 | .Vb 2 |
3463 | .Vb 2 |
3394 | \& static void io_cb (ev::io &w, int revents) { } |
3464 | \& static void io_cb (ev::io &w, int revents) { } |
3395 | \& iow.set <io_cb> (); |
3465 | \& iow.set <io_cb> (); |
3396 | .Ve |
3466 | .Ve |
3397 | .IP "w\->set (struct ev_loop *)" 4 |
3467 | .IP "w\->set (loop)" 4 |
3398 | .IX Item "w->set (struct ev_loop *)" |
3468 | .IX Item "w->set (loop)" |
3399 | Associates a different \f(CW\*(C`struct ev_loop\*(C'\fR with this watcher. You can only |
3469 | Associates a different \f(CW\*(C`struct ev_loop\*(C'\fR with this watcher. You can only |
3400 | do this when the watcher is inactive (and not pending either). |
3470 | do this when the watcher is inactive (and not pending either). |
3401 | .IP "w\->set ([arguments])" 4 |
3471 | .IP "w\->set ([arguments])" 4 |
3402 | .IX Item "w->set ([arguments])" |
3472 | .IX Item "w->set ([arguments])" |
3403 | Basically the same as \f(CW\*(C`ev_TYPE_set\*(C'\fR, with the same arguments. Must be |
3473 | Basically the same as \f(CW\*(C`ev_TYPE_set\*(C'\fR, with the same arguments. Must be |
… | |
… | |
3486 | be found at <http://proj.llucax.com.ar/wiki/evd>. |
3556 | be found at <http://proj.llucax.com.ar/wiki/evd>. |
3487 | .IP "Ocaml" 4 |
3557 | .IP "Ocaml" 4 |
3488 | .IX Item "Ocaml" |
3558 | .IX Item "Ocaml" |
3489 | Erkki Seppala has written Ocaml bindings for libev, to be found at |
3559 | Erkki Seppala has written Ocaml bindings for libev, to be found at |
3490 | <http://modeemi.cs.tut.fi/~flux/software/ocaml\-ev/>. |
3560 | <http://modeemi.cs.tut.fi/~flux/software/ocaml\-ev/>. |
|
|
3561 | .IP "Lua" 4 |
|
|
3562 | .IX Item "Lua" |
|
|
3563 | Brian Maher has written a partial interface to libev |
|
|
3564 | for lua (only \f(CW\*(C`ev_io\*(C'\fR and \f(CW\*(C`ev_timer\*(C'\fR), to be found at |
|
|
3565 | <http://github.com/brimworks/lua\-ev>. |
3491 | .SH "MACRO MAGIC" |
3566 | .SH "MACRO MAGIC" |
3492 | .IX Header "MACRO MAGIC" |
3567 | .IX Header "MACRO MAGIC" |
3493 | Libev can be compiled with a variety of options, the most fundamental |
3568 | Libev can be compiled with a variety of options, the most fundamental |
3494 | of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most) |
3569 | of which is \f(CW\*(C`EV_MULTIPLICITY\*(C'\fR. This option determines whether (most) |
3495 | functions and callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument. |
3570 | functions and callbacks have an initial \f(CW\*(C`struct ev_loop *\*(C'\fR argument. |
… | |
… | |
3671 | keeps libev from including \fIconfig.h\fR, and it also defines dummy |
3746 | keeps libev from including \fIconfig.h\fR, and it also defines dummy |
3672 | implementations for some libevent functions (such as logging, which is not |
3747 | implementations for some libevent functions (such as logging, which is not |
3673 | supported). It will also not define any of the structs usually found in |
3748 | supported). It will also not define any of the structs usually found in |
3674 | \&\fIevent.h\fR that are not directly supported by the libev core alone. |
3749 | \&\fIevent.h\fR that are not directly supported by the libev core alone. |
3675 | .Sp |
3750 | .Sp |
3676 | In stanbdalone mode, libev will still try to automatically deduce the |
3751 | In standalone mode, libev will still try to automatically deduce the |
3677 | configuration, but has to be more conservative. |
3752 | configuration, but has to be more conservative. |
3678 | .IP "\s-1EV_USE_MONOTONIC\s0" 4 |
3753 | .IP "\s-1EV_USE_MONOTONIC\s0" 4 |
3679 | .IX Item "EV_USE_MONOTONIC" |
3754 | .IX Item "EV_USE_MONOTONIC" |
3680 | If defined to be \f(CW1\fR, libev will try to detect the availability of the |
3755 | If defined to be \f(CW1\fR, libev will try to detect the availability of the |
3681 | monotonic clock option at both compile time and runtime. Otherwise no |
3756 | monotonic clock option at both compile time and runtime. Otherwise no |
… | |
… | |
3737 | wants osf handles on win32 (this is the case when the select to |
3812 | wants osf handles on win32 (this is the case when the select to |
3738 | be used is the winsock select). This means that it will call |
3813 | be used is the winsock select). This means that it will call |
3739 | \&\f(CW\*(C`_get_osfhandle\*(C'\fR on the fd to convert it to an \s-1OS\s0 handle. Otherwise, |
3814 | \&\f(CW\*(C`_get_osfhandle\*(C'\fR on the fd to convert it to an \s-1OS\s0 handle. Otherwise, |
3740 | it is assumed that all these functions actually work on fds, even |
3815 | it is assumed that all these functions actually work on fds, even |
3741 | on win32. Should not be defined on non\-win32 platforms. |
3816 | on win32. Should not be defined on non\-win32 platforms. |
3742 | .IP "\s-1EV_FD_TO_WIN32_HANDLE\s0" 4 |
3817 | .IP "\s-1EV_FD_TO_WIN32_HANDLE\s0(fd)" 4 |
3743 | .IX Item "EV_FD_TO_WIN32_HANDLE" |
3818 | .IX Item "EV_FD_TO_WIN32_HANDLE(fd)" |
3744 | If \f(CW\*(C`EV_SELECT_IS_WINSOCKET\*(C'\fR is enabled, then libev needs a way to map |
3819 | If \f(CW\*(C`EV_SELECT_IS_WINSOCKET\*(C'\fR is enabled, then libev needs a way to map |
3745 | file descriptors to socket handles. When not defining this symbol (the |
3820 | file descriptors to socket handles. When not defining this symbol (the |
3746 | default), then libev will call \f(CW\*(C`_get_osfhandle\*(C'\fR, which is usually |
3821 | default), then libev will call \f(CW\*(C`_get_osfhandle\*(C'\fR, which is usually |
3747 | correct. In some cases, programs use their own file descriptor management, |
3822 | correct. In some cases, programs use their own file descriptor management, |
3748 | in which case they can provide this function to map fds to socket handles. |
3823 | in which case they can provide this function to map fds to socket handles. |
|
|
3824 | .IP "\s-1EV_WIN32_HANDLE_TO_FD\s0(handle)" 4 |
|
|
3825 | .IX Item "EV_WIN32_HANDLE_TO_FD(handle)" |
|
|
3826 | If \f(CW\*(C`EV_SELECT_IS_WINSOCKET\*(C'\fR then libev maps handles to file descriptors |
|
|
3827 | using the standard \f(CW\*(C`_open_osfhandle\*(C'\fR function. For programs implementing |
|
|
3828 | their own fd to handle mapping, overwriting this function makes it easier |
|
|
3829 | to do so. This can be done by defining this macro to an appropriate value. |
|
|
3830 | .IP "\s-1EV_WIN32_CLOSE_FD\s0(fd)" 4 |
|
|
3831 | .IX Item "EV_WIN32_CLOSE_FD(fd)" |
|
|
3832 | If programs implement their own fd to handle mapping on win32, then this |
|
|
3833 | macro can be used to override the \f(CW\*(C`close\*(C'\fR function, useful to unregister |
|
|
3834 | file descriptors again. Note that the replacement function has to close |
|
|
3835 | the underlying \s-1OS\s0 handle. |
3749 | .IP "\s-1EV_USE_POLL\s0" 4 |
3836 | .IP "\s-1EV_USE_POLL\s0" 4 |
3750 | .IX Item "EV_USE_POLL" |
3837 | .IX Item "EV_USE_POLL" |
3751 | If defined to be \f(CW1\fR, libev will compile in support for the \f(CW\*(C`poll\*(C'\fR(2) |
3838 | If defined to be \f(CW1\fR, libev will compile in support for the \f(CW\*(C`poll\*(C'\fR(2) |
3752 | backend. Otherwise it will be enabled on non\-win32 platforms. It |
3839 | backend. Otherwise it will be enabled on non\-win32 platforms. It |
3753 | takes precedence over select. |
3840 | takes precedence over select. |
… | |
… | |
3880 | .Sp |
3967 | .Sp |
3881 | Defining \f(CW\*(C`EV_MINIMAL\*(C'\fR to \f(CW2\fR will additionally reduce the core \s-1API\s0 to |
3968 | Defining \f(CW\*(C`EV_MINIMAL\*(C'\fR to \f(CW2\fR will additionally reduce the core \s-1API\s0 to |
3882 | provide a bare-bones event library. See \f(CW\*(C`ev.h\*(C'\fR for details on what parts |
3969 | provide a bare-bones event library. See \f(CW\*(C`ev.h\*(C'\fR for details on what parts |
3883 | of the \s-1API\s0 are still available, and do not complain if this subset changes |
3970 | of the \s-1API\s0 are still available, and do not complain if this subset changes |
3884 | over time. |
3971 | over time. |
|
|
3972 | .IP "\s-1EV_NSIG\s0" 4 |
|
|
3973 | .IX Item "EV_NSIG" |
|
|
3974 | The highest supported signal number, +1 (or, the number of |
|
|
3975 | signals): Normally, libev tries to deduce the maximum number of signals |
|
|
3976 | automatically, but sometimes this fails, in which case it can be |
|
|
3977 | specified. Also, using a lower number than detected (\f(CW32\fR should be |
|
|
3978 | good for about any system in existance) can save some memory, as libev |
|
|
3979 | statically allocates some 12\-24 bytes per signal number. |
3885 | .IP "\s-1EV_PID_HASHSIZE\s0" 4 |
3980 | .IP "\s-1EV_PID_HASHSIZE\s0" 4 |
3886 | .IX Item "EV_PID_HASHSIZE" |
3981 | .IX Item "EV_PID_HASHSIZE" |
3887 | \&\f(CW\*(C`ev_child\*(C'\fR watchers use a small hash table to distribute workload by |
3982 | \&\f(CW\*(C`ev_child\*(C'\fR watchers use a small hash table to distribute workload by |
3888 | pid. The default size is \f(CW16\fR (or \f(CW1\fR with \f(CW\*(C`EV_MINIMAL\*(C'\fR), usually more |
3983 | pid. The default size is \f(CW16\fR (or \f(CW1\fR with \f(CW\*(C`EV_MINIMAL\*(C'\fR), usually more |
3889 | than enough. If you need to manage thousands of children you might want to |
3984 | than enough. If you need to manage thousands of children you might want to |