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

Comparing libev/ev.pod (file contents):
Revision 1.353 by root, Mon Jan 10 14:36:44 2011 UTC vs.
Revision 1.354 by root, Tue Jan 11 01:40:25 2011 UTC

506employing an additional generation counter and comparing that against the 506employing an additional generation counter and comparing that against the
507events to filter out spurious ones, recreating the set when required. Last 507events to filter out spurious ones, recreating the set when required. Last
508not least, it also refuses to work with some file descriptors which work 508not least, it also refuses to work with some file descriptors which work
509perfectly fine with C<select> (files, many character devices...). 509perfectly fine with C<select> (files, many character devices...).
510 510
511Epoll is truly the train wreck analog among event poll mechanisms. 511Epoll is truly the train wreck analog among event poll mechanisms,
512a frankenpoll, cobbled together in a hurry, no thought to design or
513interaction with others.
512 514
513While stopping, setting and starting an I/O watcher in the same iteration 515While stopping, setting and starting an I/O watcher in the same iteration
514will result in some caching, there is still a system call per such 516will result in some caching, there is still a system call per such
515incident (because the same I<file descriptor> could point to a different 517incident (because the same I<file descriptor> could point to a different
516I<file description> now), so its best to avoid that. Also, C<dup ()>'ed 518I<file description> now), so its best to avoid that. Also, C<dup ()>'ed
1614In general you can register as many read and/or write event watchers per 1616In general you can register as many read and/or write event watchers per
1615fd as you want (as long as you don't confuse yourself). Setting all file 1617fd as you want (as long as you don't confuse yourself). Setting all file
1616descriptors to non-blocking mode is also usually a good idea (but not 1618descriptors to non-blocking mode is also usually a good idea (but not
1617required if you know what you are doing). 1619required if you know what you are doing).
1618 1620
1619If you cannot use non-blocking mode, then force the use of a
1620known-to-be-good backend (at the time of this writing, this includes only
1621C<EVBACKEND_SELECT> and C<EVBACKEND_POLL>). The same applies to file
1622descriptors for which non-blocking operation makes no sense (such as
1623files) - libev doesn't guarantee any specific behaviour in that case.
1624
1625Another thing you have to watch out for is that it is quite easy to 1621Another thing you have to watch out for is that it is quite easy to
1626receive "spurious" readiness notifications, that is your callback might 1622receive "spurious" readiness notifications, that is, your callback might
1627be called with C<EV_READ> but a subsequent C<read>(2) will actually block 1623be called with C<EV_READ> but a subsequent C<read>(2) will actually block
1628because there is no data. Not only are some backends known to create a 1624because there is no data. It is very easy to get into this situation even
1629lot of those (for example Solaris ports), it is very easy to get into 1625with a relatively standard program structure. Thus it is best to always
1630this situation even with a relatively standard program structure. Thus 1626use non-blocking I/O: An extra C<read>(2) returning C<EAGAIN> is far
1631it is best to always use non-blocking I/O: An extra C<read>(2) returning
1632C<EAGAIN> is far preferable to a program hanging until some data arrives. 1627preferable to a program hanging until some data arrives.
1633 1628
1634If you cannot run the fd in non-blocking mode (for example you should 1629If you cannot run the fd in non-blocking mode (for example you should
1635not play around with an Xlib connection), then you have to separately 1630not play around with an Xlib connection), then you have to separately
1636re-test whether a file descriptor is really ready with a known-to-be good 1631re-test whether a file descriptor is really ready with a known-to-be good
1637interface such as poll (fortunately in our Xlib example, Xlib already 1632interface such as poll (fortunately in the case of Xlib, it already does
1638does this on its own, so its quite safe to use). Some people additionally 1633this on its own, so its quite safe to use). Some people additionally
1639use C<SIGALRM> and an interval timer, just to be sure you won't block 1634use C<SIGALRM> and an interval timer, just to be sure you won't block
1640indefinitely. 1635indefinitely.
1641 1636
1642But really, best use non-blocking mode. 1637But really, best use non-blocking mode.
1643 1638
1671 1666
1672There is no workaround possible except not registering events 1667There is no workaround possible except not registering events
1673for potentially C<dup ()>'ed file descriptors, or to resort to 1668for potentially C<dup ()>'ed file descriptors, or to resort to
1674C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>. 1669C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>.
1675 1670
1671=head3 The special problem of files
1672
1673Many people try to use C<select> (or libev) on file descriptors
1674representing files, and expect it to become ready when their program
1675doesn't block on disk accesses (which can take a long time on their own).
1676
1677However, this cannot ever work in the "expected" way - you get a readiness
1678notification as soon as the kernel knows whether and how much data is
1679there, and in the case of open files, that's always the case, so you
1680always get a readiness notification instantly, and your read (or possibly
1681write) will still block on the disk I/O.
1682
1683Another way to view it is that in the case of sockets, pipes, character
1684devices and so on, there is another party (the sender) that delivers data
1685on it's own, but in the case of files, there is no such thing: the disk
1686will not send data on it's own, simply because it doesn't know what you
1687wish to read - you would first have to request some data.
1688
1689Since files are typically not-so-well supported by advanced notification
1690mechanism, libev tries hard to emulate POSIX behaviour with respect
1691to files, even though you should not use it. The reason for this is
1692convenience: sometimes you want to watch STDIN or STDOUT, which is
1693usually a tty, often a pipe, but also sometimes files or special devices
1694(for example, C<epoll> on Linux works with F</dev/random> but not with
1695F</dev/urandom>), and even though the file might better be served with
1696asynchronous I/O instead of with non-blocking I/O, it is still useful when
1697it "just works" instead of freezing.
1698
1699So avoid file descriptors pointing to files when you know it (e.g. use
1700libeio), but use them when it is convenient, e.g. for STDIN/STDOUT, or
1701when you rarely read from a file instead of from a socket, and want to
1702reuse the same code path.
1703
1676=head3 The special problem of fork 1704=head3 The special problem of fork
1677 1705
1678Some backends (epoll, kqueue) do not support C<fork ()> at all or exhibit 1706Some backends (epoll, kqueue) do not support C<fork ()> at all or exhibit
1679useless behaviour. Libev fully supports fork, but needs to be told about 1707useless behaviour. Libev fully supports fork, but needs to be told about
1680it in the child. 1708it in the child if you want to continue to use it in the child.
1681 1709
1682To support fork in your programs, you either have to call 1710To support fork in your child processes, you have to call C<ev_loop_fork
1683C<ev_default_fork ()> or C<ev_loop_fork ()> after a fork in the child, 1711()> after a fork in the child, enable C<EVFLAG_FORKCHECK>, or resort to
1684enable C<EVFLAG_FORKCHECK>, or resort to C<EVBACKEND_SELECT> or 1712C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>.
1685C<EVBACKEND_POLL>.
1686 1713
1687=head3 The special problem of SIGPIPE 1714=head3 The special problem of SIGPIPE
1688 1715
1689While not really specific to libev, it is easy to forget about C<SIGPIPE>: 1716While not really specific to libev, it is easy to forget about C<SIGPIPE>:
1690when writing to a pipe whose other end has been closed, your program gets 1717when writing to a pipe whose other end has been closed, your program gets
3470 exit_main_loop = 1; 3497 exit_main_loop = 1;
3471 3498
3472 // exit both 3499 // exit both
3473 exit_main_loop = exit_nested_loop = 1; 3500 exit_main_loop = exit_nested_loop = 1;
3474 3501
3502=item Thread locking example
3503
3504Here is a fictitious example of how to run an event loop in a different
3505thread than where callbacks are being invoked and watchers are
3506created/added/removed.
3507
3508For a real-world example, see the C<EV::Loop::Async> perl module,
3509which uses exactly this technique (which is suited for many high-level
3510languages).
3511
3512The example uses a pthread mutex to protect the loop data, a condition
3513variable to wait for callback invocations, an async watcher to notify the
3514event loop thread and an unspecified mechanism to wake up the main thread.
3515
3516First, you need to associate some data with the event loop:
3517
3518 typedef struct {
3519 mutex_t lock; /* global loop lock */
3520 ev_async async_w;
3521 thread_t tid;
3522 cond_t invoke_cv;
3523 } userdata;
3524
3525 void prepare_loop (EV_P)
3526 {
3527 // for simplicity, we use a static userdata struct.
3528 static userdata u;
3529
3530 ev_async_init (&u->async_w, async_cb);
3531 ev_async_start (EV_A_ &u->async_w);
3532
3533 pthread_mutex_init (&u->lock, 0);
3534 pthread_cond_init (&u->invoke_cv, 0);
3535
3536 // now associate this with the loop
3537 ev_set_userdata (EV_A_ u);
3538 ev_set_invoke_pending_cb (EV_A_ l_invoke);
3539 ev_set_loop_release_cb (EV_A_ l_release, l_acquire);
3540
3541 // then create the thread running ev_loop
3542 pthread_create (&u->tid, 0, l_run, EV_A);
3543 }
3544
3545The callback for the C<ev_async> watcher does nothing: the watcher is used
3546solely to wake up the event loop so it takes notice of any new watchers
3547that might have been added:
3548
3549 static void
3550 async_cb (EV_P_ ev_async *w, int revents)
3551 {
3552 // just used for the side effects
3553 }
3554
3555The C<l_release> and C<l_acquire> callbacks simply unlock/lock the mutex
3556protecting the loop data, respectively.
3557
3558 static void
3559 l_release (EV_P)
3560 {
3561 userdata *u = ev_userdata (EV_A);
3562 pthread_mutex_unlock (&u->lock);
3563 }
3564
3565 static void
3566 l_acquire (EV_P)
3567 {
3568 userdata *u = ev_userdata (EV_A);
3569 pthread_mutex_lock (&u->lock);
3570 }
3571
3572The event loop thread first acquires the mutex, and then jumps straight
3573into C<ev_run>:
3574
3575 void *
3576 l_run (void *thr_arg)
3577 {
3578 struct ev_loop *loop = (struct ev_loop *)thr_arg;
3579
3580 l_acquire (EV_A);
3581 pthread_setcanceltype (PTHREAD_CANCEL_ASYNCHRONOUS, 0);
3582 ev_run (EV_A_ 0);
3583 l_release (EV_A);
3584
3585 return 0;
3586 }
3587
3588Instead of invoking all pending watchers, the C<l_invoke> callback will
3589signal the main thread via some unspecified mechanism (signals? pipe
3590writes? C<Async::Interrupt>?) and then waits until all pending watchers
3591have been called (in a while loop because a) spurious wakeups are possible
3592and b) skipping inter-thread-communication when there are no pending
3593watchers is very beneficial):
3594
3595 static void
3596 l_invoke (EV_P)
3597 {
3598 userdata *u = ev_userdata (EV_A);
3599
3600 while (ev_pending_count (EV_A))
3601 {
3602 wake_up_other_thread_in_some_magic_or_not_so_magic_way ();
3603 pthread_cond_wait (&u->invoke_cv, &u->lock);
3604 }
3605 }
3606
3607Now, whenever the main thread gets told to invoke pending watchers, it
3608will grab the lock, call C<ev_invoke_pending> and then signal the loop
3609thread to continue:
3610
3611 static void
3612 real_invoke_pending (EV_P)
3613 {
3614 userdata *u = ev_userdata (EV_A);
3615
3616 pthread_mutex_lock (&u->lock);
3617 ev_invoke_pending (EV_A);
3618 pthread_cond_signal (&u->invoke_cv);
3619 pthread_mutex_unlock (&u->lock);
3620 }
3621
3622Whenever you want to start/stop a watcher or do other modifications to an
3623event loop, you will now have to lock:
3624
3625 ev_timer timeout_watcher;
3626 userdata *u = ev_userdata (EV_A);
3627
3628 ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
3629
3630 pthread_mutex_lock (&u->lock);
3631 ev_timer_start (EV_A_ &timeout_watcher);
3632 ev_async_send (EV_A_ &u->async_w);
3633 pthread_mutex_unlock (&u->lock);
3634
3635Note that sending the C<ev_async> watcher is required because otherwise
3636an event loop currently blocking in the kernel will have no knowledge
3637about the newly added timer. By waking up the loop it will pick up any new
3638watchers in the next event loop iteration.
3639
3475=back 3640=back
3476 3641
3477 3642
3478=head1 LIBEVENT EMULATION 3643=head1 LIBEVENT EMULATION
3479 3644
4471default loop and triggering an C<ev_async> watcher from the default loop 4636default loop and triggering an C<ev_async> watcher from the default loop
4472watcher callback into the event loop interested in the signal. 4637watcher callback into the event loop interested in the signal.
4473 4638
4474=back 4639=back
4475 4640
4476=head4 THREAD LOCKING EXAMPLE 4641See also L<Thread locking example>.
4477
4478Here is a fictitious example of how to run an event loop in a different
4479thread than where callbacks are being invoked and watchers are
4480created/added/removed.
4481
4482For a real-world example, see the C<EV::Loop::Async> perl module,
4483which uses exactly this technique (which is suited for many high-level
4484languages).
4485
4486The example uses a pthread mutex to protect the loop data, a condition
4487variable to wait for callback invocations, an async watcher to notify the
4488event loop thread and an unspecified mechanism to wake up the main thread.
4489
4490First, you need to associate some data with the event loop:
4491
4492 typedef struct {
4493 mutex_t lock; /* global loop lock */
4494 ev_async async_w;
4495 thread_t tid;
4496 cond_t invoke_cv;
4497 } userdata;
4498
4499 void prepare_loop (EV_P)
4500 {
4501 // for simplicity, we use a static userdata struct.
4502 static userdata u;
4503
4504 ev_async_init (&u->async_w, async_cb);
4505 ev_async_start (EV_A_ &u->async_w);
4506
4507 pthread_mutex_init (&u->lock, 0);
4508 pthread_cond_init (&u->invoke_cv, 0);
4509
4510 // now associate this with the loop
4511 ev_set_userdata (EV_A_ u);
4512 ev_set_invoke_pending_cb (EV_A_ l_invoke);
4513 ev_set_loop_release_cb (EV_A_ l_release, l_acquire);
4514
4515 // then create the thread running ev_loop
4516 pthread_create (&u->tid, 0, l_run, EV_A);
4517 }
4518
4519The callback for the C<ev_async> watcher does nothing: the watcher is used
4520solely to wake up the event loop so it takes notice of any new watchers
4521that might have been added:
4522
4523 static void
4524 async_cb (EV_P_ ev_async *w, int revents)
4525 {
4526 // just used for the side effects
4527 }
4528
4529The C<l_release> and C<l_acquire> callbacks simply unlock/lock the mutex
4530protecting the loop data, respectively.
4531
4532 static void
4533 l_release (EV_P)
4534 {
4535 userdata *u = ev_userdata (EV_A);
4536 pthread_mutex_unlock (&u->lock);
4537 }
4538
4539 static void
4540 l_acquire (EV_P)
4541 {
4542 userdata *u = ev_userdata (EV_A);
4543 pthread_mutex_lock (&u->lock);
4544 }
4545
4546The event loop thread first acquires the mutex, and then jumps straight
4547into C<ev_run>:
4548
4549 void *
4550 l_run (void *thr_arg)
4551 {
4552 struct ev_loop *loop = (struct ev_loop *)thr_arg;
4553
4554 l_acquire (EV_A);
4555 pthread_setcanceltype (PTHREAD_CANCEL_ASYNCHRONOUS, 0);
4556 ev_run (EV_A_ 0);
4557 l_release (EV_A);
4558
4559 return 0;
4560 }
4561
4562Instead of invoking all pending watchers, the C<l_invoke> callback will
4563signal the main thread via some unspecified mechanism (signals? pipe
4564writes? C<Async::Interrupt>?) and then waits until all pending watchers
4565have been called (in a while loop because a) spurious wakeups are possible
4566and b) skipping inter-thread-communication when there are no pending
4567watchers is very beneficial):
4568
4569 static void
4570 l_invoke (EV_P)
4571 {
4572 userdata *u = ev_userdata (EV_A);
4573
4574 while (ev_pending_count (EV_A))
4575 {
4576 wake_up_other_thread_in_some_magic_or_not_so_magic_way ();
4577 pthread_cond_wait (&u->invoke_cv, &u->lock);
4578 }
4579 }
4580
4581Now, whenever the main thread gets told to invoke pending watchers, it
4582will grab the lock, call C<ev_invoke_pending> and then signal the loop
4583thread to continue:
4584
4585 static void
4586 real_invoke_pending (EV_P)
4587 {
4588 userdata *u = ev_userdata (EV_A);
4589
4590 pthread_mutex_lock (&u->lock);
4591 ev_invoke_pending (EV_A);
4592 pthread_cond_signal (&u->invoke_cv);
4593 pthread_mutex_unlock (&u->lock);
4594 }
4595
4596Whenever you want to start/stop a watcher or do other modifications to an
4597event loop, you will now have to lock:
4598
4599 ev_timer timeout_watcher;
4600 userdata *u = ev_userdata (EV_A);
4601
4602 ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
4603
4604 pthread_mutex_lock (&u->lock);
4605 ev_timer_start (EV_A_ &timeout_watcher);
4606 ev_async_send (EV_A_ &u->async_w);
4607 pthread_mutex_unlock (&u->lock);
4608
4609Note that sending the C<ev_async> watcher is required because otherwise
4610an event loop currently blocking in the kernel will have no knowledge
4611about the newly added timer. By waking up the loop it will pick up any new
4612watchers in the next event loop iteration.
4613 4642
4614=head3 COROUTINES 4643=head3 COROUTINES
4615 4644
4616Libev is very accommodating to coroutines ("cooperative threads"): 4645Libev is very accommodating to coroutines ("cooperative threads"):
4617libev fully supports nesting calls to its functions from different 4646libev fully supports nesting calls to its functions from different

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines