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

Comparing libev/ev.3 (file contents):
Revision 1.9 by root, Fri Nov 23 16:17:12 2007 UTC vs.
Revision 1.16 by root, Sat Nov 24 10:19: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-23" "perl v5.8.8" "User Contributed Perl Documentation"	132	.TH "<STANDARD INPUT>" 1 "2007-11-24" "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
…		…
231	recommended for this platform. This set is often smaller than the one	231	recommended for this platform. This set is often smaller than the one
232	returned by \f(CW\(C`ev_supported_backends\(C'\fR, as for example kqueue is broken on	232	returned by \f(CW\(C`ev_supported_backends\(C'\fR, as for example kqueue is broken on
233	most BSDs and will not be autodetected unless you explicitly request it	233	most BSDs and will not be autodetected unless you explicitly request it
234	(assuming you know what you are doing). This is the set of backends that	234	(assuming you know what you are doing). This is the set of backends that
235	libev will probe for if you specify no backends explicitly.	235	libev will probe for if you specify no backends explicitly.
		236	.IP "unsigned int ev_embeddable_backends ()" 4
		237	.IX Item "unsigned int ev_embeddable_backends ()"
		238	Returns the set of backends that are embeddable in other event loops. This
		239	is the theoretical, all\-platform, value. To find which backends
		240	might be supported on the current system, you would need to look at
		241	\&\f(CW\(C`ev_embeddable_backends () & ev_supported_backends ()\(C'\fR, likewise for
		242	recommended ones.
		243	.Sp
		244	See the description of \f(CW\(C`ev_embed\(C'\fR watchers for more info.
236	.IP "ev_set_allocator (void (cb)(void *ptr, long size))" 4	245	.IP "ev_set_allocator (void (cb)(void *ptr, long size))" 4
237	.IX Item "ev_set_allocator (void (cb)(void *ptr, long size))"	246	.IX Item "ev_set_allocator (void (cb)(void *ptr, long size))"
238	Sets the allocation function to use (the prototype is similar to the	247	Sets the allocation function to use (the prototype is similar to the
239	realloc C function, the semantics are identical). It is used to allocate	248	realloc C function, the semantics are identical). It is used to allocate
240	and free memory (no surprises here). If it returns zero when memory	249	and free memory (no surprises here). If it returns zero when memory
…		…
449	\& fatal ("no epoll found here, maybe it hides under your chair");	458	\& fatal ("no epoll found here, maybe it hides under your chair");
450	.Ve	459	.Ve
451	.IP "ev_default_destroy ()" 4	460	.IP "ev_default_destroy ()" 4
452	.IX Item "ev_default_destroy ()"	461	.IX Item "ev_default_destroy ()"
453	Destroys the default loop again (frees all memory and kernel state	462	Destroys the default loop again (frees all memory and kernel state
454	etc.). This stops all registered event watchers (by not touching them in	463	etc.). None of the active event watchers will be stopped in the normal
455	any way whatsoever, although you cannot rely on this :).	464	sense, so e.g. \f(CW\(C`ev_is_active\(C'\fR might still return true. It is your
		465	responsibility to either stop all watchers cleanly yoursef \fIbefore\fR
		466	calling this function, or cope with the fact afterwards (which is usually
		467	the easiest thing, youc na just ignore the watchers and/or \f(CW\(C`free ()\(C'\fR them
		468	for example).
456	.IP "ev_loop_destroy (loop)" 4	469	.IP "ev_loop_destroy (loop)" 4
457	.IX Item "ev_loop_destroy (loop)"	470	.IX Item "ev_loop_destroy (loop)"
458	Like \f(CW\(C`ev_default_destroy\(C'\fR, but destroys an event loop created by an	471	Like \f(CW\(C`ev_default_destroy\(C'\fR, but destroys an event loop created by an
459	earlier call to \f(CW\(C`ev_loop_new\(C'\fR.	472	earlier call to \f(CW\(C`ev_loop_new\(C'\fR.
460	.IP "ev_default_fork ()" 4	473	.IP "ev_default_fork ()" 4
…		…
636	)\(C'\fR), and you can stop watching for events at any time by calling the	649	)\(C'\fR), and you can stop watching for events at any time by calling the
637	corresponding stop function (\f(CW\(C`ev_<type>_stop (loop, watcher )\*(C'\fR.	650	corresponding stop function (\f(CW\(C`ev_<type>_stop (loop, watcher )\*(C'\fR.
638	.PP	651	.PP
639	As long as your watcher is active (has been started but not stopped) you	652	As long as your watcher is active (has been started but not stopped) you
640	must not touch the values stored in it. Most specifically you must never	653	must not touch the values stored in it. Most specifically you must never
641	reinitialise it or call its set macro.	654	reinitialise it or call its \f(CW\(C`set\(C'\fR macro.
642	.PP
643	You can check whether an event is active by calling the \f(CW\*(C`ev_is_active
644	(watcher )\(C'\fR macro. To see whether an event is outstanding (but the
645	callback for it has not been called yet) you can use the \f(CW\*(C`ev_is_pending
646	(watcher )\(C'\fR macro.
647	.PP	655	.PP
648	Each and every callback receives the event loop pointer as first, the	656	Each and every callback receives the event loop pointer as first, the
649	registered watcher structure as second, and a bitset of received events as	657	registered watcher structure as second, and a bitset of received events as
650	third argument.	658	third argument.
651	.PP	659	.PP
…		…
709	Libev will usually signal a few \(L"dummy\(R" events together with an error,	717	Libev will usually signal a few \(L"dummy\(R" events together with an error,
710	for example it might indicate that a fd is readable or writable, and if	718	for example it might indicate that a fd is readable or writable, and if
711	your callbacks is well-written it can just attempt the operation and cope	719	your callbacks is well-written it can just attempt the operation and cope
712	with the error from \fIread()\fR or \fIwrite()\fR. This will not work in multithreaded	720	with the error from \fIread()\fR or \fIwrite()\fR. This will not work in multithreaded
713	programs, though, so beware.	721	programs, though, so beware.
		722	.Sh "\s-1SUMMARY\s0 \s-1OF\s0 \s-1GENERIC\s0 \s-1WATCHER\s0 \s-1FUNCTIONS\s0"
		723	.IX Subsection "SUMMARY OF GENERIC WATCHER FUNCTIONS"
		724	In the following description, \f(CW\(C`TYPE\(C'\fR stands for the watcher type,
		725	e.g. \f(CW\(C`timer\(C'\fR for \f(CW\(C`ev_timer\(C'\fR watchers and \f(CW\(C`io\(C'\fR for \f(CW\(C`ev_io\(C'\fR watchers.
		726	.ie n .IP """ev_init"" (ev_TYPE *watcher, callback)" 4
		727	.el .IP "\f(CWev_init\fR (ev_TYPE *watcher, callback)" 4
		728	.IX Item "ev_init (ev_TYPE *watcher, callback)"
		729	This macro initialises the generic portion of a watcher. The contents
		730	of the watcher object can be arbitrary (so \f(CW\(C`malloc\(C'\fR will do). Only
		731	the generic parts of the watcher are initialised, you \fIneed\fR to call
		732	the type-specific \f(CW\(C`ev_TYPE_set\(C'\fR macro afterwards to initialise the
		733	type-specific parts. For each type there is also a \f(CW\(C`ev_TYPE_init\(C'\fR macro
		734	which rolls both calls into one.
		735	.Sp
		736	You can reinitialise a watcher at any time as long as it has been stopped
		737	(or never started) and there are no pending events outstanding.
		738	.Sp
		739	The callbakc is always of type \f(CW\(C`void ()(ev_loop loop, ev_TYPE watcher,
		740	int revents)\*(C'\fR.
		741	.ie n .IP """ev_TYPE_set"" (ev_TYPE *, [args])" 4
		742	.el .IP "\f(CWev_TYPE_set\fR (ev_TYPE *, [args])" 4
		743	.IX Item "ev_TYPE_set (ev_TYPE *, [args])"
		744	This macro initialises the type-specific parts of a watcher. You need to
		745	call \f(CW\(C`ev_init\(C'\fR at least once before you call this macro, but you can
		746	call \f(CW\(C`ev_TYPE_set\(C'\fR any number of times. You must not, however, call this
		747	macro on a watcher that is active (it can be pending, however, which is a
		748	difference to the \f(CW\(C`ev_init\(C'\fR macro).
		749	.Sp
		750	Although some watcher types do not have type-specific arguments
		751	(e.g. \f(CW\(C`ev_prepare\(C'\fR) you still need to call its \f(CW\(C`set\(C'\fR macro.
		752	.ie n .IP """ev_TYPE_init"" (ev_TYPE *watcher, callback, [args])" 4
		753	.el .IP "\f(CWev_TYPE_init\fR (ev_TYPE *watcher, callback, [args])" 4
		754	.IX Item "ev_TYPE_init (ev_TYPE *watcher, callback, [args])"
		755	This convinience macro rolls both \f(CW\(C`ev_init\(C'\fR and \f(CW\(C`ev_TYPE_set\(C'\fR macro
		756	calls into a single call. This is the most convinient method to initialise
		757	a watcher. The same limitations apply, of course.
		758	.ie n .IP """ev_TYPE_start"" (loop , ev_TYPE watcher)" 4
		759	.el .IP "\f(CWev_TYPE_start\fR (loop , ev_TYPE watcher)" 4
		760	.IX Item "ev_TYPE_start (loop , ev_TYPE watcher)"
		761	Starts (activates) the given watcher. Only active watchers will receive
		762	events. If the watcher is already active nothing will happen.
		763	.ie n .IP """ev_TYPE_stop"" (loop , ev_TYPE watcher)" 4
		764	.el .IP "\f(CWev_TYPE_stop\fR (loop , ev_TYPE watcher)" 4
		765	.IX Item "ev_TYPE_stop (loop , ev_TYPE watcher)"
		766	Stops the given watcher again (if active) and clears the pending
		767	status. It is possible that stopped watchers are pending (for example,
		768	non-repeating timers are being stopped when they become pending), but
		769	\&\f(CW\(C`ev_TYPE_stop\(C'\fR ensures that the watcher is neither active nor pending. If
		770	you want to free or reuse the memory used by the watcher it is therefore a
		771	good idea to always call its \f(CW\(C`ev_TYPE_stop\(C'\fR function.
		772	.IP "bool ev_is_active (ev_TYPE *watcher)" 4
		773	.IX Item "bool ev_is_active (ev_TYPE *watcher)"
		774	Returns a true value iff the watcher is active (i.e. it has been started
		775	and not yet been stopped). As long as a watcher is active you must not modify
		776	it.
		777	.IP "bool ev_is_pending (ev_TYPE *watcher)" 4
		778	.IX Item "bool ev_is_pending (ev_TYPE *watcher)"
		779	Returns a true value iff the watcher is pending, (i.e. it has outstanding
		780	events but its callback has not yet been invoked). As long as a watcher
		781	is pending (but not active) you must not call an init function on it (but
		782	\&\f(CW\(C`ev_TYPE_set\(C'\fR is safe) and you must make sure the watcher is available to
		783	libev (e.g. you cnanot \f(CW\(C`free ()\(C'\fR it).
		784	.IP "callback = ev_cb (ev_TYPE *watcher)" 4
		785	.IX Item "callback = ev_cb (ev_TYPE *watcher)"
		786	Returns the callback currently set on the watcher.
		787	.IP "ev_cb_set (ev_TYPE *watcher, callback)" 4
		788	.IX Item "ev_cb_set (ev_TYPE *watcher, callback)"
		789	Change the callback. You can change the callback at virtually any time
		790	(modulo threads).
714	.Sh "\s-1ASSOCIATING\s0 \s-1CUSTOM\s0 \s-1DATA\s0 \s-1WITH\s0 A \s-1WATCHER\s0"	791	.Sh "\s-1ASSOCIATING\s0 \s-1CUSTOM\s0 \s-1DATA\s0 \s-1WITH\s0 A \s-1WATCHER\s0"
715	.IX Subsection "ASSOCIATING CUSTOM DATA WITH A WATCHER"	792	.IX Subsection "ASSOCIATING CUSTOM DATA WITH A WATCHER"
716	Each watcher has, by default, a member \f(CW\(C`void data\*(C'\fR that you can change	793	Each watcher has, by default, a member \f(CW\(C`void data\*(C'\fR that you can change
717	and read at any time, libev will completely ignore it. This can be used	794	and read at any time, libev will completely ignore it. This can be used
718	to associate arbitrary data with your watcher. If you need more data and	795	to associate arbitrary data with your watcher. If you need more data and
…		…
918	(and unfortunately a bit complex).	995	(and unfortunately a bit complex).
919	.PP	996	.PP
920	Unlike \f(CW\(C`ev_timer\(C'\fR's, they are not based on real time (or relative time)	997	Unlike \f(CW\(C`ev_timer\(C'\fR's, they are not based on real time (or relative time)
921	but on wallclock time (absolute time). You can tell a periodic watcher	998	but on wallclock time (absolute time). You can tell a periodic watcher
922	to trigger \(L"at\(R" some specific point in time. For example, if you tell a	999	to trigger \(L"at\(R" some specific point in time. For example, if you tell a
923	periodic watcher to trigger in 10 seconds (by specifiying e.g. c<ev_now ()	1000	periodic watcher to trigger in 10 seconds (by specifiying e.g. \f(CW\*(C`ev_now ()
924	+ 10.>) and then reset your system clock to the last year, then it will	1001	+ 10.\*(C'\fR) and then reset your system clock to the last year, then it will
925	take a year to trigger the event (unlike an \f(CW\(C`ev_timer\(C'\fR, which would trigger	1002	take a year to trigger the event (unlike an \f(CW\(C`ev_timer\(C'\fR, which would trigger
926	roughly 10 seconds later and of course not if you reset your system time	1003	roughly 10 seconds later and of course not if you reset your system time
927	again).	1004	again).
928	.PP	1005	.PP
929	They can also be used to implement vastly more complex timers, such as	1006	They can also be used to implement vastly more complex timers, such as
…		…
1159	.IX Subsection "ev_prepare and ev_check - customise your event loop"	1236	.IX Subsection "ev_prepare and ev_check - customise your event loop"
1160	Prepare and check watchers are usually (but not always) used in tandem:	1237	Prepare and check watchers are usually (but not always) used in tandem:
1161	prepare watchers get invoked before the process blocks and check watchers	1238	prepare watchers get invoked before the process blocks and check watchers
1162	afterwards.	1239	afterwards.
1163	.PP	1240	.PP
1164	Their main purpose is to integrate other event mechanisms into libev. This	1241	Their main purpose is to integrate other event mechanisms into libev and
1165	could be used, for example, to track variable changes, implement your own	1242	their use is somewhat advanced. This could be used, for example, to track
1166	watchers, integrate net-snmp or a coroutine library and lots more.	1243	variable changes, implement your own watchers, integrate net-snmp or a
		1244	coroutine library and lots more.
1167	.PP	1245	.PP
1168	This is done by examining in each prepare call which file descriptors need	1246	This is done by examining in each prepare call which file descriptors need
1169	to be watched by the other library, registering \f(CW\(C`ev_io\(C'\fR watchers for	1247	to be watched by the other library, registering \f(CW\(C`ev_io\(C'\fR watchers for
1170	them and starting an \f(CW\(C`ev_timer\(C'\fR watcher for any timeouts (many libraries	1248	them and starting an \f(CW\(C`ev_timer\(C'\fR watcher for any timeouts (many libraries
1171	provide just this functionality). Then, in the check watcher you check for	1249	provide just this functionality). Then, in the check watcher you check for
…		…
1191	Initialises and configures the prepare or check watcher \- they have no	1269	Initialises and configures the prepare or check watcher \- they have no
1192	parameters of any kind. There are \f(CW\(C`ev_prepare_set\(C'\fR and \f(CW\(C`ev_check_set\(C'\fR	1270	parameters of any kind. There are \f(CW\(C`ev_prepare_set\(C'\fR and \f(CW\(C`ev_check_set\(C'\fR
1193	macros, but using them is utterly, utterly and completely pointless.	1271	macros, but using them is utterly, utterly and completely pointless.
1194	.PP	1272	.PP
1195	Example: TODO.	1273	Example: TODO.
		1274	.ie n .Sh """ev_embed"" \- when one backend isn't enough"
		1275	.el .Sh "\f(CWev_embed\fP \- when one backend isn't enough"
		1276	.IX Subsection "ev_embed - when one backend isn't enough"
		1277	This is a rather advanced watcher type that lets you embed one event loop
		1278	into another (currently only \f(CW\(C`ev_io\(C'\fR events are supported in the embedded
		1279	loop, other types of watchers might be handled in a delayed or incorrect
		1280	fashion and must not be used).
		1281	.PP
		1282	There are primarily two reasons you would want that: work around bugs and
		1283	prioritise I/O.
		1284	.PP
		1285	As an example for a bug workaround, the kqueue backend might only support
		1286	sockets on some platform, so it is unusable as generic backend, but you
		1287	still want to make use of it because you have many sockets and it scales
		1288	so nicely. In this case, you would create a kqueue-based loop and embed it
		1289	into your default loop (which might use e.g. poll). Overall operation will
		1290	be a bit slower because first libev has to poll and then call kevent, but
		1291	at least you can use both at what they are best.
		1292	.PP
		1293	As for prioritising I/O: rarely you have the case where some fds have
		1294	to be watched and handled very quickly (with low latency), and even
		1295	priorities and idle watchers might have too much overhead. In this case
		1296	you would put all the high priority stuff in one loop and all the rest in
		1297	a second one, and embed the second one in the first.
		1298	.PP
		1299	As long as the watcher is active, the callback will be invoked every time
		1300	there might be events pending in the embedded loop. The callback must then
		1301	call \f(CW\(C`ev_embed_sweep (mainloop, watcher)\(C'\fR to make a single sweep and invoke
		1302	their callbacks (you could also start an idle watcher to give the embedded
		1303	loop strictly lower priority for example). You can also set the callback
		1304	to \f(CW0\fR, in which case the embed watcher will automatically execute the
		1305	embedded loop sweep.
		1306	.PP
		1307	As long as the watcher is started it will automatically handle events. The
		1308	callback will be invoked whenever some events have been handled. You can
		1309	set the callback to \f(CW0\fR to avoid having to specify one if you are not
		1310	interested in that.
		1311	.PP
		1312	Also, there have not currently been made special provisions for forking:
		1313	when you fork, you not only have to call \f(CW\(C`ev_loop_fork\(C'\fR on both loops,
		1314	but you will also have to stop and restart any \f(CW\(C`ev_embed\(C'\fR watchers
		1315	yourself.
		1316	.PP
		1317	Unfortunately, not all backends are embeddable, only the ones returned by
		1318	\&\f(CW\(C`ev_embeddable_backends\(C'\fR are, which, unfortunately, does not include any
		1319	portable one.
		1320	.PP
		1321	So when you want to use this feature you will always have to be prepared
		1322	that you cannot get an embeddable loop. The recommended way to get around
		1323	this is to have a separate variables for your embeddable loop, try to
		1324	create it, and if that fails, use the normal loop for everything:
		1325	.PP
		1326	.Vb 3
		1327	\& struct ev_loop *loop_hi = ev_default_init (0);
		1328	\& struct ev_loop *loop_lo = 0;
		1329	\& struct ev_embed embed;
		1330	.Ve
		1331	.PP
		1332	.Vb 5
		1333	\& // see if there is a chance of getting one that works
		1334	\& // (remember that a flags value of 0 means autodetection)
		1335	\& loop_lo = ev_embeddable_backends () & ev_recommended_backends ()
		1336	\& ? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ())
		1337	\& : 0;
		1338	.Ve
		1339	.PP
		1340	.Vb 8
		1341	\& // if we got one, then embed it, otherwise default to loop_hi
		1342	\& if (loop_lo)
		1343	\& {
		1344	\& ev_embed_init (&embed, 0, loop_lo);
		1345	\& ev_embed_start (loop_hi, &embed);
		1346	\& }
		1347	\& else
		1348	\& loop_lo = loop_hi;
		1349	.Ve
		1350	.IP "ev_embed_init (ev_embed , callback, struct ev_loop embedded_loop)" 4
		1351	.IX Item "ev_embed_init (ev_embed , callback, struct ev_loop embedded_loop)"
		1352	.PD 0
		1353	.IP "ev_embed_set (ev_embed , callback, struct ev_loop embedded_loop)" 4
		1354	.IX Item "ev_embed_set (ev_embed , callback, struct ev_loop embedded_loop)"
		1355	.PD
		1356	Configures the watcher to embed the given loop, which must be
		1357	embeddable. If the callback is \f(CW0\fR, then \f(CW\(C`ev_embed_sweep\(C'\fR will be
		1358	invoked automatically, otherwise it is the responsibility of the callback
		1359	to invoke it (it will continue to be called until the sweep has been done,
		1360	if you do not want thta, you need to temporarily stop the embed watcher).
		1361	.IP "ev_embed_sweep (loop, ev_embed *)" 4
		1362	.IX Item "ev_embed_sweep (loop, ev_embed *)"
		1363	Make a single, non-blocking sweep over the embedded loop. This works
		1364	similarly to \f(CW\(C`ev_loop (embedded_loop, EVLOOP_NONBLOCK)\(C'\fR, but in the most
		1365	apropriate way for embedded loops.
1196	.SH "OTHER FUNCTIONS"	1366	.SH "OTHER FUNCTIONS"
1197	.IX Header "OTHER FUNCTIONS"	1367	.IX Header "OTHER FUNCTIONS"
1198	There are some other functions of possible interest. Described. Here. Now.	1368	There are some other functions of possible interest. Described. Here. Now.
1199	.IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 4	1369	.IP "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)" 4
1200	.IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)"	1370	.IX Item "ev_once (loop, int fd, int events, ev_tstamp timeout, callback)"
…		…
1229	.Ve	1399	.Ve
1230	.Sp	1400	.Sp
1231	.Vb 1	1401	.Vb 1
1232	\& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);	1402	\& ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
1233	.Ve	1403	.Ve
1234	.IP "ev_feed_event (loop, watcher, int events)" 4	1404	.IP "ev_feed_event (ev_loop , watcher , int revents)" 4
1235	.IX Item "ev_feed_event (loop, watcher, int events)"	1405	.IX Item "ev_feed_event (ev_loop , watcher , int revents)"
1236	Feeds the given event set into the event loop, as if the specified event	1406	Feeds the given event set into the event loop, as if the specified event
1237	had happened for the specified watcher (which must be a pointer to an	1407	had happened for the specified watcher (which must be a pointer to an
1238	initialised but not necessarily started event watcher).	1408	initialised but not necessarily started event watcher).
1239	.IP "ev_feed_fd_event (loop, int fd, int revents)" 4	1409	.IP "ev_feed_fd_event (ev_loop *, int fd, int revents)" 4
1240	.IX Item "ev_feed_fd_event (loop, int fd, int revents)"	1410	.IX Item "ev_feed_fd_event (ev_loop *, int fd, int revents)"
1241	Feed an event on the given fd, as if a file descriptor backend detected	1411	Feed an event on the given fd, as if a file descriptor backend detected
1242	the given events it.	1412	the given events it.
1243	.IP "ev_feed_signal_event (loop, int signum)" 4	1413	.IP "ev_feed_signal_event (ev_loop *loop, int signum)" 4
1244	.IX Item "ev_feed_signal_event (loop, int signum)"	1414	.IX Item "ev_feed_signal_event (ev_loop *loop, int signum)"
1245	Feed an event as if the given signal occured (loop must be the default loop!).	1415	Feed an event as if the given signal occured (\f(CW\(C`loop\(C'\fR must be the default
		1416	loop!).
1246	.SH "LIBEVENT EMULATION"	1417	.SH "LIBEVENT EMULATION"
1247	.IX Header "LIBEVENT EMULATION"	1418	.IX Header "LIBEVENT EMULATION"
1248	Libev offers a compatibility emulation layer for libevent. It cannot	1419	Libev offers a compatibility emulation layer for libevent. It cannot
1249	emulate the internals of libevent, so here are some usage hints:	1420	emulate the internals of libevent, so here are some usage hints:
1250	.IP "* Use it by including <event.h>, as usual." 4	1421	.IP "* Use it by including <event.h>, as usual." 4
…		…
1261	.IP "* The libev emulation is \fInot\fR \s-1ABI\s0 compatible to libevent, you need to use the libev header file and library." 4	1432	.IP "* The libev emulation is \fInot\fR \s-1ABI\s0 compatible to libevent, you need to use the libev header file and library." 4
1262	.IX Item "The libev emulation is not ABI compatible to libevent, you need to use the libev header file and library."	1433	.IX Item "The libev emulation is not ABI compatible to libevent, you need to use the libev header file and library."
1263	.PD	1434	.PD
1264	.SH "\*(C+ SUPPORT"	1435	.SH "\*(C+ SUPPORT"
1265	.IX Header " SUPPORT"	1436	.IX Header " SUPPORT"
1266	\&\s-1TBD\s0.	1437	Libev comes with some simplistic wrapper classes for \*(C+ that mainly allow
		1438	you to use some convinience methods to start/stop watchers and also change
		1439	the callback model to a model using method callbacks on objects.
		1440	.PP
		1441	To use it,
		1442	.PP
		1443	.Vb 1
		1444	\& #include <ev++.h>
		1445	.Ve
		1446	.PP
		1447	(it is not installed by default). This automatically includes \fIev.h\fR
		1448	and puts all of its definitions (many of them macros) into the global
		1449	namespace. All \(C+ specific things are put into the \f(CW\(C`ev\*(C'\fR namespace.
		1450	.PP
		1451	It should support all the same embedding options as \fIev.h\fR, most notably
		1452	\&\f(CW\(C`EV_MULTIPLICITY\(C'\fR.
		1453	.PP
		1454	Here is a list of things available in the \f(CW\(C`ev\(C'\fR namespace:
		1455	.ie n .IP """ev::READ""\fR, \f(CW""ev::WRITE"" etc." 4
		1456	.el .IP "\f(CWev::READ\fR, \f(CWev::WRITE\fR etc." 4
		1457	.IX Item "ev::READ, ev::WRITE etc."
		1458	These are just enum values with the same values as the \f(CW\(C`EV_READ\(C'\fR etc.
		1459	macros from \fIev.h\fR.
		1460	.ie n .IP """ev::tstamp""\fR, \f(CW""ev::now""" 4
		1461	.el .IP "\f(CWev::tstamp\fR, \f(CWev::now\fR" 4
		1462	.IX Item "ev::tstamp, ev::now"
		1463	Aliases to the same types/functions as with the \f(CW\(C`ev_\(C'\fR prefix.
		1464	.ie n .IP """ev::io""\fR, \f(CW""ev::timer""\fR, \f(CW""ev::periodic""\fR, \f(CW""ev::idle""\fR, \f(CW""ev::sig"" etc." 4
		1465	.el .IP "\f(CWev::io\fR, \f(CWev::timer\fR, \f(CWev::periodic\fR, \f(CWev::idle\fR, \f(CWev::sig\fR etc." 4
		1466	.IX Item "ev::io, ev::timer, ev::periodic, ev::idle, ev::sig etc."
		1467	For each \f(CW\(C`ev_TYPE\(C'\fR watcher in \fIev.h\fR there is a corresponding class of
		1468	the same name in the \f(CW\(C`ev\(C'\fR namespace, with the exception of \f(CW\(C`ev_signal\(C'\fR
		1469	which is called \f(CW\(C`ev::sig\(C'\fR to avoid clashes with the \f(CW\(C`signal\(C'\fR macro
		1470	defines by many implementations.
		1471	.Sp
		1472	All of those classes have these methods:
		1473	.RS 4
		1474	.IP "ev::TYPE::TYPE (object , object::method )" 4
		1475	.IX Item "ev::TYPE::TYPE (object , object::method )"
		1476	.PD 0
		1477	.IP "ev::TYPE::TYPE (object , object::method , struct ev_loop *)" 4
		1478	.IX Item "ev::TYPE::TYPE (object , object::method , struct ev_loop *)"
		1479	.IP "ev::TYPE::~TYPE" 4
		1480	.IX Item "ev::TYPE::~TYPE"
		1481	.PD
		1482	The constructor takes a pointer to an object and a method pointer to
		1483	the event handler callback to call in this class. The constructor calls
		1484	\&\f(CW\(C`ev_init\(C'\fR for you, which means you have to call the \f(CW\(C`set\(C'\fR method
		1485	before starting it. If you do not specify a loop then the constructor
		1486	automatically associates the default loop with this watcher.
		1487	.Sp
		1488	The destructor automatically stops the watcher if it is active.
		1489	.IP "w\->set (struct ev_loop *)" 4
		1490	.IX Item "w->set (struct ev_loop *)"
		1491	Associates a different \f(CW\(C`struct ev_loop\(C'\fR with this watcher. You can only
		1492	do this when the watcher is inactive (and not pending either).
		1493	.IP "w\->set ([args])" 4
		1494	.IX Item "w->set ([args])"
		1495	Basically the same as \f(CW\(C`ev_TYPE_set\(C'\fR, with the same args. Must be
		1496	called at least once. Unlike the C counterpart, an active watcher gets
		1497	automatically stopped and restarted.
		1498	.IP "w\->start ()" 4
		1499	.IX Item "w->start ()"
		1500	Starts the watcher. Note that there is no \f(CW\(C`loop\(C'\fR argument as the
		1501	constructor already takes the loop.
		1502	.IP "w\->stop ()" 4
		1503	.IX Item "w->stop ()"
		1504	Stops the watcher if it is active. Again, no \f(CW\(C`loop\(C'\fR argument.
		1505	.ie n .IP "w\->again () ""ev::timer""\fR, \f(CW""ev::periodic"" only" 4
		1506	.el .IP "w\->again () \f(CWev::timer\fR, \f(CWev::periodic\fR only" 4
		1507	.IX Item "w->again () ev::timer, ev::periodic only"
		1508	For \f(CW\(C`ev::timer\(C'\fR and \f(CW\(C`ev::periodic\(C'\fR, this invokes the corresponding
		1509	\&\f(CW\(C`ev_TYPE_again\(C'\fR function.
		1510	.ie n .IP "w\->sweep () ""ev::embed"" only" 4
		1511	.el .IP "w\->sweep () \f(CWev::embed\fR only" 4
		1512	.IX Item "w->sweep () ev::embed only"
		1513	Invokes \f(CW\(C`ev_embed_sweep\(C'\fR.
		1514	.RE
		1515	.RS 4
		1516	.RE
		1517	.PP
		1518	Example: Define a class with an \s-1IO\s0 and idle watcher, start one of them in
		1519	the constructor.
		1520	.PP
		1521	.Vb 4
		1522	\& class myclass
		1523	\& {
		1524	\& ev_io io; void io_cb (ev::io &w, int revents);
		1525	\& ev_idle idle void idle_cb (ev::idle &w, int revents);
		1526	.Ve
		1527	.PP
		1528	.Vb 2
		1529	\& myclass ();
		1530	\& }
		1531	.Ve
		1532	.PP
		1533	.Vb 6
		1534	\& myclass::myclass (int fd)
		1535	\& : io (this, &myclass::io_cb),
		1536	\& idle (this, &myclass::idle_cb)
		1537	\& {
		1538	\& io.start (fd, ev::READ);
		1539	\& }
		1540	.Ve
		1541	.SH "EMBEDDING"
		1542	.IX Header "EMBEDDING"
		1543	Libev can (and often is) directly embedded into host
		1544	applications. Examples of applications that embed it include the Deliantra
		1545	Game Server, the \s-1EV\s0 perl module, the \s-1GNU\s0 Virtual Private Ethernet (gvpe)
		1546	and rxvt\-unicode.
		1547	.PP
		1548	The goal is to enable you to just copy the neecssary files into your
		1549	source directory without having to change even a single line in them, so
		1550	you can easily upgrade by simply copying (or having a checked-out copy of
		1551	libev somewhere in your source tree).
		1552	.Sh "\s-1FILESETS\s0"
		1553	.IX Subsection "FILESETS"
		1554	Depending on what features you need you need to include one or more sets of files
		1555	in your app.
		1556	.PP
		1557	\fI\s-1CORE\s0 \s-1EVENT\s0 \s-1LOOP\s0\fR
		1558	.IX Subsection "CORE EVENT LOOP"
		1559	.PP
		1560	To include only the libev core (all the \f(CW\(C`ev_\*(C'\fR functions), with manual
		1561	configuration (no autoconf):
		1562	.PP
		1563	.Vb 2
		1564	\& #define EV_STANDALONE 1
		1565	\& #include "ev.c"
		1566	.Ve
		1567	.PP
		1568	This will automatically include \fIev.h\fR, too, and should be done in a
		1569	single C source file only to provide the function implementations. To use
		1570	it, do the same for \fIev.h\fR in all files wishing to use this \s-1API\s0 (best
		1571	done by writing a wrapper around \fIev.h\fR that you can include instead and
		1572	where you can put other configuration options):
		1573	.PP
		1574	.Vb 2
		1575	\& #define EV_STANDALONE 1
		1576	\& #include "ev.h"
		1577	.Ve
		1578	.PP
		1579	Both header files and implementation files can be compiled with a \*(C+
		1580	compiler (at least, thats a stated goal, and breakage will be treated
		1581	as a bug).
		1582	.PP
		1583	You need the following files in your source tree, or in a directory
		1584	in your include path (e.g. in libev/ when using \-Ilibev):
		1585	.PP
		1586	.Vb 4
		1587	\& ev.h
		1588	\& ev.c
		1589	\& ev_vars.h
		1590	\& ev_wrap.h
		1591	.Ve
		1592	.PP
		1593	.Vb 1
		1594	\& ev_win32.c required on win32 platforms only
		1595	.Ve
		1596	.PP
		1597	.Vb 5
		1598	\& ev_select.c only when select backend is enabled (which is is by default)
		1599	\& ev_poll.c only when poll backend is enabled (disabled by default)
		1600	\& ev_epoll.c only when the epoll backend is enabled (disabled by default)
		1601	\& ev_kqueue.c only when the kqueue backend is enabled (disabled by default)
		1602	\& ev_port.c only when the solaris port backend is enabled (disabled by default)
		1603	.Ve
		1604	.PP
		1605	\&\fIev.c\fR includes the backend files directly when enabled, so you only need
		1606	to compile a single file.
		1607	.PP
		1608	\fI\s-1LIBEVENT\s0 \s-1COMPATIBILITY\s0 \s-1API\s0\fR
		1609	.IX Subsection "LIBEVENT COMPATIBILITY API"
		1610	.PP
		1611	To include the libevent compatibility \s-1API\s0, also include:
		1612	.PP
		1613	.Vb 1
		1614	\& #include "event.c"
		1615	.Ve
		1616	.PP
		1617	in the file including \fIev.c\fR, and:
		1618	.PP
		1619	.Vb 1
		1620	\& #include "event.h"
		1621	.Ve
		1622	.PP
		1623	in the files that want to use the libevent \s-1API\s0. This also includes \fIev.h\fR.
		1624	.PP
		1625	You need the following additional files for this:
		1626	.PP
		1627	.Vb 2
		1628	\& event.h
		1629	\& event.c
		1630	.Ve
		1631	.PP
		1632	\fI\s-1AUTOCONF\s0 \s-1SUPPORT\s0\fR
		1633	.IX Subsection "AUTOCONF SUPPORT"
		1634	.PP
		1635	Instead of using \f(CW\(C`EV_STANDALONE=1\(C'\fR and providing your config in
		1636	whatever way you want, you can also \f(CW\(C`m4_include([libev.m4])\(C'\fR in your
		1637	\&\fIconfigure.ac\fR and leave \f(CW\(C`EV_STANDALONE\(C'\fR off. \fIev.c\fR will then include
		1638	\&\fIconfig.h\fR and configure itself accordingly.
		1639	.PP
		1640	For this of course you need the m4 file:
		1641	.PP
		1642	.Vb 1
		1643	\& libev.m4
		1644	.Ve
		1645	.Sh "\s-1PREPROCESSOR\s0 \s-1SYMBOLS/MACROS\s0"
		1646	.IX Subsection "PREPROCESSOR SYMBOLS/MACROS"
		1647	Libev can be configured via a variety of preprocessor symbols you have to define
		1648	before including any of its files. The default is not to build for multiplicity
		1649	and only include the select backend.
		1650	.IP "\s-1EV_STANDALONE\s0" 4
		1651	.IX Item "EV_STANDALONE"
		1652	Must always be \f(CW1\fR if you do not use autoconf configuration, which
		1653	keeps libev from including \fIconfig.h\fR, and it also defines dummy
		1654	implementations for some libevent functions (such as logging, which is not
		1655	supported). It will also not define any of the structs usually found in
		1656	\&\fIevent.h\fR that are not directly supported by the libev core alone.
		1657	.IP "\s-1EV_USE_MONOTONIC\s0" 4
		1658	.IX Item "EV_USE_MONOTONIC"
		1659	If defined to be \f(CW1\fR, libev will try to detect the availability of the
		1660	monotonic clock option at both compiletime and runtime. Otherwise no use
		1661	of the monotonic clock option will be attempted. If you enable this, you
		1662	usually have to link against librt or something similar. Enabling it when
		1663	the functionality isn't available is safe, though, althoguh you have
		1664	to make sure you link against any libraries where the \f(CW\(C`clock_gettime\(C'\fR
		1665	function is hiding in (often \fI\-lrt\fR).
		1666	.IP "\s-1EV_USE_REALTIME\s0" 4
		1667	.IX Item "EV_USE_REALTIME"
		1668	If defined to be \f(CW1\fR, libev will try to detect the availability of the
		1669	realtime clock option at compiletime (and assume its availability at
		1670	runtime if successful). Otherwise no use of the realtime clock option will
		1671	be attempted. This effectively replaces \f(CW\(C`gettimeofday\(C'\fR by \f(CW\*(C`clock_get
		1672	(CLOCK_REALTIME, ...)\*(C'\fR and will not normally affect correctness. See tzhe note about libraries
		1673	in the description of \f(CW\(C`EV_USE_MONOTONIC\(C'\fR, though.
		1674	.IP "\s-1EV_USE_SELECT\s0" 4
		1675	.IX Item "EV_USE_SELECT"
		1676	If undefined or defined to be \f(CW1\fR, libev will compile in support for the
		1677	\&\f(CW\(C`select\(C'\fR(2) backend. No attempt at autodetection will be done: if no
		1678	other method takes over, select will be it. Otherwise the select backend
		1679	will not be compiled in.
		1680	.IP "\s-1EV_SELECT_USE_FD_SET\s0" 4
		1681	.IX Item "EV_SELECT_USE_FD_SET"
		1682	If defined to \f(CW1\fR, then the select backend will use the system \f(CW\(C`fd_set\(C'\fR
		1683	structure. This is useful if libev doesn't compile due to a missing
		1684	\&\f(CW\(C`NFDBITS\(C'\fR or \f(CW\(C`fd_mask\(C'\fR definition or it misguesses the bitset layout on
		1685	exotic systems. This usually limits the range of file descriptors to some
		1686	low limit such as 1024 or might have other limitations (winsocket only
		1687	allows 64 sockets). The \f(CW\(C`FD_SETSIZE\(C'\fR macro, set before compilation, might
		1688	influence the size of the \f(CW\(C`fd_set\(C'\fR used.
		1689	.IP "\s-1EV_SELECT_IS_WINSOCKET\s0" 4
		1690	.IX Item "EV_SELECT_IS_WINSOCKET"
		1691	When defined to \f(CW1\fR, the select backend will assume that
		1692	select/socket/connect etc. don't understand file descriptors but
		1693	wants osf handles on win32 (this is the case when the select to
		1694	be used is the winsock select). This means that it will call
		1695	\&\f(CW\(C`_get_osfhandle\(C'\fR on the fd to convert it to an \s-1OS\s0 handle. Otherwise,
		1696	it is assumed that all these functions actually work on fds, even
		1697	on win32. Should not be defined on non\-win32 platforms.
		1698	.IP "\s-1EV_USE_POLL\s0" 4
		1699	.IX Item "EV_USE_POLL"
		1700	If defined to be \f(CW1\fR, libev will compile in support for the \f(CW\(C`poll\(C'\fR(2)
		1701	backend. Otherwise it will be enabled on non\-win32 platforms. It
		1702	takes precedence over select.
		1703	.IP "\s-1EV_USE_EPOLL\s0" 4
		1704	.IX Item "EV_USE_EPOLL"
		1705	If defined to be \f(CW1\fR, libev will compile in support for the Linux
		1706	\&\f(CW\(C`epoll\(C'\fR(7) backend. Its availability will be detected at runtime,
		1707	otherwise another method will be used as fallback. This is the
		1708	preferred backend for GNU/Linux systems.
		1709	.IP "\s-1EV_USE_KQUEUE\s0" 4
		1710	.IX Item "EV_USE_KQUEUE"
		1711	If defined to be \f(CW1\fR, libev will compile in support for the \s-1BSD\s0 style
		1712	\&\f(CW\(C`kqueue\(C'\fR(2) backend. Its actual availability will be detected at runtime,
		1713	otherwise another method will be used as fallback. This is the preferred
		1714	backend for \s-1BSD\s0 and BSD-like systems, although on most BSDs kqueue only
		1715	supports some types of fds correctly (the only platform we found that
		1716	supports ptys for example was NetBSD), so kqueue might be compiled in, but
		1717	not be used unless explicitly requested. The best way to use it is to find
		1718	out whether kqueue supports your type of fd properly and use an embedded
		1719	kqueue loop.
		1720	.IP "\s-1EV_USE_PORT\s0" 4
		1721	.IX Item "EV_USE_PORT"
		1722	If defined to be \f(CW1\fR, libev will compile in support for the Solaris
		1723	10 port style backend. Its availability will be detected at runtime,
		1724	otherwise another method will be used as fallback. This is the preferred
		1725	backend for Solaris 10 systems.
		1726	.IP "\s-1EV_USE_DEVPOLL\s0" 4
		1727	.IX Item "EV_USE_DEVPOLL"
		1728	reserved for future expansion, works like the \s-1USE\s0 symbols above.
		1729	.IP "\s-1EV_H\s0" 4
		1730	.IX Item "EV_H"
		1731	The name of the \fIev.h\fR header file used to include it. The default if
		1732	undefined is \f(CW\(C`<ev.h>\(C'\fR in \fIevent.h\fR and \f(CW"ev.h"\fR in \fIev.c\fR. This
		1733	can be used to virtually rename the \fIev.h\fR header file in case of conflicts.
		1734	.IP "\s-1EV_CONFIG_H\s0" 4
		1735	.IX Item "EV_CONFIG_H"
		1736	If \f(CW\(C`EV_STANDALONE\(C'\fR isn't \f(CW1\fR, this variable can be used to override
		1737	\&\fIev.c\fR's idea of where to find the \fIconfig.h\fR file, similarly to
		1738	\&\f(CW\(C`EV_H\(C'\fR, above.
		1739	.IP "\s-1EV_EVENT_H\s0" 4
		1740	.IX Item "EV_EVENT_H"
		1741	Similarly to \f(CW\(C`EV_H\(C'\fR, this macro can be used to override \fIevent.c\fR's idea
		1742	of how the \fIevent.h\fR header can be found.
		1743	.IP "\s-1EV_PROTOTYPES\s0" 4
		1744	.IX Item "EV_PROTOTYPES"
		1745	If defined to be \f(CW0\fR, then \fIev.h\fR will not define any function
		1746	prototypes, but still define all the structs and other symbols. This is
		1747	occasionally useful if you want to provide your own wrapper functions
		1748	around libev functions.
		1749	.IP "\s-1EV_MULTIPLICITY\s0" 4
		1750	.IX Item "EV_MULTIPLICITY"
		1751	If undefined or defined to \f(CW1\fR, then all event-loop-specific functions
		1752	will have the \f(CW\(C`struct ev_loop \*(C'\fR as first argument, and you can create
		1753	additional independent event loops. Otherwise there will be no support
		1754	for multiple event loops and there is no first event loop pointer
		1755	argument. Instead, all functions act on the single default loop.
		1756	.IP "\s-1EV_PERIODICS\s0" 4
		1757	.IX Item "EV_PERIODICS"
		1758	If undefined or defined to be \f(CW1\fR, then periodic timers are supported,
		1759	otherwise not. This saves a few kb of code.
		1760	.IP "\s-1EV_COMMON\s0" 4
		1761	.IX Item "EV_COMMON"
		1762	By default, all watchers have a \f(CW\(C`void data\*(C'\fR member. By redefining
		1763	this macro to a something else you can include more and other types of
		1764	members. You have to define it each time you include one of the files,
		1765	though, and it must be identical each time.
		1766	.Sp
		1767	For example, the perl \s-1EV\s0 module uses something like this:
		1768	.Sp
		1769	.Vb 3
		1770	\& #define EV_COMMON \e
		1771	\& SV self; / contains this struct */ \e
		1772	\& SV cb_sv, fh /* note no trailing ";" */
		1773	.Ve
		1774	.IP "\s-1EV_CB_DECLARE\s0(type)" 4
		1775	.IX Item "EV_CB_DECLARE(type)"
		1776	.PD 0
		1777	.IP "\s-1EV_CB_INVOKE\s0(watcher,revents)" 4
		1778	.IX Item "EV_CB_INVOKE(watcher,revents)"
		1779	.IP "ev_set_cb(ev,cb)" 4
		1780	.IX Item "ev_set_cb(ev,cb)"
		1781	.PD
		1782	Can be used to change the callback member declaration in each watcher,
		1783	and the way callbacks are invoked and set. Must expand to a struct member
		1784	definition and a statement, respectively. See the \fIev.v\fR header file for
		1785	their default definitions. One possible use for overriding these is to
		1786	avoid the ev_loop pointer as first argument in all cases, or to use method
		1787	calls instead of plain function calls in \*(C+.
		1788	.Sh "\s-1EXAMPLES\s0"
		1789	.IX Subsection "EXAMPLES"
		1790	For a real-world example of a program the includes libev
		1791	verbatim, you can have a look at the \s-1EV\s0 perl module
		1792	(<http://software.schmorp.de/pkg/EV.html>). It has the libev files in
		1793	the \fIlibev/\fR subdirectory and includes them in the \fI\s-1EV/EVAPI\s0.h\fR (public
		1794	interface) and \fI\s-1EV\s0.xs\fR (implementation) files. Only the \fI\s-1EV\s0.xs\fR file
		1795	will be compiled. It is pretty complex because it provides its own header
		1796	file.
		1797	.Sp
		1798	The usage in rxvt-unicode is simpler. It has a \fIev_cpp.h\fR header file
		1799	that everybody includes and which overrides some autoconf choices:
		1800	.Sp
		1801	.Vb 4
		1802	\& #define EV_USE_POLL 0
		1803	\& #define EV_MULTIPLICITY 0
		1804	\& #define EV_PERIODICS 0
		1805	\& #define EV_CONFIG_H <config.h>
		1806	.Ve
		1807	.Sp
		1808	.Vb 1
		1809	\& #include "ev++.h"
		1810	.Ve
		1811	.Sp
		1812	And a \fIev_cpp.C\fR implementation file that contains libev proper and is compiled:
		1813	.Sp
		1814	.Vb 2
		1815	\& #include "ev_cpp.h"
		1816	\& #include "ev.c"
		1817	.Ve
1267	.SH "AUTHOR"	1818	.SH "AUTHOR"
1268	.IX Header "AUTHOR"	1819	.IX Header "AUTHOR"
1269	Marc Lehmann <libev@schmorp.de>.	1820	Marc Lehmann <libev@schmorp.de>.

Diff Legend

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

Comparing libev/ev.3 (file contents): Revision 1.9 by root, Fri Nov 23 16:17:12 2007 UTC vs. Revision 1.16 by root, Sat Nov 24 10:19:14 2007 UTC

Diff Legend

Comparing libev/ev.3 (file contents):
Revision 1.9 by root, Fri Nov 23 16:17:12 2007 UTC vs.
Revision 1.16 by root, Sat Nov 24 10:19:14 2007 UTC