[ViewVC] Diff of: cvs/libev/ev.3

Comparing libev/ev.3 (file contents):
Revision 1.43 by root, Sat Dec 8 14:27:38 2007 UTC vs.
Revision 1.45 by root, Sat Dec 8 22:11:14 2007 UTC

…		…
634	libev watchers. However, a pair of \f(CW\(C`ev_prepare\(C'\fR/\f(CW\(C`ev_check\(C'\fR watchers is	634	libev watchers. However, a pair of \f(CW\(C`ev_prepare\(C'\fR/\f(CW\(C`ev_check\(C'\fR watchers is
635	usually a better approach for this kind of thing.	635	usually a better approach for this kind of thing.
636	.Sp	636	.Sp
637	Here are the gory details of what \f(CW\(C`ev_loop\(C'\fR does:	637	Here are the gory details of what \f(CW\(C`ev_loop\(C'\fR does:
638	.Sp	638	.Sp
639	.Vb 18	639	.Vb 19
		640	\& - Before the first iteration, call any pending watchers.
640	\& * If there are no active watchers (reference count is zero), return.	641	\& * If there are no active watchers (reference count is zero), return.
641	\& - Queue prepare watchers and then call all outstanding watchers.	642	\& - Queue all prepare watchers and then call all outstanding watchers.
642	\& - If we have been forked, recreate the kernel state.	643	\& - If we have been forked, recreate the kernel state.
643	\& - Update the kernel state with all outstanding changes.	644	\& - Update the kernel state with all outstanding changes.
644	\& - Update the "event loop time".	645	\& - Update the "event loop time".
645	\& - Calculate for how long to block.	646	\& - Calculate for how long to block.
646	\& - Block the process, waiting for any events.	647	\& - Block the process, waiting for any events.
…		…
1634	are ready to run (it's actually more complicated: it only runs coroutines	1635	are ready to run (it's actually more complicated: it only runs coroutines
1635	with priority higher than or equal to the event loop and one coroutine	1636	with priority higher than or equal to the event loop and one coroutine
1636	of lower priority, but only once, using idle watchers to keep the event	1637	of lower priority, but only once, using idle watchers to keep the event
1637	loop from blocking if lower-priority coroutines are active, thus mapping	1638	loop from blocking if lower-priority coroutines are active, thus mapping
1638	low-priority coroutines to idle/background tasks).	1639	low-priority coroutines to idle/background tasks).
		1640	.PP
		1641	It is recommended to give \f(CW\(C`ev_check\(C'\fR watchers highest (\f(CW\(C`EV_MAXPRI\(C'\fR)
		1642	priority, to ensure that they are being run before any other watchers
		1643	after the poll. Also, \f(CW\(C`ev_check\(C'\fR watchers (and \f(CW\(C`ev_prepare\(C'\fR watchers,
		1644	too) should not activate (\(L"feed\(R") events into libev. While libev fully
		1645	supports this, they will be called before other \f(CW\(C`ev_check\(C'\fR watchers did
		1646	their job. As \f(CW\(C`ev_check\(C'\fR watchers are often used to embed other event
		1647	loops those other event loops might be in an unusable state until their
		1648	\&\f(CW\(C`ev_check\(C'\fR watcher ran (always remind yourself to coexist peacefully with
		1649	others).
1639	.IP "ev_prepare_init (ev_prepare *, callback)" 4	1650	.IP "ev_prepare_init (ev_prepare *, callback)" 4
1640	.IX Item "ev_prepare_init (ev_prepare *, callback)"	1651	.IX Item "ev_prepare_init (ev_prepare *, callback)"
1641	.PD 0	1652	.PD 0
1642	.IP "ev_check_init (ev_check *, callback)" 4	1653	.IP "ev_check_init (ev_check *, callback)" 4
1643	.IX Item "ev_check_init (ev_check *, callback)"	1654	.IX Item "ev_check_init (ev_check *, callback)"
1644	.PD	1655	.PD
1645	Initialises and configures the prepare or check watcher \- they have no	1656	Initialises and configures the prepare or check watcher \- they have no
1646	parameters of any kind. There are \f(CW\(C`ev_prepare_set\(C'\fR and \f(CW\(C`ev_check_set\(C'\fR	1657	parameters of any kind. There are \f(CW\(C`ev_prepare_set\(C'\fR and \f(CW\(C`ev_check_set\(C'\fR
1647	macros, but using them is utterly, utterly and completely pointless.	1658	macros, but using them is utterly, utterly and completely pointless.
1648	.PP	1659	.PP
1649	Example: To include a library such as adns, you would add \s-1IO\s0 watchers	1660	There are a number of principal ways to embed other event loops or modules
1650	and a timeout watcher in a prepare handler, as required by libadns, and	1661	into libev. Here are some ideas on how to include libadns into libev
		1662	(there is a Perl module named \f(CW\(C`EV::ADNS\(C'\fR that does this, which you could
		1663	use for an actually working example. Another Perl module named \f(CW\(C`EV::Glib\(C'\fR
		1664	embeds a Glib main context into libev, and finally, \f(CW\(C`Glib::EV\(C'\fR embeds \s-1EV\s0
		1665	into the Glib event loop).
		1666	.PP
		1667	Method 1: Add \s-1IO\s0 watchers and a timeout watcher in a prepare handler,
1651	in a check watcher, destroy them and call into libadns. What follows is	1668	and in a check watcher, destroy them and call into libadns. What follows
1652	pseudo-code only of course:	1669	is pseudo-code only of course. This requires you to either use a low
		1670	priority for the check watcher or use \f(CW\(C`ev_clear_pending\(C'\fR explicitly, as
		1671	the callbacks for the IO/timeout watchers might not have been called yet.
1653	.PP	1672	.PP
1654	.Vb 2	1673	.Vb 2
1655	\& static ev_io iow [nfd];	1674	\& static ev_io iow [nfd];
1656	\& static ev_timer tw;	1675	\& static ev_timer tw;
1657	.Ve	1676	.Ve
1658	.PP	1677	.PP
1659	.Vb 9	1678	.Vb 4
1660	\& static void	1679	\& static void
1661	\& io_cb (ev_loop loop, ev_io w, int revents)	1680	\& io_cb (ev_loop loop, ev_io w, int revents)
1662	\& {	1681	\& {
1663	\& // set the relevant poll flags
1664	\& // could also call adns_processreadable etc. here
1665	\& struct pollfd fd = (struct pollfd )w->data;
1666	\& if (revents & EV_READ ) fd->revents \|= fd->events & POLLIN;
1667	\& if (revents & EV_WRITE) fd->revents \|= fd->events & POLLOUT;
1668	\& }	1682	\& }
1669	.Ve	1683	.Ve
1670	.PP	1684	.PP
1671	.Vb 8	1685	.Vb 8
1672	\& // create io watchers for each fd and a timer before blocking	1686	\& // create io watchers for each fd and a timer before blocking
…		…
1684	\& ev_timer_init (&tw, 0, timeout * 1e-3);	1698	\& ev_timer_init (&tw, 0, timeout * 1e-3);
1685	\& ev_timer_start (loop, &tw);	1699	\& ev_timer_start (loop, &tw);
1686	.Ve	1700	.Ve
1687	.PP	1701	.PP
1688	.Vb 6	1702	.Vb 6
1689	\& // create on ev_io per pollfd	1703	\& // create one ev_io per pollfd
1690	\& for (int i = 0; i < nfd; ++i)	1704	\& for (int i = 0; i < nfd; ++i)
1691	\& {	1705	\& {
1692	\& ev_io_init (iow + i, io_cb, fds [i].fd,	1706	\& ev_io_init (iow + i, io_cb, fds [i].fd,
1693	\& ((fds [i].events & POLLIN ? EV_READ : 0)	1707	\& ((fds [i].events & POLLIN ? EV_READ : 0)
1694	\& \| (fds [i].events & POLLOUT ? EV_WRITE : 0)));	1708	\& \| (fds [i].events & POLLOUT ? EV_WRITE : 0)));
1695	.Ve	1709	.Ve
1696	.PP	1710	.PP
1697	.Vb 5	1711	.Vb 4
1698	\& fds [i].revents = 0;	1712	\& fds [i].revents = 0;
1699	\& iow [i].data = fds + i;
1700	\& ev_io_start (loop, iow + i);	1713	\& ev_io_start (loop, iow + i);
1701	\& }	1714	\& }
1702	\& }	1715	\& }
1703	.Ve	1716	.Ve
1704	.PP	1717	.PP
…		…
1708	\& adns_check_cb (ev_loop loop, ev_check w, int revents)	1721	\& adns_check_cb (ev_loop loop, ev_check w, int revents)
1709	\& {	1722	\& {
1710	\& ev_timer_stop (loop, &tw);	1723	\& ev_timer_stop (loop, &tw);
1711	.Ve	1724	.Ve
1712	.PP	1725	.PP
1713	.Vb 2	1726	.Vb 8
1714	\& for (int i = 0; i < nfd; ++i)	1727	\& for (int i = 0; i < nfd; ++i)
		1728	\& {
		1729	\& // set the relevant poll flags
		1730	\& // could also call adns_processreadable etc. here
		1731	\& struct pollfd *fd = fds + i;
		1732	\& int revents = ev_clear_pending (iow + i);
		1733	\& if (revents & EV_READ ) fd->revents \|= fd->events & POLLIN;
		1734	\& if (revents & EV_WRITE) fd->revents \|= fd->events & POLLOUT;
		1735	.Ve
		1736	.PP
		1737	.Vb 3
		1738	\& // now stop the watcher
1715	\& ev_io_stop (loop, iow + i);	1739	\& ev_io_stop (loop, iow + i);
		1740	\& }
1716	.Ve	1741	.Ve
1717	.PP	1742	.PP
1718	.Vb 2	1743	.Vb 2
1719	\& adns_afterpoll (adns, fds, nfd, timeval_from (ev_now (loop));	1744	\& adns_afterpoll (adns, fds, nfd, timeval_from (ev_now (loop));
		1745	\& }
		1746	.Ve
		1747	.PP
		1748	Method 2: This would be just like method 1, but you run \f(CW\(C`adns_afterpoll\(C'\fR
		1749	in the prepare watcher and would dispose of the check watcher.
		1750	.PP
		1751	Method 3: If the module to be embedded supports explicit event
		1752	notification (adns does), you can also make use of the actual watcher
		1753	callbacks, and only destroy/create the watchers in the prepare watcher.
		1754	.PP
		1755	.Vb 5
		1756	\& static void
		1757	\& timer_cb (EV_P_ ev_timer *w, int revents)
		1758	\& {
		1759	\& adns_state ads = (adns_state)w->data;
		1760	\& update_now (EV_A);
		1761	.Ve
		1762	.PP
		1763	.Vb 2
		1764	\& adns_processtimeouts (ads, &tv_now);
		1765	\& }
		1766	.Ve
		1767	.PP
		1768	.Vb 5
		1769	\& static void
		1770	\& io_cb (EV_P_ ev_io *w, int revents)
		1771	\& {
		1772	\& adns_state ads = (adns_state)w->data;
		1773	\& update_now (EV_A);
		1774	.Ve
		1775	.PP
		1776	.Vb 3
		1777	\& if (revents & EV_READ ) adns_processreadable (ads, w->fd, &tv_now);
		1778	\& if (revents & EV_WRITE) adns_processwriteable (ads, w->fd, &tv_now);
		1779	\& }
		1780	.Ve
		1781	.PP
		1782	.Vb 1
		1783	\& // do not ever call adns_afterpoll
		1784	.Ve
		1785	.PP
		1786	Method 4: Do not use a prepare or check watcher because the module you
		1787	want to embed is too inflexible to support it. Instead, youc na override
		1788	their poll function. The drawback with this solution is that the main
		1789	loop is now no longer controllable by \s-1EV\s0. The \f(CW\(C`Glib::EV\(C'\fR module does
		1790	this.
		1791	.PP
		1792	.Vb 4
		1793	\& static gint
		1794	\& event_poll_func (GPollFD *fds, guint nfds, gint timeout)
		1795	\& {
		1796	\& int got_events = 0;
		1797	.Ve
		1798	.PP
		1799	.Vb 2
		1800	\& for (n = 0; n < nfds; ++n)
		1801	\& // create/start io watcher that sets the relevant bits in fds[n] and increment got_events
		1802	.Ve
		1803	.PP
		1804	.Vb 2
		1805	\& if (timeout >= 0)
		1806	\& // create/start timer
		1807	.Ve
		1808	.PP
		1809	.Vb 2
		1810	\& // poll
		1811	\& ev_loop (EV_A_ 0);
		1812	.Ve
		1813	.PP
		1814	.Vb 3
		1815	\& // stop timer again
		1816	\& if (timeout >= 0)
		1817	\& ev_timer_stop (EV_A_ &to);
		1818	.Ve
		1819	.PP
		1820	.Vb 3
		1821	\& // stop io watchers again - their callbacks should have set
		1822	\& for (n = 0; n < nfds; ++n)
		1823	\& ev_io_stop (EV_A_ iow [n]);
		1824	.Ve
		1825	.PP
		1826	.Vb 2
		1827	\& return got_events;
1720	\& }	1828	\& }
1721	.Ve	1829	.Ve
1722	.ie n .Sh """ev_embed"" \- when one backend isn't enough..."	1830	.ie n .Sh """ev_embed"" \- when one backend isn't enough..."
1723	.el .Sh "\f(CWev_embed\fP \- when one backend isn't enough..."	1831	.el .Sh "\f(CWev_embed\fP \- when one backend isn't enough..."
1724	.IX Subsection "ev_embed - when one backend isn't enough..."	1832	.IX Subsection "ev_embed - when one backend isn't enough..."

Diff Legend

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

Comparing libev/ev.3 (file contents): Revision 1.43 by root, Sat Dec 8 14:27:38 2007 UTC vs. Revision 1.45 by root, Sat Dec 8 22:11:14 2007 UTC

Diff Legend

Comparing libev/ev.3 (file contents):
Revision 1.43 by root, Sat Dec 8 14:27:38 2007 UTC vs.
Revision 1.45 by root, Sat Dec 8 22:11:14 2007 UTC