… | |
… | |
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-27" "libev-3.8" "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" |
… | |
… | |
246 | 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) |
247 | configuration will be described, which supports multiple event loops. For |
247 | configuration will be described, which supports multiple event loops. For |
248 | more info about various configuration options please have a look at |
248 | more info about various configuration options please have a look at |
249 | \&\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 |
250 | 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 |
251 | 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 |
252 | this argument. |
252 | this argument. |
253 | .SS "\s-1TIME\s0 \s-1REPRESENTATION\s0" |
253 | .SS "\s-1TIME\s0 \s-1REPRESENTATION\s0" |
254 | .IX Subsection "TIME REPRESENTATION" |
254 | .IX Subsection "TIME REPRESENTATION" |
255 | Libev represents time as a single floating point number, representing |
255 | Libev represents time as a single floating point number, representing |
256 | 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 |
… | |
… | |
486 | .IX Item "EVFLAG_NOINOTIFY" |
486 | .IX Item "EVFLAG_NOINOTIFY" |
487 | When this flag is specified, then libev will not attempt to use the |
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 |
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 |
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. |
490 | otherwise each loop using \f(CW\*(C`ev_stat\*(C'\fR watchers consumes one inotify handle. |
491 | .ie n .IP """EVFLAG_NOSIGNALFD""" 4 |
491 | .ie n .IP """EVFLAG_SIGNALFD""" 4 |
492 | .el .IP "\f(CWEVFLAG_NOSIGNALFD\fR" 4 |
492 | .el .IP "\f(CWEVFLAG_SIGNALFD\fR" 4 |
493 | .IX Item "EVFLAG_NOSIGNALFD" |
493 | .IX Item "EVFLAG_SIGNALFD" |
494 | When this flag is specified, then libev will not attempt to use the |
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 is |
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 | probably only useful to work around any bugs in libev. Consequently, this |
496 | delivers signals synchronously, which makes it both faster and might make |
497 | flag might go away once the signalfd functionality is considered stable, |
497 | it possible to get the queued signal data. It can also simplify signal |
498 | so it's useful mostly in environment variables and not in program code. |
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. |
499 | .ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4 |
504 | .ie n .IP """EVBACKEND_SELECT"" (value 1, portable select backend)" 4 |
500 | .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 |
501 | .IX Item "EVBACKEND_SELECT (value 1, portable select backend)" |
506 | .IX Item "EVBACKEND_SELECT (value 1, portable select backend)" |
502 | 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 |
503 | 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, |
… | |
… | |
528 | 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 |
529 | \&\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. |
530 | .ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4 |
535 | .ie n .IP """EVBACKEND_EPOLL"" (value 4, Linux)" 4 |
531 | .el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4 |
536 | .el .IP "\f(CWEVBACKEND_EPOLL\fR (value 4, Linux)" 4 |
532 | .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 |
533 | 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, |
534 | but it scales phenomenally better. While poll and select usually scale |
542 | but it scales phenomenally better. While poll and select usually scale |
535 | 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), |
536 | epoll scales either O(1) or O(active_fds). |
544 | epoll scales either O(1) or O(active_fds). |
537 | .Sp |
545 | .Sp |
… | |
… | |
714 | as signal and child watchers) would need to be stopped manually. |
722 | as signal and child watchers) would need to be stopped manually. |
715 | .Sp |
723 | .Sp |
716 | 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 |
717 | 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 |
718 | 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 |
719 | \&\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. |
720 | .IP "ev_loop_destroy (loop)" 4 |
728 | .IP "ev_loop_destroy (loop)" 4 |
721 | .IX Item "ev_loop_destroy (loop)" |
729 | .IX Item "ev_loop_destroy (loop)" |
722 | 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 |
723 | earlier call to \f(CW\*(C`ev_loop_new\*(C'\fR. |
731 | earlier call to \f(CW\*(C`ev_loop_new\*(C'\fR. |
724 | .IP "ev_default_fork ()" 4 |
732 | .IP "ev_default_fork ()" 4 |
… | |
… | |
821 | 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 |
822 | 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). |
823 | .IP "ev_loop (loop, int flags)" 4 |
831 | .IP "ev_loop (loop, int flags)" 4 |
824 | .IX Item "ev_loop (loop, int flags)" |
832 | .IX Item "ev_loop (loop, int flags)" |
825 | 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 |
826 | 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 |
827 | events. |
835 | handling events. |
828 | .Sp |
836 | .Sp |
829 | 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 |
830 | 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. |
831 | .Sp |
839 | .Sp |
832 | 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 |
… | |
… | |
910 | .PD |
918 | .PD |
911 | 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 |
912 | 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 |
913 | 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. |
914 | .Sp |
922 | .Sp |
915 | 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 |
916 | 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 |
917 | stopping it. |
926 | before stopping it. |
918 | .Sp |
927 | .Sp |
919 | 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 |
920 | 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 |
921 | 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 |
922 | 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 |
… | |
… | |
1040 | .Sp |
1049 | .Sp |
1041 | While event loop modifications are allowed between invocations of |
1050 | While event loop modifications are allowed between invocations of |
1042 | \&\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 |
1043 | 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 |
1044 | 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 |
1045 | 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 |
1046 | to take note of any changes you made. |
1055 | to take note of any changes you made. |
1047 | .Sp |
1056 | .Sp |
1048 | 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 |
1049 | 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. |
1050 | .Sp |
1059 | .Sp |
… | |
… | |
1245 | .Vb 3 |
1254 | .Vb 3 |
1246 | \& ev_io w; |
1255 | \& ev_io w; |
1247 | \& ev_init (&w, my_cb); |
1256 | \& ev_init (&w, my_cb); |
1248 | \& ev_io_set (&w, STDIN_FILENO, EV_READ); |
1257 | \& ev_io_set (&w, STDIN_FILENO, EV_READ); |
1249 | .Ve |
1258 | .Ve |
1250 | .ie n .IP """ev_TYPE_set"" (ev_TYPE *, [args])" 4 |
1259 | .ie n .IP """ev_TYPE_set"" (ev_TYPE *watcher, [args])" 4 |
1251 | .el .IP "\f(CWev_TYPE_set\fR (ev_TYPE *, [args])" 4 |
1260 | .el .IP "\f(CWev_TYPE_set\fR (ev_TYPE *watcher, [args])" 4 |
1252 | .IX Item "ev_TYPE_set (ev_TYPE *, [args])" |
1261 | .IX Item "ev_TYPE_set (ev_TYPE *watcher, [args])" |
1253 | 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 |
1254 | 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 |
1255 | 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 |
1256 | 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 |
1257 | difference to the \f(CW\*(C`ev_init\*(C'\fR macro). |
1266 | difference to the \f(CW\*(C`ev_init\*(C'\fR macro). |
… | |
… | |
1270 | 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. |
1271 | .Sp |
1280 | .Sp |
1272 | .Vb 1 |
1281 | .Vb 1 |
1273 | \& ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ); |
1282 | \& ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ); |
1274 | .Ve |
1283 | .Ve |
1275 | .ie n .IP """ev_TYPE_start"" (loop *, ev_TYPE *watcher)" 4 |
1284 | .ie n .IP """ev_TYPE_start"" (loop, ev_TYPE *watcher)" 4 |
1276 | .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 |
1277 | .IX Item "ev_TYPE_start (loop *, ev_TYPE *watcher)" |
1286 | .IX Item "ev_TYPE_start (loop, ev_TYPE *watcher)" |
1278 | Starts (activates) the given watcher. Only active watchers will receive |
1287 | Starts (activates) the given watcher. Only active watchers will receive |
1279 | events. If the watcher is already active nothing will happen. |
1288 | events. If the watcher is already active nothing will happen. |
1280 | .Sp |
1289 | .Sp |
1281 | 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 |
1282 | whole section. |
1291 | whole section. |
1283 | .Sp |
1292 | .Sp |
1284 | .Vb 1 |
1293 | .Vb 1 |
1285 | \& ev_io_start (EV_DEFAULT_UC, &w); |
1294 | \& ev_io_start (EV_DEFAULT_UC, &w); |
1286 | .Ve |
1295 | .Ve |
1287 | .ie n .IP """ev_TYPE_stop"" (loop *, ev_TYPE *watcher)" 4 |
1296 | .ie n .IP """ev_TYPE_stop"" (loop, ev_TYPE *watcher)" 4 |
1288 | .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 |
1289 | .IX Item "ev_TYPE_stop (loop *, ev_TYPE *watcher)" |
1298 | .IX Item "ev_TYPE_stop (loop, ev_TYPE *watcher)" |
1290 | 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 |
1291 | the watcher was active or not). |
1300 | the watcher was active or not). |
1292 | .Sp |
1301 | .Sp |
1293 | It is possible that stopped watchers are pending \- for example, |
1302 | It is possible that stopped watchers are pending \- for example, |
1294 | non-repeating timers are being stopped when they become pending \- but |
1303 | non-repeating timers are being stopped when they become pending \- but |
… | |
… | |
1313 | Returns the callback currently set on the watcher. |
1322 | Returns the callback currently set on the watcher. |
1314 | .IP "ev_cb_set (ev_TYPE *watcher, callback)" 4 |
1323 | .IP "ev_cb_set (ev_TYPE *watcher, callback)" 4 |
1315 | .IX Item "ev_cb_set (ev_TYPE *watcher, callback)" |
1324 | .IX Item "ev_cb_set (ev_TYPE *watcher, callback)" |
1316 | 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 |
1317 | (modulo threads). |
1326 | (modulo threads). |
1318 | .IP "ev_set_priority (ev_TYPE *watcher, priority)" 4 |
1327 | .IP "ev_set_priority (ev_TYPE *watcher, int priority)" 4 |
1319 | .IX Item "ev_set_priority (ev_TYPE *watcher, priority)" |
1328 | .IX Item "ev_set_priority (ev_TYPE *watcher, int priority)" |
1320 | .PD 0 |
1329 | .PD 0 |
1321 | .IP "int ev_priority (ev_TYPE *watcher)" 4 |
1330 | .IP "int ev_priority (ev_TYPE *watcher)" 4 |
1322 | .IX Item "int ev_priority (ev_TYPE *watcher)" |
1331 | .IX Item "int ev_priority (ev_TYPE *watcher)" |
1323 | .PD |
1332 | .PD |
1324 | 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 |
… | |
… | |
1354 | 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 |
1355 | 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. |
1356 | .Sp |
1365 | .Sp |
1357 | 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 |
1358 | 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. |
1359 | .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" |
1360 | .IX Subsection "ASSOCIATING CUSTOM DATA WITH A WATCHER" |
1382 | .IX Subsection "ASSOCIATING CUSTOM DATA WITH A WATCHER" |
1361 | 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 |
1362 | 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 |
1363 | 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 |
… | |
… | |
1974 | 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 |
1975 | \&\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. |
1976 | .Sp |
1998 | .Sp |
1977 | 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 |
1978 | usage example. |
2000 | usage example. |
1979 | .IP "ev_timer_remaining (loop, ev_timer *)" 4 |
2001 | .IP "ev_tstamp ev_timer_remaining (loop, ev_timer *)" 4 |
1980 | .IX Item "ev_timer_remaining (loop, ev_timer *)" |
2002 | .IX Item "ev_tstamp ev_timer_remaining (loop, ev_timer *)" |
1981 | 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, |
1982 | 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 |
1983 | the timeout value currently configured. |
2005 | the timeout value currently configured. |
1984 | .Sp |
2006 | .Sp |
1985 | 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 |
… | |
… | |
2249 | .PP |
2271 | .PP |
2250 | When the first watcher gets started will libev actually register something |
2272 | When the first watcher gets started will libev actually register something |
2251 | 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 |
2252 | you don't register any with libev for the same signal). |
2274 | you don't register any with libev for the same signal). |
2253 | .PP |
2275 | .PP |
2254 | Both the signal mask state (\f(CW\*(C`sigprocmask\*(C'\fR) and the signal handler state |
|
|
2255 | (\f(CW\*(C`sigaction\*(C'\fR) are unspecified after starting a signal watcher (and after |
|
|
2256 | sotpping it again), that is, libev might or might not block the signal, |
|
|
2257 | and might or might not set or restore the installed signal handler. |
|
|
2258 | .PP |
|
|
2259 | If possible and supported, libev will install its handlers with |
2276 | If possible and supported, libev will install its handlers with |
2260 | \&\f(CW\*(C`SA_RESTART\*(C'\fR (or equivalent) behaviour enabled, so system calls should |
2277 | \&\f(CW\*(C`SA_RESTART\*(C'\fR (or equivalent) behaviour enabled, so system calls should |
2261 | not be unduly interrupted. If you have a problem with system calls getting |
2278 | not be unduly interrupted. If you have a problem with system calls getting |
2262 | interrupted by signals you can block all signals in an \f(CW\*(C`ev_check\*(C'\fR watcher |
2279 | interrupted by signals you can block all signals in an \f(CW\*(C`ev_check\*(C'\fR watcher |
2263 | and unblock 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. |
2264 | .PP |
2311 | .PP |
2265 | \fIWatcher-Specific Functions and Data Members\fR |
2312 | \fIWatcher-Specific Functions and Data Members\fR |
2266 | .IX Subsection "Watcher-Specific Functions and Data Members" |
2313 | .IX Subsection "Watcher-Specific Functions and Data Members" |
2267 | .IP "ev_signal_init (ev_signal *, callback, int signum)" 4 |
2314 | .IP "ev_signal_init (ev_signal *, callback, int signum)" 4 |
2268 | .IX Item "ev_signal_init (ev_signal *, callback, int signum)" |
2315 | .IX Item "ev_signal_init (ev_signal *, callback, int signum)" |
… | |
… | |
3085 | .IX Subsection "Queueing" |
3132 | .IX Subsection "Queueing" |
3086 | .PP |
3133 | .PP |
3087 | \&\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 |
3088 | 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 |
3089 | 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 |
3090 | need elaborate support such as pthreads. |
3137 | need elaborate support such as pthreads or unportable memory access |
|
|
3138 | semantics. |
3091 | .PP |
3139 | .PP |
3092 | 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 |
3093 | 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 |
3094 | queue: |
3142 | queue: |
3095 | .IP "queueing from a signal handler context" 4 |
3143 | .IP "queueing from a signal handler context" 4 |
… | |
… | |
3240 | \& /* doh, nothing entered */; |
3288 | \& /* doh, nothing entered */; |
3241 | \& } |
3289 | \& } |
3242 | \& |
3290 | \& |
3243 | \& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); |
3291 | \& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0); |
3244 | .Ve |
3292 | .Ve |
3245 | .IP "ev_feed_event (struct ev_loop *, watcher *, int revents)" 4 |
|
|
3246 | .IX Item "ev_feed_event (struct ev_loop *, watcher *, int revents)" |
|
|
3247 | Feeds the given event set into the event loop, as if the specified event |
|
|
3248 | had happened for the specified watcher (which must be a pointer to an |
|
|
3249 | initialised but not necessarily started event watcher). |
|
|
3250 | .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 |
3251 | .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)" |
3252 | 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 |
3253 | the given events it. |
3296 | the given events it. |
3254 | .IP "ev_feed_signal_event (struct ev_loop *loop, int signum)" 4 |
3297 | .IP "ev_feed_signal_event (loop, int signum)" 4 |
3255 | .IX Item "ev_feed_signal_event (struct ev_loop *loop, int signum)" |
3298 | .IX Item "ev_feed_signal_event (loop, int signum)" |
3256 | 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 |
3257 | loop!). |
3300 | loop!). |
3258 | .SH "LIBEVENT EMULATION" |
3301 | .SH "LIBEVENT EMULATION" |
3259 | .IX Header "LIBEVENT EMULATION" |
3302 | .IX Header "LIBEVENT EMULATION" |
3260 | Libev offers a compatibility emulation layer for libevent. It cannot |
3303 | Libev offers a compatibility emulation layer for libevent. It cannot |
… | |
… | |
3329 | All of those classes have these methods: |
3372 | All of those classes have these methods: |
3330 | .RS 4 |
3373 | .RS 4 |
3331 | .IP "ev::TYPE::TYPE ()" 4 |
3374 | .IP "ev::TYPE::TYPE ()" 4 |
3332 | .IX Item "ev::TYPE::TYPE ()" |
3375 | .IX Item "ev::TYPE::TYPE ()" |
3333 | .PD 0 |
3376 | .PD 0 |
3334 | .IP "ev::TYPE::TYPE (struct ev_loop *)" 4 |
3377 | .IP "ev::TYPE::TYPE (loop)" 4 |
3335 | .IX Item "ev::TYPE::TYPE (struct ev_loop *)" |
3378 | .IX Item "ev::TYPE::TYPE (loop)" |
3336 | .IP "ev::TYPE::~TYPE" 4 |
3379 | .IP "ev::TYPE::~TYPE" 4 |
3337 | .IX Item "ev::TYPE::~TYPE" |
3380 | .IX Item "ev::TYPE::~TYPE" |
3338 | .PD |
3381 | .PD |
3339 | The constructor (optionally) takes an event loop to associate the watcher |
3382 | The constructor (optionally) takes an event loop to associate the watcher |
3340 | 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. |
… | |
… | |
3419 | .Sp |
3462 | .Sp |
3420 | .Vb 2 |
3463 | .Vb 2 |
3421 | \& static void io_cb (ev::io &w, int revents) { } |
3464 | \& static void io_cb (ev::io &w, int revents) { } |
3422 | \& iow.set <io_cb> (); |
3465 | \& iow.set <io_cb> (); |
3423 | .Ve |
3466 | .Ve |
3424 | .IP "w\->set (struct ev_loop *)" 4 |
3467 | .IP "w\->set (loop)" 4 |
3425 | .IX Item "w->set (struct ev_loop *)" |
3468 | .IX Item "w->set (loop)" |
3426 | 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 |
3427 | do this when the watcher is inactive (and not pending either). |
3470 | do this when the watcher is inactive (and not pending either). |
3428 | .IP "w\->set ([arguments])" 4 |
3471 | .IP "w\->set ([arguments])" 4 |
3429 | .IX Item "w->set ([arguments])" |
3472 | .IX Item "w->set ([arguments])" |
3430 | 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 |
… | |
… | |
3769 | 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 |
3770 | 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 |
3771 | \&\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, |
3772 | 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 |
3773 | on win32. Should not be defined on non\-win32 platforms. |
3816 | on win32. Should not be defined on non\-win32 platforms. |
3774 | .IP "\s-1EV_FD_TO_WIN32_HANDLE\s0" 4 |
3817 | .IP "\s-1EV_FD_TO_WIN32_HANDLE\s0(fd)" 4 |
3775 | .IX Item "EV_FD_TO_WIN32_HANDLE" |
3818 | .IX Item "EV_FD_TO_WIN32_HANDLE(fd)" |
3776 | 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 |
3777 | file descriptors to socket handles. When not defining this symbol (the |
3820 | file descriptors to socket handles. When not defining this symbol (the |
3778 | 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 |
3779 | correct. In some cases, programs use their own file descriptor management, |
3822 | correct. In some cases, programs use their own file descriptor management, |
3780 | 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. |
3781 | .IP "\s-1EV_USE_POLL\s0" 4 |
3836 | .IP "\s-1EV_USE_POLL\s0" 4 |
3782 | .IX Item "EV_USE_POLL" |
3837 | .IX Item "EV_USE_POLL" |
3783 | 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) |
3784 | backend. Otherwise it will be enabled on non\-win32 platforms. It |
3839 | backend. Otherwise it will be enabled on non\-win32 platforms. It |
3785 | takes precedence over select. |
3840 | takes precedence over select. |