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

Comparing libev/ev.3 (file contents):
Revision 1.19 by root, Sat Nov 24 16:57:38 2007 UTC vs.
Revision 1.20 by root, Mon Nov 26 09:52:14 2007 UTC

…		…
127	.\}	127	.\}
128	.rm #[ #] #H #V #F C	128	.rm #[ #] #H #V #F C
129	.\" ========================================================================	129	.\" ========================================================================
130	.\"	130	.\"
131	.IX Title ""<STANDARD INPUT>" 1"	131	.IX Title ""<STANDARD INPUT>" 1"
132	.TH "<STANDARD INPUT>" 1 "2007-11-24" "perl v5.8.8" "User Contributed Perl Documentation"	132	.TH "<STANDARD INPUT>" 1 "2007-11-26" "perl v5.8.8" "User Contributed Perl Documentation"
133	.SH "NAME"	133	.SH "NAME"
134	libev \- a high performance full\-featured event loop written in C	134	libev \- a high performance full\-featured event loop written in C
135	.SH "SYNOPSIS"	135	.SH "SYNOPSIS"
136	.IX Header "SYNOPSIS"	136	.IX Header "SYNOPSIS"
137	.Vb 1	137	.Vb 1
…		…
1242	.IX Subsection "ev_prepare and ev_check - customise your event loop!"	1242	.IX Subsection "ev_prepare and ev_check - customise your event loop!"
1243	Prepare and check watchers are usually (but not always) used in tandem:	1243	Prepare and check watchers are usually (but not always) used in tandem:
1244	prepare watchers get invoked before the process blocks and check watchers	1244	prepare watchers get invoked before the process blocks and check watchers
1245	afterwards.	1245	afterwards.
1246	.PP	1246	.PP
		1247	You \fImust not\fR call \f(CW\(C`ev_loop\(C'\fR or similar functions that enter
		1248	the current event loop from either \f(CW\(C`ev_prepare\(C'\fR or \f(CW\(C`ev_check\(C'\fR
		1249	watchers. Other loops than the current one are fine, however. The
		1250	rationale behind this is that you do not need to check for recursion in
		1251	those watchers, i.e. the sequence will always be \f(CW\(C`ev_prepare\(C'\fR, blocking,
		1252	\&\f(CW\(C`ev_check\(C'\fR so if you have one watcher of each kind they will always be
		1253	called in pairs bracketing the blocking call.
		1254	.PP
1247	Their main purpose is to integrate other event mechanisms into libev and	1255	Their main purpose is to integrate other event mechanisms into libev and
1248	their use is somewhat advanced. This could be used, for example, to track	1256	their use is somewhat advanced. This could be used, for example, to track
1249	variable changes, implement your own watchers, integrate net-snmp or a	1257	variable changes, implement your own watchers, integrate net-snmp or a
1250	coroutine library and lots more.	1258	coroutine library and lots more. They are also occasionally useful if
		1259	you cache some data and want to flush it before blocking (for example,
		1260	in X programs you might want to do an \f(CW\(C`XFlush ()\(C'\fR in an \f(CW\(C`ev_prepare\(C'\fR
		1261	watcher).
1251	.PP	1262	.PP
1252	This is done by examining in each prepare call which file descriptors need	1263	This is done by examining in each prepare call which file descriptors need
1253	to be watched by the other library, registering \f(CW\(C`ev_io\(C'\fR watchers for	1264	to be watched by the other library, registering \f(CW\(C`ev_io\(C'\fR watchers for
1254	them and starting an \f(CW\(C`ev_timer\(C'\fR watcher for any timeouts (many libraries	1265	them and starting an \f(CW\(C`ev_timer\(C'\fR watcher for any timeouts (many libraries
1255	provide just this functionality). Then, in the check watcher you check for	1266	provide just this functionality). Then, in the check watcher you check for
…		…
1274	.PD	1285	.PD
1275	Initialises and configures the prepare or check watcher \- they have no	1286	Initialises and configures the prepare or check watcher \- they have no
1276	parameters of any kind. There are \f(CW\(C`ev_prepare_set\(C'\fR and \f(CW\(C`ev_check_set\(C'\fR	1287	parameters of any kind. There are \f(CW\(C`ev_prepare_set\(C'\fR and \f(CW\(C`ev_check_set\(C'\fR
1277	macros, but using them is utterly, utterly and completely pointless.	1288	macros, but using them is utterly, utterly and completely pointless.
1278	.PP	1289	.PP
1279	Example: TODO.	1290	Example: To include a library such as adns, you would add \s-1IO\s0 watchers
		1291	and a timeout watcher in a prepare handler, as required by libadns, and
		1292	in a check watcher, destroy them and call into libadns. What follows is
		1293	pseudo-code only of course:
		1294	.PP
		1295	.Vb 2
		1296	\& static ev_io iow [nfd];
		1297	\& static ev_timer tw;
		1298	.Ve
		1299	.PP
		1300	.Vb 8
		1301	\& static void
		1302	\& io_cb (ev_loop loop, ev_io w, int revents)
		1303	\& {
		1304	\& // set the relevant poll flags
		1305	\& struct pollfd fd = (struct pollfd )w->data;
		1306	\& if (revents & EV_READ ) fd->revents \|= fd->events & POLLIN;
		1307	\& if (revents & EV_WRITE) fd->revents \|= fd->events & POLLOUT;
		1308	\& }
		1309	.Ve
		1310	.PP
		1311	.Vb 7
		1312	\& // create io watchers for each fd and a timer before blocking
		1313	\& static void
		1314	\& adns_prepare_cb (ev_loop loop, ev_prepare w, int revents)
		1315	\& {
		1316	\& int timeout = 3600000;truct pollfd fds [nfd];
		1317	\& // actual code will need to loop here and realloc etc.
		1318	\& adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ()));
		1319	.Ve
		1320	.PP
		1321	.Vb 3
		1322	\& /* the callback is illegal, but won't be called as we stop during check */
		1323	\& ev_timer_init (&tw, 0, timeout * 1e-3);
		1324	\& ev_timer_start (loop, &tw);
		1325	.Ve
		1326	.PP
		1327	.Vb 6
		1328	\& // create on ev_io per pollfd
		1329	\& for (int i = 0; i < nfd; ++i)
		1330	\& {
		1331	\& ev_io_init (iow + i, io_cb, fds [i].fd,
		1332	\& ((fds [i].events & POLLIN ? EV_READ : 0)
		1333	\& \| (fds [i].events & POLLOUT ? EV_WRITE : 0)));
		1334	.Ve
		1335	.PP
		1336	.Vb 5
		1337	\& fds [i].revents = 0;
		1338	\& iow [i].data = fds + i;
		1339	\& ev_io_start (loop, iow + i);
		1340	\& }
		1341	\& }
		1342	.Ve
		1343	.PP
		1344	.Vb 5
		1345	\& // stop all watchers after blocking
		1346	\& static void
		1347	\& adns_check_cb (ev_loop loop, ev_check w, int revents)
		1348	\& {
		1349	\& ev_timer_stop (loop, &tw);
		1350	.Ve
		1351	.PP
		1352	.Vb 2
		1353	\& for (int i = 0; i < nfd; ++i)
		1354	\& ev_io_stop (loop, iow + i);
		1355	.Ve
		1356	.PP
		1357	.Vb 2
		1358	\& adns_afterpoll (adns, fds, nfd, timeval_from (ev_now (loop));
		1359	\& }
		1360	.Ve
1280	.ie n .Sh """ev_embed"" \- when one backend isn't enough..."	1361	.ie n .Sh """ev_embed"" \- when one backend isn't enough..."
1281	.el .Sh "\f(CWev_embed\fP \- when one backend isn't enough..."	1362	.el .Sh "\f(CWev_embed\fP \- when one backend isn't enough..."
1282	.IX Subsection "ev_embed - when one backend isn't enough..."	1363	.IX Subsection "ev_embed - when one backend isn't enough..."
1283	This is a rather advanced watcher type that lets you embed one event loop	1364	This is a rather advanced watcher type that lets you embed one event loop
1284	into another (currently only \f(CW\(C`ev_io\(C'\fR events are supported in the embedded	1365	into another (currently only \f(CW\(C`ev_io\(C'\fR events are supported in the embedded

Diff Legend

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

Comparing libev/ev.3 (file contents): Revision 1.19 by root, Sat Nov 24 16:57:38 2007 UTC vs. Revision 1.20 by root, Mon Nov 26 09:52:14 2007 UTC

Diff Legend

Comparing libev/ev.3 (file contents):
Revision 1.19 by root, Sat Nov 24 16:57:38 2007 UTC vs.
Revision 1.20 by root, Mon Nov 26 09:52:14 2007 UTC