… | |
… | |
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 | |
… | |
… | |
1431 | =item int signum [read-only] |
1435 | =item int signum [read-only] |
1432 | |
1436 | |
1433 | The signal the watcher watches out for. |
1437 | The signal the watcher watches out for. |
1434 | |
1438 | |
1435 | =back |
1439 | =back |
|
|
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); |
1436 | |
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 |
… | |
… | |
1470 | The process exit/trace status caused by C<rpid> (see your systems |
1488 | The process exit/trace status caused by C<rpid> (see your systems |
1471 | C<waitpid> and C<sys/wait.h> documentation for details). |
1489 | C<waitpid> and C<sys/wait.h> documentation for details). |
1472 | |
1490 | |
1473 | =back |
1491 | =back |
1474 | |
1492 | |
1475 | =head3 Examples |
|
|
1476 | |
|
|
1477 | Example: Try to exit cleanly on SIGINT and SIGTERM. |
|
|
1478 | |
|
|
1479 | static void |
|
|
1480 | sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents) |
|
|
1481 | { |
|
|
1482 | ev_unloop (loop, EVUNLOOP_ALL); |
|
|
1483 | } |
|
|
1484 | |
|
|
1485 | struct ev_signal signal_watcher; |
|
|
1486 | ev_signal_init (&signal_watcher, sigint_cb, SIGINT); |
|
|
1487 | ev_signal_start (loop, &sigint_cb); |
|
|
1488 | |
|
|
1489 | |
1493 | |
1490 | =head2 C<ev_stat> - did the file attributes just change? |
1494 | =head2 C<ev_stat> - did the file attributes just change? |
1491 | |
1495 | |
1492 | This watches a filesystem path for attribute changes. That is, it calls |
1496 | This watches a filesystem path for attribute changes. That is, it calls |
1493 | C<stat> regularly (or when the OS says it changed) and sees if it changed |
1497 | C<stat> regularly (or when the OS says it changed) and sees if it changed |
… | |
… | |
1572 | |
1576 | |
1573 | The callback will be receive C<EV_STAT> when a change was detected, |
1577 | 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 |
1578 | relative to the attributes at the time the watcher was started (or the |
1575 | last change was detected). |
1579 | last change was detected). |
1576 | |
1580 | |
1577 | =item ev_stat_stat (ev_stat *) |
1581 | =item ev_stat_stat (loop, ev_stat *) |
1578 | |
1582 | |
1579 | Updates the stat buffer immediately with new values. If you change the |
1583 | 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 |
1584 | watched path in your callback, you could call this fucntion to avoid |
1581 | detecting this change (while introducing a race condition). Can also be |
1585 | detecting this change (while introducing a race condition). Can also be |
1582 | useful simply to find out the new values. |
1586 | useful simply to find out the new values. |
… | |
… | |
2070 | C<ev_async_sent> calls). |
2074 | C<ev_async_sent> calls). |
2071 | |
2075 | |
2072 | Unlike C<ev_signal> watchers, C<ev_async> works with any event loop, not |
2076 | Unlike C<ev_signal> watchers, C<ev_async> works with any event loop, not |
2073 | just the default loop. |
2077 | just the default loop. |
2074 | |
2078 | |
|
|
2079 | =head3 Queueing |
|
|
2080 | |
|
|
2081 | C<ev_async> does not support queueing of data in any way. The reason |
|
|
2082 | is that the author does not know of a simple (or any) algorithm for a |
|
|
2083 | multiple-writer-single-reader queue that works in all cases and doesn't |
|
|
2084 | need elaborate support such as pthreads. |
|
|
2085 | |
|
|
2086 | That means that if you want to queue data, you have to provide your own |
|
|
2087 | queue. But at least I can tell you would implement locking around your |
|
|
2088 | queue: |
|
|
2089 | |
|
|
2090 | =over 4 |
|
|
2091 | |
|
|
2092 | =item queueing from a signal handler context |
|
|
2093 | |
|
|
2094 | To implement race-free queueing, you simply add to the queue in the signal |
|
|
2095 | handler but you block the signal handler in the watcher callback. Here is an example that does that for |
|
|
2096 | some fictitiuous SIGUSR1 handler: |
|
|
2097 | |
|
|
2098 | static ev_async mysig; |
|
|
2099 | |
|
|
2100 | static void |
|
|
2101 | sigusr1_handler (void) |
|
|
2102 | { |
|
|
2103 | sometype data; |
|
|
2104 | |
|
|
2105 | // no locking etc. |
|
|
2106 | queue_put (data); |
|
|
2107 | ev_async_send (EV_DEFAULT_ &mysig); |
|
|
2108 | } |
|
|
2109 | |
|
|
2110 | static void |
|
|
2111 | mysig_cb (EV_P_ ev_async *w, int revents) |
|
|
2112 | { |
|
|
2113 | sometype data; |
|
|
2114 | sigset_t block, prev; |
|
|
2115 | |
|
|
2116 | sigemptyset (&block); |
|
|
2117 | sigaddset (&block, SIGUSR1); |
|
|
2118 | sigprocmask (SIG_BLOCK, &block, &prev); |
|
|
2119 | |
|
|
2120 | while (queue_get (&data)) |
|
|
2121 | process (data); |
|
|
2122 | |
|
|
2123 | if (sigismember (&prev, SIGUSR1) |
|
|
2124 | sigprocmask (SIG_UNBLOCK, &block, 0); |
|
|
2125 | } |
|
|
2126 | |
|
|
2127 | (Note: pthreads in theory requires you to use C<pthread_setmask> |
|
|
2128 | instead of C<sigprocmask> when you use threads, but libev doesn't do it |
|
|
2129 | either...). |
|
|
2130 | |
|
|
2131 | =item queueing from a thread context |
|
|
2132 | |
|
|
2133 | The strategy for threads is different, as you cannot (easily) block |
|
|
2134 | threads but you can easily preempt them, so to queue safely you need to |
|
|
2135 | employ a traditional mutex lock, such as in this pthread example: |
|
|
2136 | |
|
|
2137 | static ev_async mysig; |
|
|
2138 | static pthread_mutex_t mymutex = PTHREAD_MUTEX_INITIALIZER; |
|
|
2139 | |
|
|
2140 | static void |
|
|
2141 | otherthread (void) |
|
|
2142 | { |
|
|
2143 | // only need to lock the actual queueing operation |
|
|
2144 | pthread_mutex_lock (&mymutex); |
|
|
2145 | queue_put (data); |
|
|
2146 | pthread_mutex_unlock (&mymutex); |
|
|
2147 | |
|
|
2148 | ev_async_send (EV_DEFAULT_ &mysig); |
|
|
2149 | } |
|
|
2150 | |
|
|
2151 | static void |
|
|
2152 | mysig_cb (EV_P_ ev_async *w, int revents) |
|
|
2153 | { |
|
|
2154 | pthread_mutex_lock (&mymutex); |
|
|
2155 | |
|
|
2156 | while (queue_get (&data)) |
|
|
2157 | process (data); |
|
|
2158 | |
|
|
2159 | pthread_mutex_unlock (&mymutex); |
|
|
2160 | } |
|
|
2161 | |
|
|
2162 | =back |
|
|
2163 | |
|
|
2164 | |
2075 | =head3 Watcher-Specific Functions and Data Members |
2165 | =head3 Watcher-Specific Functions and Data Members |
2076 | |
2166 | |
2077 | =over 4 |
2167 | =over 4 |
2078 | |
2168 | |
2079 | =item ev_async_init (ev_async *, callback) |
2169 | =item ev_async_init (ev_async *, callback) |
… | |
… | |
2610 | be detected at runtime. |
2700 | be detected at runtime. |
2611 | |
2701 | |
2612 | =item EV_ATOMIC_T |
2702 | =item EV_ATOMIC_T |
2613 | |
2703 | |
2614 | Libev requires an integer type (suitable for storing C<0> or C<1>) whose |
2704 | Libev requires an integer type (suitable for storing C<0> or C<1>) whose |
2615 | access is atomic with respect to other threads or signal contexts. No such type |
2705 | access is atomic with respect to other threads or signal contexts. No such |
2616 | is easily found using, so you cna provide your own type that you know is safe. |
2706 | type is easily found in the C language, so you can provide your own type |
|
|
2707 | that you know is safe for your purposes. It is used both for signal handler "locking" |
|
|
2708 | as well as for signal and thread safety in C<ev_async> watchers. |
2617 | |
2709 | |
2618 | In the absense of this define, libev will use C<sig_atomic_t volatile> |
2710 | In the absense of this define, libev will use C<sig_atomic_t volatile> |
2619 | from F<signal.h>, which is usually good enough on most platforms. |
2711 | (from F<signal.h>), which is usually good enough on most platforms. |
2620 | |
2712 | |
2621 | =item EV_H |
2713 | =item EV_H |
2622 | |
2714 | |
2623 | The name of the F<ev.h> header file used to include it. The default if |
2715 | The name of the F<ev.h> header file used to include it. The default if |
2624 | undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be |
2716 | undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be |
… | |
… | |
2825 | =item Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers) |
2917 | =item Changing timer/periodic watchers (by autorepeat or calling again): O(log skipped_other_timers) |
2826 | |
2918 | |
2827 | That means that changing a timer costs less than removing/adding them |
2919 | That means that changing a timer costs less than removing/adding them |
2828 | as only the relative motion in the event queue has to be paid for. |
2920 | as only the relative motion in the event queue has to be paid for. |
2829 | |
2921 | |
2830 | =item Starting io/check/prepare/idle/signal/child watchers: O(1) |
2922 | =item Starting io/check/prepare/idle/signal/child/fork/async watchers: O(1) |
2831 | |
2923 | |
2832 | These just add the watcher into an array or at the head of a list. |
2924 | These just add the watcher into an array or at the head of a list. |
2833 | |
2925 | |
2834 | =item Stopping check/prepare/idle watchers: O(1) |
2926 | =item Stopping check/prepare/idle/fork/async watchers: O(1) |
2835 | |
2927 | |
2836 | =item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE)) |
2928 | =item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % EV_PID_HASHSIZE)) |
2837 | |
2929 | |
2838 | These watchers are stored in lists then need to be walked to find the |
2930 | These watchers are stored in lists then need to be walked to find the |
2839 | correct watcher to remove. The lists are usually short (you don't usually |
2931 | correct watcher to remove. The lists are usually short (you don't usually |
… | |
… | |
2855 | =item Priority handling: O(number_of_priorities) |
2947 | =item Priority handling: O(number_of_priorities) |
2856 | |
2948 | |
2857 | Priorities are implemented by allocating some space for each |
2949 | Priorities are implemented by allocating some space for each |
2858 | priority. When doing priority-based operations, libev usually has to |
2950 | priority. When doing priority-based operations, libev usually has to |
2859 | linearly search all the priorities, but starting/stopping and activating |
2951 | linearly search all the priorities, but starting/stopping and activating |
2860 | watchers becomes O(1) w.r.t. prioritiy handling. |
2952 | watchers becomes O(1) w.r.t. priority handling. |
|
|
2953 | |
|
|
2954 | =item Sending an ev_async: O(1) |
|
|
2955 | |
|
|
2956 | =item Processing ev_async_send: O(number_of_async_watchers) |
|
|
2957 | |
|
|
2958 | =item Processing signals: O(max_signal_number) |
|
|
2959 | |
|
|
2960 | Sending involves a syscall I<iff> there were no other C<ev_async_send> |
|
|
2961 | calls in the current loop iteration. Checking for async and signal events |
|
|
2962 | involves iterating over all running async watchers or all signal numbers. |
2861 | |
2963 | |
2862 | =back |
2964 | =back |
2863 | |
2965 | |
2864 | |
2966 | |
2865 | =head1 Win32 platform limitations and workarounds |
2967 | =head1 Win32 platform limitations and workarounds |