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

Comparing libev/ev.3 (file contents):
Revision 1.17 by root, Sat Nov 24 16:31:45 2007 UTC vs.
Revision 1.22 by root, Tue Nov 27 08:11:52 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-27" "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
…		…
684	The signal specified in the \f(CW\(C`ev_signal\(C'\fR watcher has been received by a thread.	684	The signal specified in the \f(CW\(C`ev_signal\(C'\fR watcher has been received by a thread.
685	.ie n .IP """EV_CHILD""" 4	685	.ie n .IP """EV_CHILD""" 4
686	.el .IP "\f(CWEV_CHILD\fR" 4	686	.el .IP "\f(CWEV_CHILD\fR" 4
687	.IX Item "EV_CHILD"	687	.IX Item "EV_CHILD"
688	The pid specified in the \f(CW\(C`ev_child\(C'\fR watcher has received a status change.	688	The pid specified in the \f(CW\(C`ev_child\(C'\fR watcher has received a status change.
		689	.ie n .IP """EV_STAT""" 4
		690	.el .IP "\f(CWEV_STAT\fR" 4
		691	.IX Item "EV_STAT"
		692	The path specified in the \f(CW\(C`ev_stat\(C'\fR watcher changed its attributes somehow.
689	.ie n .IP """EV_IDLE""" 4	693	.ie n .IP """EV_IDLE""" 4
690	.el .IP "\f(CWEV_IDLE\fR" 4	694	.el .IP "\f(CWEV_IDLE\fR" 4
691	.IX Item "EV_IDLE"	695	.IX Item "EV_IDLE"
692	The \f(CW\(C`ev_idle\(C'\fR watcher has determined that you have nothing better to do.	696	The \f(CW\(C`ev_idle\(C'\fR watcher has determined that you have nothing better to do.
693	.ie n .IP """EV_PREPARE""" 4	697	.ie n .IP """EV_PREPARE""" 4
…		…
821	More interesting and less C\-conformant ways of catsing your callback type	825	More interesting and less C\-conformant ways of catsing your callback type
822	have been omitted....	826	have been omitted....
823	.SH "WATCHER TYPES"	827	.SH "WATCHER TYPES"
824	.IX Header "WATCHER TYPES"	828	.IX Header "WATCHER TYPES"
825	This section describes each watcher in detail, but will not repeat	829	This section describes each watcher in detail, but will not repeat
826	information given in the last section.	830	information given in the last section. Any initialisation/set macros,
		831	functions and members specific to the watcher type are explained.
		832	.PP
		833	Members are additionally marked with either \fI[read\-only]\fR, meaning that,
		834	while the watcher is active, you can look at the member and expect some
		835	sensible content, but you must not modify it (you can modify it while the
		836	watcher is stopped to your hearts content), or \fI[read\-write]\fR, which
		837	means you can expect it to have some sensible content while the watcher
		838	is active, but you can also modify it. Modifying it may not do something
		839	sensible or take immediate effect (or do anything at all), but libev will
		840	not crash or malfunction in any way.
827	.ie n .Sh """ev_io"" \- is this file descriptor readable or writable?"	841	.ie n .Sh """ev_io"" \- is this file descriptor readable or writable?"
828	.el .Sh "\f(CWev_io\fP \- is this file descriptor readable or writable?"	842	.el .Sh "\f(CWev_io\fP \- is this file descriptor readable or writable?"
829	.IX Subsection "ev_io - is this file descriptor readable or writable?"	843	.IX Subsection "ev_io - is this file descriptor readable or writable?"
830	I/O watchers check whether a file descriptor is readable or writable	844	I/O watchers check whether a file descriptor is readable or writable
831	in each iteration of the event loop, or, more precisely, when reading	845	in each iteration of the event loop, or, more precisely, when reading
…		…
871	.IX Item "ev_io_set (ev_io *, int fd, int events)"	885	.IX Item "ev_io_set (ev_io *, int fd, int events)"
872	.PD	886	.PD
873	Configures an \f(CW\(C`ev_io\(C'\fR watcher. The \f(CW\(C`fd\(C'\fR is the file descriptor to	887	Configures an \f(CW\(C`ev_io\(C'\fR watcher. The \f(CW\(C`fd\(C'\fR is the file descriptor to
874	rceeive events for and events is either \f(CW\(C`EV_READ\(C'\fR, \f(CW\(C`EV_WRITE\(C'\fR or	888	rceeive events for and events is either \f(CW\(C`EV_READ\(C'\fR, \f(CW\(C`EV_WRITE\(C'\fR or
875	\&\f(CW\(C`EV_READ \| EV_WRITE\(C'\fR to receive the given events.	889	\&\f(CW\(C`EV_READ \| EV_WRITE\(C'\fR to receive the given events.
		890	.IP "int fd [read\-only]" 4
		891	.IX Item "int fd [read-only]"
		892	The file descriptor being watched.
		893	.IP "int events [read\-only]" 4
		894	.IX Item "int events [read-only]"
		895	The events being watched.
876	.PP	896	.PP
877	Example: call \f(CW\(C`stdin_readable_cb\(C'\fR when \s-1STDIN_FILENO\s0 has become, well	897	Example: call \f(CW\(C`stdin_readable_cb\(C'\fR when \s-1STDIN_FILENO\s0 has become, well
878	readable, but only once. Since it is likely line\-buffered, you could	898	readable, but only once. Since it is likely line\-buffered, you could
879	attempt to read a whole line in the callback:	899	attempt to read a whole line in the callback:
880	.PP	900	.PP
…		…
945	.Sp	965	.Sp
946	If the timer is repeating, either start it if necessary (with the repeat	966	If the timer is repeating, either start it if necessary (with the repeat
947	value), or reset the running timer to the repeat value.	967	value), or reset the running timer to the repeat value.
948	.Sp	968	.Sp
949	This sounds a bit complicated, but here is a useful and typical	969	This sounds a bit complicated, but here is a useful and typical
950	example: Imagine you have a tcp connection and you want a so-called idle	970	example: Imagine you have a tcp connection and you want a so-called
951	timeout, that is, you want to be called when there have been, say, 60	971	idle timeout, that is, you want to be called when there have been,
952	seconds of inactivity on the socket. The easiest way to do this is to	972	say, 60 seconds of inactivity on the socket. The easiest way to do
953	configure an \f(CW\(C`ev_timer\(C'\fR with after=repeat=60 and calling ev_timer_again each	973	this is to configure an \f(CW\(C`ev_timer\(C'\fR with \f(CW\(C`after\(C'\fR=\f(CW\(C`repeat\(C'\fR=\f(CW60\fR and calling
954	time you successfully read or write some data. If you go into an idle	974	\&\f(CW\(C`ev_timer_again\(C'\fR each time you successfully read or write some data. If
955	state where you do not expect data to travel on the socket, you can stop	975	you go into an idle state where you do not expect data to travel on the
956	the timer, and again will automatically restart it if need be.	976	socket, you can stop the timer, and again will automatically restart it if
		977	need be.
		978	.Sp
		979	You can also ignore the \f(CW\(C`after\(C'\fR value and \f(CW\(C`ev_timer_start\(C'\fR altogether
		980	and only ever use the \f(CW\(C`repeat\(C'\fR value:
		981	.Sp
		982	.Vb 8
		983	\& ev_timer_init (timer, callback, 0., 5.);
		984	\& ev_timer_again (loop, timer);
		985	\& ...
		986	\& timer->again = 17.;
		987	\& ev_timer_again (loop, timer);
		988	\& ...
		989	\& timer->again = 10.;
		990	\& ev_timer_again (loop, timer);
		991	.Ve
		992	.Sp
		993	This is more efficient then stopping/starting the timer eahc time you want
		994	to modify its timeout value.
		995	.IP "ev_tstamp repeat [read\-write]" 4
		996	.IX Item "ev_tstamp repeat [read-write]"
		997	The current \f(CW\(C`repeat\(C'\fR value. Will be used each time the watcher times out
		998	or \f(CW\(C`ev_timer_again\(C'\fR is called and determines the next timeout (if any),
		999	which is also when any modifications are taken into account.
957	.PP	1000	.PP
958	Example: create a timer that fires after 60 seconds.	1001	Example: create a timer that fires after 60 seconds.
959	.PP	1002	.PP
960	.Vb 5	1003	.Vb 5
961	\& static void	1004	\& static void
…		…
1093	.IX Item "ev_periodic_again (loop, ev_periodic *)"	1136	.IX Item "ev_periodic_again (loop, ev_periodic *)"
1094	Simply stops and restarts the periodic watcher again. This is only useful	1137	Simply stops and restarts the periodic watcher again. This is only useful
1095	when you changed some parameters or the reschedule callback would return	1138	when you changed some parameters or the reschedule callback would return
1096	a different time than the last time it was called (e.g. in a crond like	1139	a different time than the last time it was called (e.g. in a crond like
1097	program when the crontabs have changed).	1140	program when the crontabs have changed).
		1141	.IP "ev_tstamp interval [read\-write]" 4
		1142	.IX Item "ev_tstamp interval [read-write]"
		1143	The current interval value. Can be modified any time, but changes only
		1144	take effect when the periodic timer fires or \f(CW\(C`ev_periodic_again\(C'\fR is being
		1145	called.
		1146	.IP "ev_tstamp (reschedule_cb)(struct ev_periodic w, ev_tstamp now) [read\-write]" 4
		1147	.IX Item "ev_tstamp (reschedule_cb)(struct ev_periodic w, ev_tstamp now) [read-write]"
		1148	The current reschedule callback, or \f(CW0\fR, if this functionality is
		1149	switched off. Can be changed any time, but changes only take effect when
		1150	the periodic timer fires or \f(CW\(C`ev_periodic_again\(C'\fR is being called.
1098	.PP	1151	.PP
1099	Example: call a callback every hour, or, more precisely, whenever the	1152	Example: call a callback every hour, or, more precisely, whenever the
1100	system clock is divisible by 3600. The callback invocation times have	1153	system clock is divisible by 3600. The callback invocation times have
1101	potentially a lot of jittering, but good long-term stability.	1154	potentially a lot of jittering, but good long-term stability.
1102	.PP	1155	.PP
…		…
1160	.IP "ev_signal_set (ev_signal *, int signum)" 4	1213	.IP "ev_signal_set (ev_signal *, int signum)" 4
1161	.IX Item "ev_signal_set (ev_signal *, int signum)"	1214	.IX Item "ev_signal_set (ev_signal *, int signum)"
1162	.PD	1215	.PD
1163	Configures the watcher to trigger on the given signal number (usually one	1216	Configures the watcher to trigger on the given signal number (usually one
1164	of the \f(CW\(C`SIGxxx\(C'\fR constants).	1217	of the \f(CW\(C`SIGxxx\(C'\fR constants).
		1218	.IP "int signum [read\-only]" 4
		1219	.IX Item "int signum [read-only]"
		1220	The signal the watcher watches out for.
1165	.ie n .Sh """ev_child"" \- watch out for process status changes"	1221	.ie n .Sh """ev_child"" \- watch out for process status changes"
1166	.el .Sh "\f(CWev_child\fP \- watch out for process status changes"	1222	.el .Sh "\f(CWev_child\fP \- watch out for process status changes"
1167	.IX Subsection "ev_child - watch out for process status changes"	1223	.IX Subsection "ev_child - watch out for process status changes"
1168	Child watchers trigger when your process receives a \s-1SIGCHLD\s0 in response to	1224	Child watchers trigger when your process receives a \s-1SIGCHLD\s0 in response to
1169	some child status changes (most typically when a child of yours dies).	1225	some child status changes (most typically when a child of yours dies).
…		…
1177	\&\fIany\fR process if \f(CW\(C`pid\(C'\fR is specified as \f(CW0\fR). The callback can look	1233	\&\fIany\fR process if \f(CW\(C`pid\(C'\fR is specified as \f(CW0\fR). The callback can look
1178	at the \f(CW\(C`rstatus\(C'\fR member of the \f(CW\(C`ev_child\(C'\fR watcher structure to see	1234	at the \f(CW\(C`rstatus\(C'\fR member of the \f(CW\(C`ev_child\(C'\fR watcher structure to see
1179	the status word (use the macros from \f(CW\(C`sys/wait.h\(C'\fR and see your systems	1235	the status word (use the macros from \f(CW\(C`sys/wait.h\(C'\fR and see your systems
1180	\&\f(CW\(C`waitpid\(C'\fR documentation). The \f(CW\(C`rpid\(C'\fR member contains the pid of the	1236	\&\f(CW\(C`waitpid\(C'\fR documentation). The \f(CW\(C`rpid\(C'\fR member contains the pid of the
1181	process causing the status change.	1237	process causing the status change.
		1238	.IP "int pid [read\-only]" 4
		1239	.IX Item "int pid [read-only]"
		1240	The process id this watcher watches out for, or \f(CW0\fR, meaning any process id.
		1241	.IP "int rpid [read\-write]" 4
		1242	.IX Item "int rpid [read-write]"
		1243	The process id that detected a status change.
		1244	.IP "int rstatus [read\-write]" 4
		1245	.IX Item "int rstatus [read-write]"
		1246	The process exit/trace status caused by \f(CW\(C`rpid\(C'\fR (see your systems
		1247	\&\f(CW\(C`waitpid\(C'\fR and \f(CW\(C`sys/wait.h\(C'\fR documentation for details).
1182	.PP	1248	.PP
1183	Example: try to exit cleanly on \s-1SIGINT\s0 and \s-1SIGTERM\s0.	1249	Example: try to exit cleanly on \s-1SIGINT\s0 and \s-1SIGTERM\s0.
1184	.PP	1250	.PP
1185	.Vb 5	1251	.Vb 5
1186	\& static void	1252	\& static void
…		…
1192	.PP	1258	.PP
1193	.Vb 3	1259	.Vb 3
1194	\& struct ev_signal signal_watcher;	1260	\& struct ev_signal signal_watcher;
1195	\& ev_signal_init (&signal_watcher, sigint_cb, SIGINT);	1261	\& ev_signal_init (&signal_watcher, sigint_cb, SIGINT);
1196	\& ev_signal_start (loop, &sigint_cb);	1262	\& ev_signal_start (loop, &sigint_cb);
		1263	.Ve
		1264	.ie n .Sh """ev_stat"" \- did the file attributes just change?"
		1265	.el .Sh "\f(CWev_stat\fP \- did the file attributes just change?"
		1266	.IX Subsection "ev_stat - did the file attributes just change?"
		1267	This watches a filesystem path for attribute changes. That is, it calls
		1268	\&\f(CW\(C`stat\(C'\fR regularly (or when the \s-1OS\s0 says it changed) and sees if it changed
		1269	compared to the last time, invoking the callback if it did.
		1270	.PP
		1271	The path does not need to exist: changing from \(L"path exists\(R" to \*(L"path does
		1272	not exist\(R" is a status change like any other. The condition \(L"path does
		1273	not exist\(R" is signified by the \f(CW\(C`st_nlink\*(C'\fR field being zero (which is
		1274	otherwise always forced to be at least one) and all the other fields of
		1275	the stat buffer having unspecified contents.
		1276	.PP
		1277	Since there is no standard to do this, the portable implementation simply
		1278	calls \f(CW\(C`stat (2)\(C'\fR regulalry on the path to see if it changed somehow. You
		1279	can specify a recommended polling interval for this case. If you specify
		1280	a polling interval of \f(CW0\fR (highly recommended!) then a \fIsuitable,
		1281	unspecified default\fR value will be used (which you can expect to be around
		1282	five seconds, although this might change dynamically). Libev will also
		1283	impose a minimum interval which is currently around \f(CW0.1\fR, but thats
		1284	usually overkill.
		1285	.PP
		1286	This watcher type is not meant for massive numbers of stat watchers,
		1287	as even with OS-supported change notifications, this can be
		1288	resource\-intensive.
		1289	.PP
		1290	At the time of this writing, no specific \s-1OS\s0 backends are implemented, but
		1291	if demand increases, at least a kqueue and inotify backend will be added.
		1292	.IP "ev_stat_init (ev_stat , callback, const char path, ev_tstamp interval)" 4
		1293	.IX Item "ev_stat_init (ev_stat , callback, const char path, ev_tstamp interval)"
		1294	.PD 0
		1295	.IP "ev_stat_set (ev_stat , const char path, ev_tstamp interval)" 4
		1296	.IX Item "ev_stat_set (ev_stat , const char path, ev_tstamp interval)"
		1297	.PD
		1298	Configures the watcher to wait for status changes of the given
		1299	\&\f(CW\(C`path\(C'\fR. The \f(CW\(C`interval\(C'\fR is a hint on how quickly a change is expected to
		1300	be detected and should normally be specified as \f(CW0\fR to let libev choose
		1301	a suitable value. The memory pointed to by \f(CW\(C`path\(C'\fR must point to the same
		1302	path for as long as the watcher is active.
		1303	.Sp
		1304	The callback will be receive \f(CW\(C`EV_STAT\(C'\fR when a change was detected,
		1305	relative to the attributes at the time the watcher was started (or the
		1306	last change was detected).
		1307	.IP "ev_stat_stat (ev_stat *)" 4
		1308	.IX Item "ev_stat_stat (ev_stat *)"
		1309	Updates the stat buffer immediately with new values. If you change the
		1310	watched path in your callback, you could call this fucntion to avoid
		1311	detecting this change (while introducing a race condition). Can also be
		1312	useful simply to find out the new values.
		1313	.IP "ev_statdata attr [read\-only]" 4
		1314	.IX Item "ev_statdata attr [read-only]"
		1315	The most-recently detected attributes of the file. Although the type is of
		1316	\&\f(CW\(C`ev_statdata\(C'\fR, this is usually the (or one of the) \f(CW\(C`struct stat\(C'\fR types
		1317	suitable for your system. If the \f(CW\(C`st_nlink\(C'\fR member is \f(CW0\fR, then there
		1318	was some error while \f(CW\(C`stat\(C'\fRing the file.
		1319	.IP "ev_statdata prev [read\-only]" 4
		1320	.IX Item "ev_statdata prev [read-only]"
		1321	The previous attributes of the file. The callback gets invoked whenever
		1322	\&\f(CW\(C`prev\(C'\fR != \f(CW\(C`attr\(C'\fR.
		1323	.IP "ev_tstamp interval [read\-only]" 4
		1324	.IX Item "ev_tstamp interval [read-only]"
		1325	The specified interval.
		1326	.IP "const char *path [read\-only]" 4
		1327	.IX Item "const char *path [read-only]"
		1328	The filesystem path that is being watched.
		1329	.PP
		1330	Example: Watch \f(CW\(C`/etc/passwd\(C'\fR for attribute changes.
		1331	.PP
		1332	.Vb 15
		1333	\& static void
		1334	\& passwd_cb (struct ev_loop loop, ev_stat w, int revents)
		1335	\& {
		1336	\& /* /etc/passwd changed in some way */
		1337	\& if (w->attr.st_nlink)
		1338	\& {
		1339	\& printf ("passwd current size %ld\en", (long)w->attr.st_size);
		1340	\& printf ("passwd current atime %ld\en", (long)w->attr.st_mtime);
		1341	\& printf ("passwd current mtime %ld\en", (long)w->attr.st_mtime);
		1342	\& }
		1343	\& else
		1344	\& /* you shalt not abuse printf for puts */
		1345	\& puts ("wow, /etc/passwd is not there, expect problems. "
		1346	\& "if this is windows, they already arrived\en");
		1347	\& }
		1348	.Ve
		1349	.PP
		1350	.Vb 2
		1351	\& ...
		1352	\& ev_stat passwd;
		1353	.Ve
		1354	.PP
		1355	.Vb 2
		1356	\& ev_stat_init (&passwd, passwd_cb, "/etc/passwd");
		1357	\& ev_stat_start (loop, &passwd);
1197	.Ve	1358	.Ve
1198	.ie n .Sh """ev_idle"" \- when you've got nothing better to do..."	1359	.ie n .Sh """ev_idle"" \- when you've got nothing better to do..."
1199	.el .Sh "\f(CWev_idle\fP \- when you've got nothing better to do..."	1360	.el .Sh "\f(CWev_idle\fP \- when you've got nothing better to do..."
1200	.IX Subsection "ev_idle - when you've got nothing better to do..."	1361	.IX Subsection "ev_idle - when you've got nothing better to do..."
1201	Idle watchers trigger events when there are no other events are pending	1362	Idle watchers trigger events when there are no other events are pending
…		…
1242	.IX Subsection "ev_prepare and ev_check - customise your event loop!"	1403	.IX Subsection "ev_prepare and ev_check - customise your event loop!"
1243	Prepare and check watchers are usually (but not always) used in tandem:	1404	Prepare and check watchers are usually (but not always) used in tandem:
1244	prepare watchers get invoked before the process blocks and check watchers	1405	prepare watchers get invoked before the process blocks and check watchers
1245	afterwards.	1406	afterwards.
1246	.PP	1407	.PP
		1408	You \fImust not\fR call \f(CW\(C`ev_loop\(C'\fR or similar functions that enter
		1409	the current event loop from either \f(CW\(C`ev_prepare\(C'\fR or \f(CW\(C`ev_check\(C'\fR
		1410	watchers. Other loops than the current one are fine, however. The
		1411	rationale behind this is that you do not need to check for recursion in
		1412	those watchers, i.e. the sequence will always be \f(CW\(C`ev_prepare\(C'\fR, blocking,
		1413	\&\f(CW\(C`ev_check\(C'\fR so if you have one watcher of each kind they will always be
		1414	called in pairs bracketing the blocking call.
		1415	.PP
1247	Their main purpose is to integrate other event mechanisms into libev and	1416	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	1417	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	1418	variable changes, implement your own watchers, integrate net-snmp or a
1250	coroutine library and lots more.	1419	coroutine library and lots more. They are also occasionally useful if
		1420	you cache some data and want to flush it before blocking (for example,
		1421	in X programs you might want to do an \f(CW\(C`XFlush ()\(C'\fR in an \f(CW\(C`ev_prepare\(C'\fR
		1422	watcher).
1251	.PP	1423	.PP
1252	This is done by examining in each prepare call which file descriptors need	1424	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	1425	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	1426	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	1427	provide just this functionality). Then, in the check watcher you check for
…		…
1274	.PD	1446	.PD
1275	Initialises and configures the prepare or check watcher \- they have no	1447	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	1448	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.	1449	macros, but using them is utterly, utterly and completely pointless.
1278	.PP	1450	.PP
1279	Example: TODO.	1451	Example: To include a library such as adns, you would add \s-1IO\s0 watchers
		1452	and a timeout watcher in a prepare handler, as required by libadns, and
		1453	in a check watcher, destroy them and call into libadns. What follows is
		1454	pseudo-code only of course:
		1455	.PP
		1456	.Vb 2
		1457	\& static ev_io iow [nfd];
		1458	\& static ev_timer tw;
		1459	.Ve
		1460	.PP
		1461	.Vb 9
		1462	\& static void
		1463	\& io_cb (ev_loop loop, ev_io w, int revents)
		1464	\& {
		1465	\& // set the relevant poll flags
		1466	\& // could also call adns_processreadable etc. here
		1467	\& struct pollfd fd = (struct pollfd )w->data;
		1468	\& if (revents & EV_READ ) fd->revents \|= fd->events & POLLIN;
		1469	\& if (revents & EV_WRITE) fd->revents \|= fd->events & POLLOUT;
		1470	\& }
		1471	.Ve
		1472	.PP
		1473	.Vb 7
		1474	\& // create io watchers for each fd and a timer before blocking
		1475	\& static void
		1476	\& adns_prepare_cb (ev_loop loop, ev_prepare w, int revents)
		1477	\& {
		1478	\& int timeout = 3600000;truct pollfd fds [nfd];
		1479	\& // actual code will need to loop here and realloc etc.
		1480	\& adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ()));
		1481	.Ve
		1482	.PP
		1483	.Vb 3
		1484	\& /* the callback is illegal, but won't be called as we stop during check */
		1485	\& ev_timer_init (&tw, 0, timeout * 1e-3);
		1486	\& ev_timer_start (loop, &tw);
		1487	.Ve
		1488	.PP
		1489	.Vb 6
		1490	\& // create on ev_io per pollfd
		1491	\& for (int i = 0; i < nfd; ++i)
		1492	\& {
		1493	\& ev_io_init (iow + i, io_cb, fds [i].fd,
		1494	\& ((fds [i].events & POLLIN ? EV_READ : 0)
		1495	\& \| (fds [i].events & POLLOUT ? EV_WRITE : 0)));
		1496	.Ve
		1497	.PP
		1498	.Vb 5
		1499	\& fds [i].revents = 0;
		1500	\& iow [i].data = fds + i;
		1501	\& ev_io_start (loop, iow + i);
		1502	\& }
		1503	\& }
		1504	.Ve
		1505	.PP
		1506	.Vb 5
		1507	\& // stop all watchers after blocking
		1508	\& static void
		1509	\& adns_check_cb (ev_loop loop, ev_check w, int revents)
		1510	\& {
		1511	\& ev_timer_stop (loop, &tw);
		1512	.Ve
		1513	.PP
		1514	.Vb 2
		1515	\& for (int i = 0; i < nfd; ++i)
		1516	\& ev_io_stop (loop, iow + i);
		1517	.Ve
		1518	.PP
		1519	.Vb 2
		1520	\& adns_afterpoll (adns, fds, nfd, timeval_from (ev_now (loop));
		1521	\& }
		1522	.Ve
1280	.ie n .Sh """ev_embed"" \- when one backend isn't enough..."	1523	.ie n .Sh """ev_embed"" \- when one backend isn't enough..."
1281	.el .Sh "\f(CWev_embed\fP \- when one backend isn't enough..."	1524	.el .Sh "\f(CWev_embed\fP \- when one backend isn't enough..."
1282	.IX Subsection "ev_embed - when one backend isn't enough..."	1525	.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	1526	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	1527	into another (currently only \f(CW\(C`ev_io\(C'\fR events are supported in the embedded
…		…
1367	.IP "ev_embed_sweep (loop, ev_embed *)" 4	1610	.IP "ev_embed_sweep (loop, ev_embed *)" 4
1368	.IX Item "ev_embed_sweep (loop, ev_embed *)"	1611	.IX Item "ev_embed_sweep (loop, ev_embed *)"
1369	Make a single, non-blocking sweep over the embedded loop. This works	1612	Make a single, non-blocking sweep over the embedded loop. This works
1370	similarly to \f(CW\(C`ev_loop (embedded_loop, EVLOOP_NONBLOCK)\(C'\fR, but in the most	1613	similarly to \f(CW\(C`ev_loop (embedded_loop, EVLOOP_NONBLOCK)\(C'\fR, but in the most
1371	apropriate way for embedded loops.	1614	apropriate way for embedded loops.
		1615	.IP "struct ev_loop *loop [read\-only]" 4
		1616	.IX Item "struct ev_loop *loop [read-only]"
		1617	The embedded event loop.
1372	.SH "OTHER FUNCTIONS"	1618	.SH "OTHER FUNCTIONS"
1373	.IX Header "OTHER FUNCTIONS"	1619	.IX Header "OTHER FUNCTIONS"
1374	There are some other functions of possible interest. Described. Here. Now.	1620	There are some other functions of possible interest. Described. Here. Now.
1375	.IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 4	1621	.IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 4
1376	.IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)"	1622	.IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)"
…		…
1599	.Vb 1	1845	.Vb 1
1600	\& ev_win32.c required on win32 platforms only	1846	\& ev_win32.c required on win32 platforms only
1601	.Ve	1847	.Ve
1602	.PP	1848	.PP
1603	.Vb 5	1849	.Vb 5
1604	\& ev_select.c only when select backend is enabled (which is is by default)	1850	\& ev_select.c only when select backend is enabled (which is by default)
1605	\& ev_poll.c only when poll backend is enabled (disabled by default)	1851	\& ev_poll.c only when poll backend is enabled (disabled by default)
1606	\& ev_epoll.c only when the epoll backend is enabled (disabled by default)	1852	\& ev_epoll.c only when the epoll backend is enabled (disabled by default)
1607	\& ev_kqueue.c only when the kqueue backend is enabled (disabled by default)	1853	\& ev_kqueue.c only when the kqueue backend is enabled (disabled by default)
1608	\& ev_port.c only when the solaris port backend is enabled (disabled by default)	1854	\& ev_port.c only when the solaris port backend is enabled (disabled by default)
1609	.Ve	1855	.Ve
1610	.PP	1856	.PP
1611	\&\fIev.c\fR includes the backend files directly when enabled, so you only need	1857	\&\fIev.c\fR includes the backend files directly when enabled, so you only need
1612	to compile a single file.	1858	to compile this single file.
1613	.PP	1859	.PP
1614	\fI\s-1LIBEVENT\s0 \s-1COMPATIBILITY\s0 \s-1API\s0\fR	1860	\fI\s-1LIBEVENT\s0 \s-1COMPATIBILITY\s0 \s-1API\s0\fR
1615	.IX Subsection "LIBEVENT COMPATIBILITY API"	1861	.IX Subsection "LIBEVENT COMPATIBILITY API"
1616	.PP	1862	.PP
1617	To include the libevent compatibility \s-1API\s0, also include:	1863	To include the libevent compatibility \s-1API\s0, also include:
…		…
1638	\fI\s-1AUTOCONF\s0 \s-1SUPPORT\s0\fR	1884	\fI\s-1AUTOCONF\s0 \s-1SUPPORT\s0\fR
1639	.IX Subsection "AUTOCONF SUPPORT"	1885	.IX Subsection "AUTOCONF SUPPORT"
1640	.PP	1886	.PP
1641	Instead of using \f(CW\(C`EV_STANDALONE=1\(C'\fR and providing your config in	1887	Instead of using \f(CW\(C`EV_STANDALONE=1\(C'\fR and providing your config in
1642	whatever way you want, you can also \f(CW\(C`m4_include([libev.m4])\(C'\fR in your	1888	whatever way you want, you can also \f(CW\(C`m4_include([libev.m4])\(C'\fR in your
1643	\&\fIconfigure.ac\fR and leave \f(CW\(C`EV_STANDALONE\(C'\fR off. \fIev.c\fR will then include	1889	\&\fIconfigure.ac\fR and leave \f(CW\(C`EV_STANDALONE\(C'\fR undefined. \fIev.c\fR will then
1644	\&\fIconfig.h\fR and configure itself accordingly.	1890	include \fIconfig.h\fR and configure itself accordingly.
1645	.PP	1891	.PP
1646	For this of course you need the m4 file:	1892	For this of course you need the m4 file:
1647	.PP	1893	.PP
1648	.Vb 1	1894	.Vb 1
1649	\& libev.m4	1895	\& libev.m4
…		…
1757	If undefined or defined to \f(CW1\fR, then all event-loop-specific functions	2003	If undefined or defined to \f(CW1\fR, then all event-loop-specific functions
1758	will have the \f(CW\(C`struct ev_loop \*(C'\fR as first argument, and you can create	2004	will have the \f(CW\(C`struct ev_loop \*(C'\fR as first argument, and you can create
1759	additional independent event loops. Otherwise there will be no support	2005	additional independent event loops. Otherwise there will be no support
1760	for multiple event loops and there is no first event loop pointer	2006	for multiple event loops and there is no first event loop pointer
1761	argument. Instead, all functions act on the single default loop.	2007	argument. Instead, all functions act on the single default loop.
1762	.IP "\s-1EV_PERIODICS\s0" 4	2008	.IP "\s-1EV_PERIODIC_ENABLE\s0" 4
1763	.IX Item "EV_PERIODICS"	2009	.IX Item "EV_PERIODIC_ENABLE"
1764	If undefined or defined to be \f(CW1\fR, then periodic timers are supported,	2010	If undefined or defined to be \f(CW1\fR, then periodic timers are supported. If
1765	otherwise not. This saves a few kb of code.	2011	defined to be \f(CW0\fR, then they are not. Disabling them saves a few kB of
		2012	code.
		2013	.IP "\s-1EV_EMBED_ENABLE\s0" 4
		2014	.IX Item "EV_EMBED_ENABLE"
		2015	If undefined or defined to be \f(CW1\fR, then embed watchers are supported. If
		2016	defined to be \f(CW0\fR, then they are not.
		2017	.IP "\s-1EV_STAT_ENABLE\s0" 4
		2018	.IX Item "EV_STAT_ENABLE"
		2019	If undefined or defined to be \f(CW1\fR, then stat watchers are supported. If
		2020	defined to be \f(CW0\fR, then they are not.
		2021	.IP "\s-1EV_MINIMAL\s0" 4
		2022	.IX Item "EV_MINIMAL"
		2023	If you need to shave off some kilobytes of code at the expense of some
		2024	speed, define this symbol to \f(CW1\fR. Currently only used for gcc to override
		2025	some inlining decisions, saves roughly 30% codesize of amd64.
1766	.IP "\s-1EV_COMMON\s0" 4	2026	.IP "\s-1EV_COMMON\s0" 4
1767	.IX Item "EV_COMMON"	2027	.IX Item "EV_COMMON"
1768	By default, all watchers have a \f(CW\(C`void data\*(C'\fR member. By redefining	2028	By default, all watchers have a \f(CW\(C`void data\*(C'\fR member. By redefining
1769	this macro to a something else you can include more and other types of	2029	this macro to a something else you can include more and other types of
1770	members. You have to define it each time you include one of the files,	2030	members. You have to define it each time you include one of the files,
…		…
1775	.Vb 3	2035	.Vb 3
1776	\& #define EV_COMMON \e	2036	\& #define EV_COMMON \e
1777	\& SV self; / contains this struct */ \e	2037	\& SV self; / contains this struct */ \e
1778	\& SV cb_sv, fh /* note no trailing ";" */	2038	\& SV cb_sv, fh /* note no trailing ";" */
1779	.Ve	2039	.Ve
1780	.IP "\s-1EV_CB_DECLARE\s0(type)" 4	2040	.IP "\s-1EV_CB_DECLARE\s0 (type)" 4
1781	.IX Item "EV_CB_DECLARE(type)"	2041	.IX Item "EV_CB_DECLARE (type)"
1782	.PD 0	2042	.PD 0
1783	.IP "\s-1EV_CB_INVOKE\s0(watcher,revents)" 4	2043	.IP "\s-1EV_CB_INVOKE\s0 (watcher, revents)" 4
1784	.IX Item "EV_CB_INVOKE(watcher,revents)"	2044	.IX Item "EV_CB_INVOKE (watcher, revents)"
1785	.IP "ev_set_cb(ev,cb)" 4	2045	.IP "ev_set_cb (ev, cb)" 4
1786	.IX Item "ev_set_cb(ev,cb)"	2046	.IX Item "ev_set_cb (ev, cb)"
1787	.PD	2047	.PD
1788	Can be used to change the callback member declaration in each watcher,	2048	Can be used to change the callback member declaration in each watcher,
1789	and the way callbacks are invoked and set. Must expand to a struct member	2049	and the way callbacks are invoked and set. Must expand to a struct member
1790	definition and a statement, respectively. See the \fIev.v\fR header file for	2050	definition and a statement, respectively. See the \fIev.v\fR header file for
1791	their default definitions. One possible use for overriding these is to	2051	their default definitions. One possible use for overriding these is to
1792	avoid the ev_loop pointer as first argument in all cases, or to use method	2052	avoid the \f(CW\(C`struct ev_loop \*(C'\fR as first argument in all cases, or to use
1793	calls instead of plain function calls in \*(C+.	2053	method calls instead of plain function calls in \*(C+.
1794	.Sh "\s-1EXAMPLES\s0"	2054	.Sh "\s-1EXAMPLES\s0"
1795	.IX Subsection "EXAMPLES"	2055	.IX Subsection "EXAMPLES"
1796	For a real-world example of a program the includes libev	2056	For a real-world example of a program the includes libev
1797	verbatim, you can have a look at the \s-1EV\s0 perl module	2057	verbatim, you can have a look at the \s-1EV\s0 perl module
1798	(<http://software.schmorp.de/pkg/EV.html>). It has the libev files in	2058	(<http://software.schmorp.de/pkg/EV.html>). It has the libev files in
…		…
1819	.Sp	2079	.Sp
1820	.Vb 2	2080	.Vb 2
1821	\& #include "ev_cpp.h"	2081	\& #include "ev_cpp.h"
1822	\& #include "ev.c"	2082	\& #include "ev.c"
1823	.Ve	2083	.Ve
		2084	.SH "COMPLEXITIES"
		2085	.IX Header "COMPLEXITIES"
		2086	In this section the complexities of (many of) the algorithms used inside
		2087	libev will be explained. For complexity discussions about backends see the
		2088	documentation for \f(CW\(C`ev_default_init\(C'\fR.
		2089	.RS 4
		2090	.IP "Starting and stopping timer/periodic watchers: O(log skipped_other_timers)" 4
		2091	.IX Item "Starting and stopping timer/periodic watchers: O(log skipped_other_timers)"
		2092	.PD 0
		2093	.IP "Changing timer/periodic watchers (by autorepeat, again): O(log skipped_other_timers)" 4
		2094	.IX Item "Changing timer/periodic watchers (by autorepeat, again): O(log skipped_other_timers)"
		2095	.IP "Starting io/check/prepare/idle/signal/child watchers: O(1)" 4
		2096	.IX Item "Starting io/check/prepare/idle/signal/child watchers: O(1)"
		2097	.IP "Stopping check/prepare/idle watchers: O(1)" 4
		2098	.IX Item "Stopping check/prepare/idle watchers: O(1)"
		2099	.IP "Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % 16))" 4
		2100	.IX Item "Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % 16))"
		2101	.IP "Finding the next timer per loop iteration: O(1)" 4
		2102	.IX Item "Finding the next timer per loop iteration: O(1)"
		2103	.IP "Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)" 4
		2104	.IX Item "Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)"
		2105	.IP "Activating one watcher: O(1)" 4
		2106	.IX Item "Activating one watcher: O(1)"
		2107	.RE
		2108	.RS 4
		2109	.PD
1824	.SH "AUTHOR"	2110	.SH "AUTHOR"
1825	.IX Header "AUTHOR"	2111	.IX Header "AUTHOR"
1826	Marc Lehmann <libev@schmorp.de>.	2112	Marc Lehmann <libev@schmorp.de>.

Diff Legend

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

Comparing libev/ev.3 (file contents): Revision 1.17 by root, Sat Nov 24 16:31:45 2007 UTC vs. Revision 1.22 by root, Tue Nov 27 08:11:52 2007 UTC

Diff Legend

Comparing libev/ev.3 (file contents):
Revision 1.17 by root, Sat Nov 24 16:31:45 2007 UTC vs.
Revision 1.22 by root, Tue Nov 27 08:11:52 2007 UTC