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

Comparing libev/ev.pod (file contents):
Revision 1.129 by root, Tue Feb 5 23:56:33 2008 UTC vs.
Revision 1.134 by root, Sat Mar 8 07:04:56 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
… …
1152configure 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
1153exactly 10 second intervals. If, however, your program cannot keep up with 1157exactly 10 second intervals. If, however, your program cannot keep up with
1154the 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
1155timer will not fire more than once per event loop iteration. 1159timer 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
1159This 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
1160repeating. The exact semantics are: 1164repeating. The exact semantics are:
1161 1165
1162If the timer is pending, its pending status is cleared. 1166If the timer is pending, its pending status is cleared.
… …
1271In this configuration the watcher triggers an event at the wallclock time 1275In this configuration the watcher triggers an event at the wallclock time
1272C<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,
1273that 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
1274system time reaches or surpasses this time. 1278system 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
1278In 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
1279C<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)
1280and then repeat, regardless of any time jumps. 1284and then repeat, regardless of any time jumps.
1281 1285
… …
1432 1436
1433The signal the watcher watches out for. 1437The signal the watcher watches out for.
1434 1438
1435=back 1439=back
1436 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);
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
1440Child watchers trigger when your process receives a SIGCHLD in response to 1458Child watchers trigger when your process receives a SIGCHLD in response to
1441some child status changes (most typically when a child of yours dies). 1459some child status changes (most typically when a child of yours dies). It
1460is permissible to install a child watcher I<after> the child has been
1461forked (which implies it might have already exited), as long as the event
1462loop isn't entered (or is continued from a watcher).
1463
1464Only the default event loop is capable of handling signals, and therefore
1465you can only rgeister child watchers in the default event loop.
1466
1467=head3 Process Interaction
1468
1469Libev grabs C<SIGCHLD> as soon as the default event loop is
1470initialised. This is necessary to guarantee proper behaviour even if
1471the first child watcher is started after the child exits. The occurance
1472of C<SIGCHLD> is recorded asynchronously, but child reaping is done
1473synchronously as part of the event loop processing. Libev always reaps all
1474children, even ones not watched.
1475
1476=head3 Overriding the Built-In Processing
1477
1478Libev offers no special support for overriding the built-in child
1479processing, but if your application collides with libev's default child
1480handler, you can override it easily by installing your own handler for
1481C<SIGCHLD> after initialising the default loop, and making sure the
1482default loop never gets destroyed. You are encouraged, however, to use an
1483event-based approach to child reaping and thus use libev's support for
1484that, 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
1477Example: Try to exit cleanly on SIGINT and SIGTERM. 1520Example: C<fork()> a new process and install a child handler to wait for
1521its 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
1492This watches a filesystem path for attribute changes. That is, it calls 1550This watches a filesystem path for attribute changes. That is, it calls
… …
1572 1630
1573The callback will be receive C<EV_STAT> when a change was detected, 1631The callback will be receive C<EV_STAT> when a change was detected,
1574relative to the attributes at the time the watcher was started (or the 1632relative to the attributes at the time the watcher was started (or the
1575last change was detected). 1633last change was detected).
1576 1634
1577=item ev_stat_stat (ev_stat *) 1635=item ev_stat_stat (loop, ev_stat *)
1578 1636
1579Updates the stat buffer immediately with new values. If you change the 1637Updates the stat buffer immediately with new values. If you change the
1580watched path in your callback, you could call this fucntion to avoid 1638watched path in your callback, you could call this fucntion to avoid
1581detecting this change (while introducing a race condition). Can also be 1639detecting this change (while introducing a race condition). Can also be
1582useful simply to find out the new values. 1640useful simply to find out the new values.
… …
2078is that the author does not know of a simple (or any) algorithm for a 2136is that the author does not know of a simple (or any) algorithm for a
2079multiple-writer-single-reader queue that works in all cases and doesn't 2137multiple-writer-single-reader queue that works in all cases and doesn't
2080need elaborate support such as pthreads. 2138need elaborate support such as pthreads.
2081 2139
2082That means that if you want to queue data, you have to provide your own 2140That means that if you want to queue data, you have to provide your own
2083queue. And here is how you would implement locking: 2141queue. But at least I can tell you would implement locking around your
2142queue:
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
2128The strategy for threads is different, as you cannot (easily) block 2187The strategy for threads is different, as you cannot (easily) block
2129threads but you can easily preempt them, so to queue safely you need to 2188threads but you can easily preempt them, so to queue safely you need to
2130emply a traditional mutex lock, such as in this pthread example: 2189employ 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 {

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines