ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libev/ev.pod
(Generate patch)

Comparing libev/ev.pod (file contents):
Revision 1.121 by root, Mon Jan 28 12:13:54 2008 UTC vs.
Revision 1.132 by root, Wed Feb 20 17:45:29 2008 UTC

505=item ev_loop_fork (loop) 505=item ev_loop_fork (loop)
506 506
507Like C<ev_default_fork>, but acts on an event loop created by 507Like C<ev_default_fork>, but acts on an event loop created by
508C<ev_loop_new>. Yes, you have to call this on every allocated event loop 508C<ev_loop_new>. Yes, you have to call this on every allocated event loop
509after fork, and how you do this is entirely your own problem. 509after fork, and how you do this is entirely your own problem.
510
511=item int ev_is_default_loop (loop)
512
513Returns 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
513Returns the count of loop iterations for the loop, which is identical to 517Returns the count of loop iterations for the loop, which is identical to
514the number of times libev did poll for new events. It starts at C<0> and 518the number of times libev did poll for new events. It starts at C<0> and
774=item C<EV_FORK> 778=item C<EV_FORK>
775 779
776The event loop has been resumed in the child process after fork (see 780The event loop has been resumed in the child process after fork (see
777C<ev_fork>). 781C<ev_fork>).
778 782
783=item C<EV_ASYNC>
784
785The given async watcher has been asynchronously notified (see C<ev_async>).
786
779=item C<EV_ERROR> 787=item C<EV_ERROR>
780 788
781An unspecified error has occured, the watcher has been stopped. This might 789An unspecified error has occured, the watcher has been stopped. This might
782happen because the watcher could not be properly started because libev 790happen because the watcher could not be properly started because libev
783ran out of memory, a file descriptor was found to be closed or any other 791ran out of memory, a file descriptor was found to be closed or any other
1148configure a timer to trigger every 10 seconds, then it will trigger at 1156configure a timer to trigger every 10 seconds, then it will trigger at
1149exactly 10 second intervals. If, however, your program cannot keep up with 1157exactly 10 second intervals. If, however, your program cannot keep up with
1150the timer (because it takes longer than those 10 seconds to do stuff) the 1158the timer (because it takes longer than those 10 seconds to do stuff) the
1151timer will not fire more than once per event loop iteration. 1159timer will not fire more than once per event loop iteration.
1152 1160
1153=item ev_timer_again (loop) 1161=item ev_timer_again (loop, ev_timer *)
1154 1162
1155This will act as if the timer timed out and restart it again if it is 1163This will act as if the timer timed out and restart it again if it is
1156repeating. The exact semantics are: 1164repeating. The exact semantics are:
1157 1165
1158If the timer is pending, its pending status is cleared. 1166If the timer is pending, its pending status is cleared.
1267In this configuration the watcher triggers an event at the wallclock time 1275In this configuration the watcher triggers an event at the wallclock time
1268C<at> and doesn't repeat. It will not adjust when a time jump occurs, 1276C<at> and doesn't repeat. It will not adjust when a time jump occurs,
1269that is, if it is to be run at January 1st 2011 then it will run when the 1277that is, if it is to be run at January 1st 2011 then it will run when the
1270system time reaches or surpasses this time. 1278system time reaches or surpasses this time.
1271 1279
1272=item * non-repeating interval timer (at = offset, interval > 0, reschedule_cb = 0) 1280=item * repeating interval timer (at = offset, interval > 0, reschedule_cb = 0)
1273 1281
1274In this mode the watcher will always be scheduled to time out at the next 1282In this mode the watcher will always be scheduled to time out at the next
1275C<at + N * interval> time (for some integer N, which can also be negative) 1283C<at + N * interval> time (for some integer N, which can also be negative)
1276and then repeat, regardless of any time jumps. 1284and then repeat, regardless of any time jumps.
1277 1285
1427=item int signum [read-only] 1435=item int signum [read-only]
1428 1436
1429The signal the watcher watches out for. 1437The signal the watcher watches out for.
1430 1438
1431=back 1439=back
1440
1441=head3 Examples
1442
1443Example: 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);
1432 1454
1433 1455
1434=head2 C<ev_child> - watch out for process status changes 1456=head2 C<ev_child> - watch out for process status changes
1435 1457
1436Child watchers trigger when your process receives a SIGCHLD in response to 1458Child watchers trigger when your process receives a SIGCHLD in response to
1466The process exit/trace status caused by C<rpid> (see your systems 1488The process exit/trace status caused by C<rpid> (see your systems
1467C<waitpid> and C<sys/wait.h> documentation for details). 1489C<waitpid> and C<sys/wait.h> documentation for details).
1468 1490
1469=back 1491=back
1470 1492
1471=head3 Examples
1472
1473Example: Try to exit cleanly on SIGINT and SIGTERM.
1474
1475 static void
1476 sigint_cb (struct ev_loop *loop, struct ev_signal *w, int revents)
1477 {
1478 ev_unloop (loop, EVUNLOOP_ALL);
1479 }
1480
1481 struct ev_signal signal_watcher;
1482 ev_signal_init (&signal_watcher, sigint_cb, SIGINT);
1483 ev_signal_start (loop, &sigint_cb);
1484
1485 1493
1486=head2 C<ev_stat> - did the file attributes just change? 1494=head2 C<ev_stat> - did the file attributes just change?
1487 1495
1488This watches a filesystem path for attribute changes. That is, it calls 1496This watches a filesystem path for attribute changes. That is, it calls
1489C<stat> regularly (or when the OS says it changed) and sees if it changed 1497C<stat> regularly (or when the OS says it changed) and sees if it changed
1568 1576
1569The callback will be receive C<EV_STAT> when a change was detected, 1577The callback will be receive C<EV_STAT> when a change was detected,
1570relative to the attributes at the time the watcher was started (or the 1578relative to the attributes at the time the watcher was started (or the
1571last change was detected). 1579last change was detected).
1572 1580
1573=item ev_stat_stat (ev_stat *) 1581=item ev_stat_stat (loop, ev_stat *)
1574 1582
1575Updates the stat buffer immediately with new values. If you change the 1583Updates the stat buffer immediately with new values. If you change the
1576watched path in your callback, you could call this fucntion to avoid 1584watched path in your callback, you could call this fucntion to avoid
1577detecting this change (while introducing a race condition). Can also be 1585detecting this change (while introducing a race condition). Can also be
1578useful simply to find out the new values. 1586useful simply to find out the new values.
2046believe me. 2054believe me.
2047 2055
2048=back 2056=back
2049 2057
2050 2058
2059=head2 C<ev_async> - how to wake up another event loop
2060
2061In general, you cannot use an C<ev_loop> from multiple threads or other
2062asynchronous sources such as signal handlers (as opposed to multiple event
2063loops - those are of course safe to use in different threads).
2064
2065Sometimes, however, you need to wake up another event loop you do not
2066control, for example because it belongs to another thread. This is what
2067C<ev_async> watchers do: as long as the C<ev_async> watcher is active, you
2068can signal it by calling C<ev_async_send>, which is thread- and signal
2069safe.
2070
2071This functionality is very similar to C<ev_signal> watchers, as signals,
2072too, are asynchronous in nature, and signals, too, will be compressed
2073(i.e. the number of callback invocations may be less than the number of
2074C<ev_async_sent> calls).
2075
2076Unlike C<ev_signal> watchers, C<ev_async> works with any event loop, not
2077just the default loop.
2078
2079=head3 Queueing
2080
2081C<ev_async> does not support queueing of data in any way. The reason
2082is that the author does not know of a simple (or any) algorithm for a
2083multiple-writer-single-reader queue that works in all cases and doesn't
2084need elaborate support such as pthreads.
2085
2086That means that if you want to queue data, you have to provide your own
2087queue. But at least I can tell you would implement locking around your
2088queue:
2089
2090=over 4
2091
2092=item queueing from a signal handler context
2093
2094To implement race-free queueing, you simply add to the queue in the signal
2095handler but you block the signal handler in the watcher callback. Here is an example that does that for
2096some 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 (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>
2128instead of C<sigprocmask> when you use threads, but libev doesn't do it
2129either...).
2130
2131=item queueing from a thread context
2132
2133The strategy for threads is different, as you cannot (easily) block
2134threads but you can easily preempt them, so to queue safely you need to
2135employ 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 (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
2165=head3 Watcher-Specific Functions and Data Members
2166
2167=over 4
2168
2169=item ev_async_init (ev_async *, callback)
2170
2171Initialises and configures the async watcher - it has no parameters of any
2172kind. There is a C<ev_asynd_set> macro, but using it is utterly pointless,
2173believe me.
2174
2175=item ev_async_send (loop, ev_async *)
2176
2177Sends/signals/activates the given C<ev_async> watcher, that is, feeds
2178an C<EV_ASYNC> event on the watcher into the event loop. Unlike
2179C<ev_feed_event>, this call is safe to do in other threads, signal or
2180similar contexts (see the dicusssion of C<EV_ATOMIC_T> in the embedding
2181section below on what exactly this means).
2182
2183This call incurs the overhead of a syscall only once per loop iteration,
2184so while the overhead might be noticable, it doesn't apply to repeated
2185calls to C<ev_async_send>.
2186
2187=back
2188
2189
2051=head1 OTHER FUNCTIONS 2190=head1 OTHER FUNCTIONS
2052 2191
2053There are some other functions of possible interest. Described. Here. Now. 2192There are some other functions of possible interest. Described. Here. Now.
2054 2193
2055=over 4 2194=over 4
2558 2697
2559If defined to be C<1>, libev will compile in support for the Linux inotify 2698If defined to be C<1>, libev will compile in support for the Linux inotify
2560interface to speed up C<ev_stat> watchers. Its actual availability will 2699interface to speed up C<ev_stat> watchers. Its actual availability will
2561be detected at runtime. 2700be detected at runtime.
2562 2701
2702=item EV_ATOMIC_T
2703
2704Libev requires an integer type (suitable for storing C<0> or C<1>) whose
2705access is atomic with respect to other threads or signal contexts. No such
2706type is easily found in the C language, so you can provide your own type
2707that you know is safe for your purposes. It is used both for signal handler "locking"
2708as well as for signal and thread safety in C<ev_async> watchers.
2709
2710In the absense of this define, libev will use C<sig_atomic_t volatile>
2711(from F<signal.h>), which is usually good enough on most platforms.
2712
2563=item EV_H 2713=item EV_H
2564 2714
2565The name of the F<ev.h> header file used to include it. The default if 2715The name of the F<ev.h> header file used to include it. The default if
2566undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be 2716undefined is C<"ev.h"> in F<event.h>, F<ev.c> and F<ev++.h>. This can be
2567used to virtually rename the F<ev.h> header file in case of conflicts. 2717used to virtually rename the F<ev.h> header file in case of conflicts.
2632defined to be C<0>, then they are not. 2782defined to be C<0>, then they are not.
2633 2783
2634=item EV_FORK_ENABLE 2784=item EV_FORK_ENABLE
2635 2785
2636If undefined or defined to be C<1>, then fork watchers are supported. If 2786If undefined or defined to be C<1>, then fork watchers are supported. If
2787defined to be C<0>, then they are not.
2788
2789=item EV_ASYNC_ENABLE
2790
2791If undefined or defined to be C<1>, then async watchers are supported. If
2637defined to be C<0>, then they are not. 2792defined to be C<0>, then they are not.
2638 2793
2639=item EV_MINIMAL 2794=item EV_MINIMAL
2640 2795
2641If you need to shave off some kilobytes of code at the expense of some 2796If you need to shave off some kilobytes of code at the expense of some
2762=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)
2763 2918
2764That means that changing a timer costs less than removing/adding them 2919That means that changing a timer costs less than removing/adding them
2765as only the relative motion in the event queue has to be paid for. 2920as only the relative motion in the event queue has to be paid for.
2766 2921
2767=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)
2768 2923
2769These just add the watcher into an array or at the head of a list. 2924These just add the watcher into an array or at the head of a list.
2770 2925
2771=item Stopping check/prepare/idle watchers: O(1) 2926=item Stopping check/prepare/idle/fork/async watchers: O(1)
2772 2927
2773=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))
2774 2929
2775These watchers are stored in lists then need to be walked to find the 2930These watchers are stored in lists then need to be walked to find the
2776correct watcher to remove. The lists are usually short (you don't usually 2931correct watcher to remove. The lists are usually short (you don't usually
2792=item Priority handling: O(number_of_priorities) 2947=item Priority handling: O(number_of_priorities)
2793 2948
2794Priorities are implemented by allocating some space for each 2949Priorities are implemented by allocating some space for each
2795priority. When doing priority-based operations, libev usually has to 2950priority. When doing priority-based operations, libev usually has to
2796linearly search all the priorities, but starting/stopping and activating 2951linearly search all the priorities, but starting/stopping and activating
2797watchers becomes O(1) w.r.t. prioritiy handling. 2952watchers 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
2960Sending involves a syscall I<iff> there were no other C<ev_async_send>
2961calls in the current loop iteration. Checking for async and signal events
2962involves iterating over all running async watchers or all signal numbers.
2798 2963
2799=back 2964=back
2800 2965
2801 2966
2802=head1 Win32 platform limitations and workarounds 2967=head1 Win32 platform limitations and workarounds

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines