… | |
… | |
505 | =item ev_loop_fork (loop) |
505 | =item ev_loop_fork (loop) |
506 | |
506 | |
507 | Like C<ev_default_fork>, but acts on an event loop created by |
507 | Like C<ev_default_fork>, but acts on an event loop created by |
508 | C<ev_loop_new>. Yes, you have to call this on every allocated event loop |
508 | C<ev_loop_new>. Yes, you have to call this on every allocated event loop |
509 | after fork, and how you do this is entirely your own problem. |
509 | after fork, and how you do this is entirely your own problem. |
|
|
510 | |
|
|
511 | =item int ev_is_default_loop (loop) |
|
|
512 | |
|
|
513 | Returns true when the given loop actually is the default loop, false otherwise. |
510 | |
514 | |
511 | =item unsigned int ev_loop_count (loop) |
515 | =item unsigned int ev_loop_count (loop) |
512 | |
516 | |
513 | Returns the count of loop iterations for the loop, which is identical to |
517 | Returns the count of loop iterations for the loop, which is identical to |
514 | the number of times libev did poll for new events. It starts at C<0> and |
518 | the number of times libev did poll for new events. It starts at C<0> and |
… | |
… | |
1152 | configure a timer to trigger every 10 seconds, then it will trigger at |
1156 | configure a timer to trigger every 10 seconds, then it will trigger at |
1153 | exactly 10 second intervals. If, however, your program cannot keep up with |
1157 | exactly 10 second intervals. If, however, your program cannot keep up with |
1154 | the timer (because it takes longer than those 10 seconds to do stuff) the |
1158 | the timer (because it takes longer than those 10 seconds to do stuff) the |
1155 | timer will not fire more than once per event loop iteration. |
1159 | timer will not fire more than once per event loop iteration. |
1156 | |
1160 | |
1157 | =item ev_timer_again (loop) |
1161 | =item ev_timer_again (loop, ev_timer *) |
1158 | |
1162 | |
1159 | This will act as if the timer timed out and restart it again if it is |
1163 | This will act as if the timer timed out and restart it again if it is |
1160 | repeating. The exact semantics are: |
1164 | repeating. The exact semantics are: |
1161 | |
1165 | |
1162 | If the timer is pending, its pending status is cleared. |
1166 | If the timer is pending, its pending status is cleared. |
… | |
… | |
1271 | In this configuration the watcher triggers an event at the wallclock time |
1275 | In this configuration the watcher triggers an event at the wallclock time |
1272 | C<at> and doesn't repeat. It will not adjust when a time jump occurs, |
1276 | C<at> and doesn't repeat. It will not adjust when a time jump occurs, |
1273 | that is, if it is to be run at January 1st 2011 then it will run when the |
1277 | that is, if it is to be run at January 1st 2011 then it will run when the |
1274 | system time reaches or surpasses this time. |
1278 | system time reaches or surpasses this time. |
1275 | |
1279 | |
1276 | =item * non-repeating interval timer (at = offset, interval > 0, reschedule_cb = 0) |
1280 | =item * repeating interval timer (at = offset, interval > 0, reschedule_cb = 0) |
1277 | |
1281 | |
1278 | In this mode the watcher will always be scheduled to time out at the next |
1282 | In this mode the watcher will always be scheduled to time out at the next |
1279 | C<at + N * interval> time (for some integer N, which can also be negative) |
1283 | C<at + N * interval> time (for some integer N, which can also be negative) |
1280 | and then repeat, regardless of any time jumps. |
1284 | and then repeat, regardless of any time jumps. |
1281 | |
1285 | |
… | |
… | |
1432 | |
1436 | |
1433 | The signal the watcher watches out for. |
1437 | The signal the watcher watches out for. |
1434 | |
1438 | |
1435 | =back |
1439 | =back |
1436 | |
1440 | |
|
|
1441 | =head3 Examples |
|
|
1442 | |
|
|
1443 | Example: Try to exit cleanly on SIGINT and SIGTERM. |
|
|
1444 | |
|
|
1445 | static void |
|
|
1446 | sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents) |
|
|
1447 | { |
|
|
1448 | ev_unloop (loop, EVUNLOOP_ALL); |
|
|
1449 | } |
|
|
1450 | |
|
|
1451 | struct ev_signal signal_watcher; |
|
|
1452 | ev_signal_init (&signal_watcher, sigint_cb, SIGINT); |
|
|
1453 | ev_signal_start (loop, &sigint_cb); |
|
|
1454 | |
1437 | |
1455 | |
1438 | =head2 C<ev_child> - watch out for process status changes |
1456 | =head2 C<ev_child> - watch out for process status changes |
1439 | |
1457 | |
1440 | Child watchers trigger when your process receives a SIGCHLD in response to |
1458 | Child watchers trigger when your process receives a SIGCHLD in response to |
1441 | some child status changes (most typically when a child of yours dies). |
1459 | some child status changes (most typically when a child of yours dies). It |
|
|
1460 | is permissible to install a child watcher I<after> the child has been |
|
|
1461 | forked (which implies it might have already exited), as long as the event |
|
|
1462 | loop isn't entered (or is continued from a watcher). |
|
|
1463 | |
|
|
1464 | Only the default event loop is capable of handling signals, and therefore |
|
|
1465 | you can only rgeister child watchers in the default event loop. |
|
|
1466 | |
|
|
1467 | =head3 Process Interaction |
|
|
1468 | |
|
|
1469 | Libev grabs C<SIGCHLD> as soon as the default event loop is |
|
|
1470 | initialised. This is necessary to guarantee proper behaviour even if |
|
|
1471 | the first child watcher is started after the child exits. The occurance |
|
|
1472 | of C<SIGCHLD> is recorded asynchronously, but child reaping is done |
|
|
1473 | synchronously as part of the event loop processing. Libev always reaps all |
|
|
1474 | children, even ones not watched. |
|
|
1475 | |
|
|
1476 | =head3 Overriding the Built-In Processing |
|
|
1477 | |
|
|
1478 | Libev offers no special support for overriding the built-in child |
|
|
1479 | processing, but if your application collides with libev's default child |
|
|
1480 | handler, you can override it easily by installing your own handler for |
|
|
1481 | C<SIGCHLD> after initialising the default loop, and making sure the |
|
|
1482 | default loop never gets destroyed. You are encouraged, however, to use an |
|
|
1483 | event-based approach to child reaping and thus use libev's support for |
|
|
1484 | that, so other libev users can use C<ev_child> watchers freely. |
1442 | |
1485 | |
1443 | =head3 Watcher-Specific Functions and Data Members |
1486 | =head3 Watcher-Specific Functions and Data Members |
1444 | |
1487 | |
1445 | =over 4 |
1488 | =over 4 |
1446 | |
1489 | |
… | |
… | |
1472 | |
1515 | |
1473 | =back |
1516 | =back |
1474 | |
1517 | |
1475 | =head3 Examples |
1518 | =head3 Examples |
1476 | |
1519 | |
1477 | Example: Try to exit cleanly on SIGINT and SIGTERM. |
1520 | Example: C<fork()> a new process and install a child handler to wait for |
|
|
1521 | its completion. |
|
|
1522 | |
|
|
1523 | ev_child cw; |
1478 | |
1524 | |
1479 | static void |
1525 | static void |
1480 | sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents) |
1526 | child_cb (EV_P_ struct ev_child *w, int revents) |
1481 | { |
1527 | { |
1482 | ev_unloop (loop, EVUNLOOP_ALL); |
1528 | ev_child_stop (EV_A_ w); |
|
|
1529 | printf ("process %d exited with status %x\n", w->rpid, w->rstatus); |
1483 | } |
1530 | } |
1484 | |
1531 | |
1485 | struct ev_signal signal_watcher; |
1532 | pid_t pid = fork (); |
1486 | ev_signal_init (&signal_watcher, sigint_cb, SIGINT); |
1533 | |
1487 | ev_signal_start (loop, &sigint_cb); |
1534 | if (pid < 0) |
|
|
1535 | // error |
|
|
1536 | else if (pid == 0) |
|
|
1537 | { |
|
|
1538 | // the forked child executes here |
|
|
1539 | exit (1); |
|
|
1540 | } |
|
|
1541 | else |
|
|
1542 | { |
|
|
1543 | ev_child_init (&cw, child_cb, pid, 0); |
|
|
1544 | ev_child_start (EV_DEFAULT_ &cw); |
|
|
1545 | } |
1488 | |
1546 | |
1489 | |
1547 | |
1490 | =head2 C<ev_stat> - did the file attributes just change? |
1548 | =head2 C<ev_stat> - did the file attributes just change? |
1491 | |
1549 | |
1492 | This watches a filesystem path for attribute changes. That is, it calls |
1550 | This watches a filesystem path for attribute changes. That is, it calls |
… | |
… | |
1572 | |
1630 | |
1573 | The callback will be receive C<EV_STAT> when a change was detected, |
1631 | The callback will be receive C<EV_STAT> when a change was detected, |
1574 | relative to the attributes at the time the watcher was started (or the |
1632 | relative to the attributes at the time the watcher was started (or the |
1575 | last change was detected). |
1633 | last change was detected). |
1576 | |
1634 | |
1577 | =item ev_stat_stat (ev_stat *) |
1635 | =item ev_stat_stat (loop, ev_stat *) |
1578 | |
1636 | |
1579 | Updates the stat buffer immediately with new values. If you change the |
1637 | Updates the stat buffer immediately with new values. If you change the |
1580 | watched path in your callback, you could call this fucntion to avoid |
1638 | watched path in your callback, you could call this fucntion to avoid |
1581 | detecting this change (while introducing a race condition). Can also be |
1639 | detecting this change (while introducing a race condition). Can also be |
1582 | useful simply to find out the new values. |
1640 | useful simply to find out the new values. |
… | |
… | |
2078 | is that the author does not know of a simple (or any) algorithm for a |
2136 | is that the author does not know of a simple (or any) algorithm for a |
2079 | multiple-writer-single-reader queue that works in all cases and doesn't |
2137 | multiple-writer-single-reader queue that works in all cases and doesn't |
2080 | need elaborate support such as pthreads. |
2138 | need elaborate support such as pthreads. |
2081 | |
2139 | |
2082 | That means that if you want to queue data, you have to provide your own |
2140 | That means that if you want to queue data, you have to provide your own |
2083 | queue. And here is how you would implement locking: |
2141 | queue. But at least I can tell you would implement locking around your |
|
|
2142 | queue: |
2084 | |
2143 | |
2085 | =over 4 |
2144 | =over 4 |
2086 | |
2145 | |
2087 | =item queueing from a signal handler context |
2146 | =item queueing from a signal handler context |
2088 | |
2147 | |
… | |
… | |
2097 | { |
2156 | { |
2098 | sometype data; |
2157 | sometype data; |
2099 | |
2158 | |
2100 | // no locking etc. |
2159 | // no locking etc. |
2101 | queue_put (data); |
2160 | queue_put (data); |
2102 | ev_async_send (DEFAULT_ &mysig); |
2161 | ev_async_send (EV_DEFAULT_ &mysig); |
2103 | } |
2162 | } |
2104 | |
2163 | |
2105 | static void |
2164 | static void |
2106 | mysig_cb (EV_P_ ev_async *w, int revents) |
2165 | mysig_cb (EV_P_ ev_async *w, int revents) |
2107 | { |
2166 | { |
… | |
… | |
2125 | |
2184 | |
2126 | =item queueing from a thread context |
2185 | =item queueing from a thread context |
2127 | |
2186 | |
2128 | The strategy for threads is different, as you cannot (easily) block |
2187 | The strategy for threads is different, as you cannot (easily) block |
2129 | threads but you can easily preempt them, so to queue safely you need to |
2188 | threads but you can easily preempt them, so to queue safely you need to |
2130 | emply a traditional mutex lock, such as in this pthread example: |
2189 | employ a traditional mutex lock, such as in this pthread example: |
2131 | |
2190 | |
2132 | static ev_async mysig; |
2191 | static ev_async mysig; |
2133 | static pthread_mutex_t mymutex = PTHREAD_MUTEX_INITIALIZER; |
2192 | static pthread_mutex_t mymutex = PTHREAD_MUTEX_INITIALIZER; |
2134 | |
2193 | |
2135 | static void |
2194 | static void |
… | |
… | |
2138 | // only need to lock the actual queueing operation |
2197 | // only need to lock the actual queueing operation |
2139 | pthread_mutex_lock (&mymutex); |
2198 | pthread_mutex_lock (&mymutex); |
2140 | queue_put (data); |
2199 | queue_put (data); |
2141 | pthread_mutex_unlock (&mymutex); |
2200 | pthread_mutex_unlock (&mymutex); |
2142 | |
2201 | |
2143 | ev_async_send (DEFAULT_ &mysig); |
2202 | ev_async_send (EV_DEFAULT_ &mysig); |
2144 | } |
2203 | } |
2145 | |
2204 | |
2146 | static void |
2205 | static void |
2147 | mysig_cb (EV_P_ ev_async *w, int revents) |
2206 | mysig_cb (EV_P_ ev_async *w, int revents) |
2148 | { |
2207 | { |
… | |
… | |
2912 | =item Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers) |
2971 | =item Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers) |
2913 | |
2972 | |
2914 | That means that changing a timer costs less than removing/adding them |
2973 | That means that changing a timer costs less than removing/adding them |
2915 | as only the relative motion in the event queue has to be paid for. |
2974 | as only the relative motion in the event queue has to be paid for. |
2916 | |
2975 | |
2917 | =item Starting io/check/prepare/idle/signal/child watchers: O(1) |
2976 | =item Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1) |
2918 | |
2977 | |
2919 | These just add the watcher into an array or at the head of a list. |
2978 | These just add the watcher into an array or at the head of a list. |
2920 | |
2979 | |
2921 | =item Stopping check/prepare/idle watchers: O(1) |
2980 | =item Stopping check/prepare/idle/fork/async watchers: O(1) |
2922 | |
2981 | |
2923 | =item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE)) |
2982 | =item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE)) |
2924 | |
2983 | |
2925 | These watchers are stored in lists then need to be walked to find the |
2984 | These watchers are stored in lists then need to be walked to find the |
2926 | correct watcher to remove. The lists are usually short (you don't usually |
2985 | correct watcher to remove. The lists are usually short (you don't usually |
… | |
… | |
2942 | =item Priority handling: O(number_of_priorities) |
3001 | =item Priority handling: O(number_of_priorities) |
2943 | |
3002 | |
2944 | Priorities are implemented by allocating some space for each |
3003 | Priorities are implemented by allocating some space for each |
2945 | priority. When doing priority-based operations, libev usually has to |
3004 | priority. When doing priority-based operations, libev usually has to |
2946 | linearly search all the priorities, but starting/stopping and activating |
3005 | linearly search all the priorities, but starting/stopping and activating |
2947 | watchers becomes O(1) w.r.t. prioritiy handling. |
3006 | watchers becomes O(1) w.r.t. priority handling. |
|
|
3007 | |
|
|
3008 | =item Sending an ev_async: O(1) |
|
|
3009 | |
|
|
3010 | =item Processing ev_async_send: O(number_of_async_watchers) |
|
|
3011 | |
|
|
3012 | =item Processing signals: O(max_signal_number) |
|
|
3013 | |
|
|
3014 | Sending involves a syscall I<iff> there were no other C<ev_async_send> |
|
|
3015 | calls in the current loop iteration. Checking for async and signal events |
|
|
3016 | involves iterating over all running async watchers or all signal numbers. |
2948 | |
3017 | |
2949 | =back |
3018 | =back |
2950 | |
3019 | |
2951 | |
3020 | |
2952 | =head1 Win32 platform limitations and workarounds |
3021 | =head1 Win32 platform limitations and workarounds |