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

Comparing libev/ev.pod (file contents):
Revision 1.40 by root, Sat Nov 24 10:15:16 2007 UTC vs.
Revision 1.48 by root, Tue Nov 27 08:11:52 2007 UTC

…		…
468	ev_ref (myloop);	468	ev_ref (myloop);
469	ev_signal_stop (myloop, &exitsig);	469	ev_signal_stop (myloop, &exitsig);
470		470
471	=back	471	=back
472		472
		473
473	=head1 ANATOMY OF A WATCHER	474	=head1 ANATOMY OF A WATCHER
474		475
475	A watcher is a structure that you create and register to record your	476	A watcher is a structure that you create and register to record your
476	interest in some event. For instance, if you want to wait for STDIN to	477	interest in some event. For instance, if you want to wait for STDIN to
477	become readable, you would create an C<ev_io> watcher for that:	478	become readable, you would create an C<ev_io> watcher for that:
…		…
543	The signal specified in the C<ev_signal> watcher has been received by a thread.	544	The signal specified in the C<ev_signal> watcher has been received by a thread.
544		545
545	=item C<EV_CHILD>	546	=item C<EV_CHILD>
546		547
547	The pid specified in the C<ev_child> watcher has received a status change.	548	The pid specified in the C<ev_child> watcher has received a status change.
		549
		550	=item C<EV_STAT>
		551
		552	The path specified in the C<ev_stat> watcher changed its attributes somehow.
548		553
549	=item C<EV_IDLE>	554	=item C<EV_IDLE>
550		555
551	The C<ev_idle> watcher has determined that you have nothing better to do.	556	The C<ev_idle> watcher has determined that you have nothing better to do.
552		557
…		…
576	with the error from read() or write(). This will not work in multithreaded	581	with the error from read() or write(). This will not work in multithreaded
577	programs, though, so beware.	582	programs, though, so beware.
578		583
579	=back	584	=back
580		585
581	=head2 SUMMARY OF GENERIC WATCHER FUNCTIONS	586	=head2 GENERIC WATCHER FUNCTIONS
582		587
583	In the following description, C<TYPE> stands for the watcher type,	588	In the following description, C<TYPE> stands for the watcher type,
584	e.g. C<timer> for C<ev_timer> watchers and C<io> for C<ev_io> watchers.	589	e.g. C<timer> for C<ev_timer> watchers and C<io> for C<ev_io> watchers.
585		590
586	=over 4	591	=over 4
…		…
595	which rolls both calls into one.	600	which rolls both calls into one.
596		601
597	You can reinitialise a watcher at any time as long as it has been stopped	602	You can reinitialise a watcher at any time as long as it has been stopped
598	(or never started) and there are no pending events outstanding.	603	(or never started) and there are no pending events outstanding.
599		604
600	The callbakc is always of type C<void ()(ev_loop loop, ev_TYPE *watcher,	605	The callback is always of type C<void ()(ev_loop loop, ev_TYPE *watcher,
601	int revents)>.	606	int revents)>.
602		607
603	=item C<ev_TYPE_set> (ev_TYPE *, [args])	608	=item C<ev_TYPE_set> (ev_TYPE *, [args])
604		609
605	This macro initialises the type-specific parts of a watcher. You need to	610	This macro initialises the type-specific parts of a watcher. You need to
…		…
688		693
689		694
690	=head1 WATCHER TYPES	695	=head1 WATCHER TYPES
691		696
692	This section describes each watcher in detail, but will not repeat	697	This section describes each watcher in detail, but will not repeat
693	information given in the last section.	698	information given in the last section. Any initialisation/set macros,
		699	functions and members specific to the watcher type are explained.
694		700
		701	Members are additionally marked with either I<[read-only]>, meaning that,
		702	while the watcher is active, you can look at the member and expect some
		703	sensible content, but you must not modify it (you can modify it while the
		704	watcher is stopped to your hearts content), or I<[read-write]>, which
		705	means you can expect it to have some sensible content while the watcher
		706	is active, but you can also modify it. Modifying it may not do something
		707	sensible or take immediate effect (or do anything at all), but libev will
		708	not crash or malfunction in any way.
695		709
		710
696	=head2 C<ev_io> - is this file descriptor readable or writable	711	=head2 C<ev_io> - is this file descriptor readable or writable?
697		712
698	I/O watchers check whether a file descriptor is readable or writable	713	I/O watchers check whether a file descriptor is readable or writable
699	in each iteration of the event loop (This behaviour is called	714	in each iteration of the event loop, or, more precisely, when reading
700	level-triggering because you keep receiving events as long as the	715	would not block the process and writing would at least be able to write
701	condition persists. Remember you can stop the watcher if you don't want to	716	some data. This behaviour is called level-triggering because you keep
702	act on the event and neither want to receive future events).	717	receiving events as long as the condition persists. Remember you can stop
		718	the watcher if you don't want to act on the event and neither want to
		719	receive future events.
703		720
704	In general you can register as many read and/or write event watchers per	721	In general you can register as many read and/or write event watchers per
705	fd as you want (as long as you don't confuse yourself). Setting all file	722	fd as you want (as long as you don't confuse yourself). Setting all file
706	descriptors to non-blocking mode is also usually a good idea (but not	723	descriptors to non-blocking mode is also usually a good idea (but not
707	required if you know what you are doing).	724	required if you know what you are doing).
708		725
709	You have to be careful with dup'ed file descriptors, though. Some backends	726	You have to be careful with dup'ed file descriptors, though. Some backends
710	(the linux epoll backend is a notable example) cannot handle dup'ed file	727	(the linux epoll backend is a notable example) cannot handle dup'ed file
711	descriptors correctly if you register interest in two or more fds pointing	728	descriptors correctly if you register interest in two or more fds pointing
712	to the same underlying file/socket etc. description (that is, they share	729	to the same underlying file/socket/etc. description (that is, they share
713	the same underlying "file open").	730	the same underlying "file open").
714		731
715	If you must do this, then force the use of a known-to-be-good backend	732	If you must do this, then force the use of a known-to-be-good backend
716	(at the time of this writing, this includes only C<EVBACKEND_SELECT> and	733	(at the time of this writing, this includes only C<EVBACKEND_SELECT> and
717	C<EVBACKEND_POLL>).	734	C<EVBACKEND_POLL>).
718		735
		736	Another thing you have to watch out for is that it is quite easy to
		737	receive "spurious" readyness notifications, that is your callback might
		738	be called with C<EV_READ> but a subsequent C<read>(2) will actually block
		739	because there is no data. Not only are some backends known to create a
		740	lot of those (for example solaris ports), it is very easy to get into
		741	this situation even with a relatively standard program structure. Thus
		742	it is best to always use non-blocking I/O: An extra C<read>(2) returning
		743	C<EAGAIN> is far preferable to a program hanging until some data arrives.
		744
		745	If you cannot run the fd in non-blocking mode (for example you should not
		746	play around with an Xlib connection), then you have to seperately re-test
		747	wether a file descriptor is really ready with a known-to-be good interface
		748	such as poll (fortunately in our Xlib example, Xlib already does this on
		749	its own, so its quite safe to use).
		750
719	=over 4	751	=over 4
720		752
721	=item ev_io_init (ev_io *, callback, int fd, int events)	753	=item ev_io_init (ev_io *, callback, int fd, int events)
722		754
723	=item ev_io_set (ev_io *, int fd, int events)	755	=item ev_io_set (ev_io *, int fd, int events)
724		756
725	Configures an C<ev_io> watcher. The fd is the file descriptor to rceeive	757	Configures an C<ev_io> watcher. The C<fd> is the file descriptor to
726	events for and events is either C<EV_READ>, C<EV_WRITE> or C<EV_READ \|	758	rceeive events for and events is either C<EV_READ>, C<EV_WRITE> or
727	EV_WRITE> to receive the given events.	759	C<EV_READ \| EV_WRITE> to receive the given events.
728		760
729	Please note that most of the more scalable backend mechanisms (for example	761	=item int fd [read-only]
730	epoll and solaris ports) can result in spurious readyness notifications	762
731	for file descriptors, so you practically need to use non-blocking I/O (and	763	The file descriptor being watched.
732	treat callback invocation as hint only), or retest separately with a safe	764
733	interface before doing I/O (XLib can do this), or force the use of either	765	=item int events [read-only]
734	C<EVBACKEND_SELECT> or C<EVBACKEND_POLL>, which don't suffer from this	766
735	problem. Also note that it is quite easy to have your callback invoked	767	The events being watched.
736	when the readyness condition is no longer valid even when employing
737	typical ways of handling events, so its a good idea to use non-blocking
738	I/O unconditionally.
739		768
740	=back	769	=back
741		770
742	Example: call C<stdin_readable_cb> when STDIN_FILENO has become, well	771	Example: call C<stdin_readable_cb> when STDIN_FILENO has become, well
743	readable, but only once. Since it is likely line-buffered, you could	772	readable, but only once. Since it is likely line-buffered, you could
…		…
756	ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ);	785	ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ);
757	ev_io_start (loop, &stdin_readable);	786	ev_io_start (loop, &stdin_readable);
758	ev_loop (loop, 0);	787	ev_loop (loop, 0);
759		788
760		789
761	=head2 C<ev_timer> - relative and optionally recurring timeouts	790	=head2 C<ev_timer> - relative and optionally repeating timeouts
762		791
763	Timer watchers are simple relative timers that generate an event after a	792	Timer watchers are simple relative timers that generate an event after a
764	given time, and optionally repeating in regular intervals after that.	793	given time, and optionally repeating in regular intervals after that.
765		794
766	The timers are based on real time, that is, if you register an event that	795	The timers are based on real time, that is, if you register an event that
…		…
807		836
808	If the timer is repeating, either start it if necessary (with the repeat	837	If the timer is repeating, either start it if necessary (with the repeat
809	value), or reset the running timer to the repeat value.	838	value), or reset the running timer to the repeat value.
810		839
811	This sounds a bit complicated, but here is a useful and typical	840	This sounds a bit complicated, but here is a useful and typical
812	example: Imagine you have a tcp connection and you want a so-called idle	841	example: Imagine you have a tcp connection and you want a so-called
813	timeout, that is, you want to be called when there have been, say, 60	842	idle timeout, that is, you want to be called when there have been,
814	seconds of inactivity on the socket. The easiest way to do this is to	843	say, 60 seconds of inactivity on the socket. The easiest way to do
815	configure an C<ev_timer> with after=repeat=60 and calling ev_timer_again each	844	this is to configure an C<ev_timer> with C<after>=C<repeat>=C<60> and calling
816	time you successfully read or write some data. If you go into an idle	845	C<ev_timer_again> each time you successfully read or write some data. If
817	state where you do not expect data to travel on the socket, you can stop	846	you go into an idle state where you do not expect data to travel on the
818	the timer, and again will automatically restart it if need be.	847	socket, you can stop the timer, and again will automatically restart it if
		848	need be.
		849
		850	You can also ignore the C<after> value and C<ev_timer_start> altogether
		851	and only ever use the C<repeat> value:
		852
		853	ev_timer_init (timer, callback, 0., 5.);
		854	ev_timer_again (loop, timer);
		855	...
		856	timer->again = 17.;
		857	ev_timer_again (loop, timer);
		858	...
		859	timer->again = 10.;
		860	ev_timer_again (loop, timer);
		861
		862	This is more efficient then stopping/starting the timer eahc time you want
		863	to modify its timeout value.
		864
		865	=item ev_tstamp repeat [read-write]
		866
		867	The current C<repeat> value. Will be used each time the watcher times out
		868	or C<ev_timer_again> is called and determines the next timeout (if any),
		869	which is also when any modifications are taken into account.
819		870
820	=back	871	=back
821		872
822	Example: create a timer that fires after 60 seconds.	873	Example: create a timer that fires after 60 seconds.
823		874
…		…
848	// and in some piece of code that gets executed on any "activity":	899	// and in some piece of code that gets executed on any "activity":
849	// reset the timeout to start ticking again at 10 seconds	900	// reset the timeout to start ticking again at 10 seconds
850	ev_timer_again (&mytimer);	901	ev_timer_again (&mytimer);
851		902
852		903
853	=head2 C<ev_periodic> - to cron or not to cron	904	=head2 C<ev_periodic> - to cron or not to cron?
854		905
855	Periodic watchers are also timers of a kind, but they are very versatile	906	Periodic watchers are also timers of a kind, but they are very versatile
856	(and unfortunately a bit complex).	907	(and unfortunately a bit complex).
857		908
858	Unlike C<ev_timer>'s, they are not based on real time (or relative time)	909	Unlike C<ev_timer>'s, they are not based on real time (or relative time)
…		…
950	Simply stops and restarts the periodic watcher again. This is only useful	1001	Simply stops and restarts the periodic watcher again. This is only useful
951	when you changed some parameters or the reschedule callback would return	1002	when you changed some parameters or the reschedule callback would return
952	a different time than the last time it was called (e.g. in a crond like	1003	a different time than the last time it was called (e.g. in a crond like
953	program when the crontabs have changed).	1004	program when the crontabs have changed).
954		1005
		1006	=item ev_tstamp interval [read-write]
		1007
		1008	The current interval value. Can be modified any time, but changes only
		1009	take effect when the periodic timer fires or C<ev_periodic_again> is being
		1010	called.
		1011
		1012	=item ev_tstamp (reschedule_cb)(struct ev_periodic w, ev_tstamp now) [read-write]
		1013
		1014	The current reschedule callback, or C<0>, if this functionality is
		1015	switched off. Can be changed any time, but changes only take effect when
		1016	the periodic timer fires or C<ev_periodic_again> is being called.
		1017
955	=back	1018	=back
956		1019
957	Example: call a callback every hour, or, more precisely, whenever the	1020	Example: call a callback every hour, or, more precisely, whenever the
958	system clock is divisible by 3600. The callback invocation times have	1021	system clock is divisible by 3600. The callback invocation times have
959	potentially a lot of jittering, but good long-term stability.	1022	potentially a lot of jittering, but good long-term stability.
…		…
986	ev_periodic_init (&hourly_tick, clock_cb,	1049	ev_periodic_init (&hourly_tick, clock_cb,
987	fmod (ev_now (loop), 3600.), 3600., 0);	1050	fmod (ev_now (loop), 3600.), 3600., 0);
988	ev_periodic_start (loop, &hourly_tick);	1051	ev_periodic_start (loop, &hourly_tick);
989		1052
990		1053
991	=head2 C<ev_signal> - signal me when a signal gets signalled	1054	=head2 C<ev_signal> - signal me when a signal gets signalled!
992		1055
993	Signal watchers will trigger an event when the process receives a specific	1056	Signal watchers will trigger an event when the process receives a specific
994	signal one or more times. Even though signals are very asynchronous, libev	1057	signal one or more times. Even though signals are very asynchronous, libev
995	will try it's best to deliver signals synchronously, i.e. as part of the	1058	will try it's best to deliver signals synchronously, i.e. as part of the
996	normal event processing, like any other event.	1059	normal event processing, like any other event.
…		…
1009	=item ev_signal_set (ev_signal *, int signum)	1072	=item ev_signal_set (ev_signal *, int signum)
1010		1073
1011	Configures the watcher to trigger on the given signal number (usually one	1074	Configures the watcher to trigger on the given signal number (usually one
1012	of the C<SIGxxx> constants).	1075	of the C<SIGxxx> constants).
1013		1076
		1077	=item int signum [read-only]
		1078
		1079	The signal the watcher watches out for.
		1080
1014	=back	1081	=back
1015		1082
1016		1083
1017	=head2 C<ev_child> - wait for pid status changes	1084	=head2 C<ev_child> - watch out for process status changes
1018		1085
1019	Child watchers trigger when your process receives a SIGCHLD in response to	1086	Child watchers trigger when your process receives a SIGCHLD in response to
1020	some child status changes (most typically when a child of yours dies).	1087	some child status changes (most typically when a child of yours dies).
1021		1088
1022	=over 4	1089	=over 4
…		…
1030	at the C<rstatus> member of the C<ev_child> watcher structure to see	1097	at the C<rstatus> member of the C<ev_child> watcher structure to see
1031	the status word (use the macros from C<sys/wait.h> and see your systems	1098	the status word (use the macros from C<sys/wait.h> and see your systems
1032	C<waitpid> documentation). The C<rpid> member contains the pid of the	1099	C<waitpid> documentation). The C<rpid> member contains the pid of the
1033	process causing the status change.	1100	process causing the status change.
1034		1101
		1102	=item int pid [read-only]
		1103
		1104	The process id this watcher watches out for, or C<0>, meaning any process id.
		1105
		1106	=item int rpid [read-write]
		1107
		1108	The process id that detected a status change.
		1109
		1110	=item int rstatus [read-write]
		1111
		1112	The process exit/trace status caused by C<rpid> (see your systems
		1113	C<waitpid> and C<sys/wait.h> documentation for details).
		1114
1035	=back	1115	=back
1036		1116
1037	Example: try to exit cleanly on SIGINT and SIGTERM.	1117	Example: try to exit cleanly on SIGINT and SIGTERM.
1038		1118
1039	static void	1119	static void
…		…
1045	struct ev_signal signal_watcher;	1125	struct ev_signal signal_watcher;
1046	ev_signal_init (&signal_watcher, sigint_cb, SIGINT);	1126	ev_signal_init (&signal_watcher, sigint_cb, SIGINT);
1047	ev_signal_start (loop, &sigint_cb);	1127	ev_signal_start (loop, &sigint_cb);
1048		1128
1049		1129
		1130	=head2 C<ev_stat> - did the file attributes just change?
		1131
		1132	This watches a filesystem path for attribute changes. That is, it calls
		1133	C<stat> regularly (or when the OS says it changed) and sees if it changed
		1134	compared to the last time, invoking the callback if it did.
		1135
		1136	The path does not need to exist: changing from "path exists" to "path does
		1137	not exist" is a status change like any other. The condition "path does
		1138	not exist" is signified by the C<st_nlink> field being zero (which is
		1139	otherwise always forced to be at least one) and all the other fields of
		1140	the stat buffer having unspecified contents.
		1141
		1142	Since there is no standard to do this, the portable implementation simply
		1143	calls C<stat (2)> regulalry on the path to see if it changed somehow. You
		1144	can specify a recommended polling interval for this case. If you specify
		1145	a polling interval of C<0> (highly recommended!) then a I<suitable,
		1146	unspecified default> value will be used (which you can expect to be around
		1147	five seconds, although this might change dynamically). Libev will also
		1148	impose a minimum interval which is currently around C<0.1>, but thats
		1149	usually overkill.
		1150
		1151	This watcher type is not meant for massive numbers of stat watchers,
		1152	as even with OS-supported change notifications, this can be
		1153	resource-intensive.
		1154
		1155	At the time of this writing, no specific OS backends are implemented, but
		1156	if demand increases, at least a kqueue and inotify backend will be added.
		1157
		1158	=over 4
		1159
		1160	=item ev_stat_init (ev_stat , callback, const char path, ev_tstamp interval)
		1161
		1162	=item ev_stat_set (ev_stat , const char path, ev_tstamp interval)
		1163
		1164	Configures the watcher to wait for status changes of the given
		1165	C<path>. The C<interval> is a hint on how quickly a change is expected to
		1166	be detected and should normally be specified as C<0> to let libev choose
		1167	a suitable value. The memory pointed to by C<path> must point to the same
		1168	path for as long as the watcher is active.
		1169
		1170	The callback will be receive C<EV_STAT> when a change was detected,
		1171	relative to the attributes at the time the watcher was started (or the
		1172	last change was detected).
		1173
		1174	=item ev_stat_stat (ev_stat *)
		1175
		1176	Updates the stat buffer immediately with new values. If you change the
		1177	watched path in your callback, you could call this fucntion to avoid
		1178	detecting this change (while introducing a race condition). Can also be
		1179	useful simply to find out the new values.
		1180
		1181	=item ev_statdata attr [read-only]
		1182
		1183	The most-recently detected attributes of the file. Although the type is of
		1184	C<ev_statdata>, this is usually the (or one of the) C<struct stat> types
		1185	suitable for your system. If the C<st_nlink> member is C<0>, then there
		1186	was some error while C<stat>ing the file.
		1187
		1188	=item ev_statdata prev [read-only]
		1189
		1190	The previous attributes of the file. The callback gets invoked whenever
		1191	C<prev> != C<attr>.
		1192
		1193	=item ev_tstamp interval [read-only]
		1194
		1195	The specified interval.
		1196
		1197	=item const char *path [read-only]
		1198
		1199	The filesystem path that is being watched.
		1200
		1201	=back
		1202
		1203	Example: Watch C</etc/passwd> for attribute changes.
		1204
		1205	static void
		1206	passwd_cb (struct ev_loop loop, ev_stat w, int revents)
		1207	{
		1208	/* /etc/passwd changed in some way */
		1209	if (w->attr.st_nlink)
		1210	{
		1211	printf ("passwd current size %ld\n", (long)w->attr.st_size);
		1212	printf ("passwd current atime %ld\n", (long)w->attr.st_mtime);
		1213	printf ("passwd current mtime %ld\n", (long)w->attr.st_mtime);
		1214	}
		1215	else
		1216	/* you shalt not abuse printf for puts */
		1217	puts ("wow, /etc/passwd is not there, expect problems. "
		1218	"if this is windows, they already arrived\n");
		1219	}
		1220
		1221	...
		1222	ev_stat passwd;
		1223
		1224	ev_stat_init (&passwd, passwd_cb, "/etc/passwd");
		1225	ev_stat_start (loop, &passwd);
		1226
		1227
1050	=head2 C<ev_idle> - when you've got nothing better to do	1228	=head2 C<ev_idle> - when you've got nothing better to do...
1051		1229
1052	Idle watchers trigger events when there are no other events are pending	1230	Idle watchers trigger events when there are no other events are pending
1053	(prepare, check and other idle watchers do not count). That is, as long	1231	(prepare, check and other idle watchers do not count). That is, as long
1054	as your process is busy handling sockets or timeouts (or even signals,	1232	as your process is busy handling sockets or timeouts (or even signals,
1055	imagine) it will not be triggered. But when your process is idle all idle	1233	imagine) it will not be triggered. But when your process is idle all idle
…		…
1089	struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle));	1267	struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle));
1090	ev_idle_init (idle_watcher, idle_cb);	1268	ev_idle_init (idle_watcher, idle_cb);
1091	ev_idle_start (loop, idle_cb);	1269	ev_idle_start (loop, idle_cb);
1092		1270
1093		1271
1094	=head2 C<ev_prepare> and C<ev_check> - customise your event loop	1272	=head2 C<ev_prepare> and C<ev_check> - customise your event loop!
1095		1273
1096	Prepare and check watchers are usually (but not always) used in tandem:	1274	Prepare and check watchers are usually (but not always) used in tandem:
1097	prepare watchers get invoked before the process blocks and check watchers	1275	prepare watchers get invoked before the process blocks and check watchers
1098	afterwards.	1276	afterwards.
1099		1277
		1278	You I<must not> call C<ev_loop> or similar functions that enter
		1279	the current event loop from either C<ev_prepare> or C<ev_check>
		1280	watchers. Other loops than the current one are fine, however. The
		1281	rationale behind this is that you do not need to check for recursion in
		1282	those watchers, i.e. the sequence will always be C<ev_prepare>, blocking,
		1283	C<ev_check> so if you have one watcher of each kind they will always be
		1284	called in pairs bracketing the blocking call.
		1285
1100	Their main purpose is to integrate other event mechanisms into libev and	1286	Their main purpose is to integrate other event mechanisms into libev and
1101	their use is somewhat advanced. This could be used, for example, to track	1287	their use is somewhat advanced. This could be used, for example, to track
1102	variable changes, implement your own watchers, integrate net-snmp or a	1288	variable changes, implement your own watchers, integrate net-snmp or a
1103	coroutine library and lots more.	1289	coroutine library and lots more. They are also occasionally useful if
		1290	you cache some data and want to flush it before blocking (for example,
		1291	in X programs you might want to do an C<XFlush ()> in an C<ev_prepare>
		1292	watcher).
1104		1293
1105	This is done by examining in each prepare call which file descriptors need	1294	This is done by examining in each prepare call which file descriptors need
1106	to be watched by the other library, registering C<ev_io> watchers for	1295	to be watched by the other library, registering C<ev_io> watchers for
1107	them and starting an C<ev_timer> watcher for any timeouts (many libraries	1296	them and starting an C<ev_timer> watcher for any timeouts (many libraries
1108	provide just this functionality). Then, in the check watcher you check for	1297	provide just this functionality). Then, in the check watcher you check for
…		…
1130	parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set>	1319	parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set>
1131	macros, but using them is utterly, utterly and completely pointless.	1320	macros, but using them is utterly, utterly and completely pointless.
1132		1321
1133	=back	1322	=back
1134		1323
1135	Example: TODO.	1324	Example: To include a library such as adns, you would add IO watchers
		1325	and a timeout watcher in a prepare handler, as required by libadns, and
		1326	in a check watcher, destroy them and call into libadns. What follows is
		1327	pseudo-code only of course:
1136		1328
		1329	static ev_io iow [nfd];
		1330	static ev_timer tw;
1137		1331
		1332	static void
		1333	io_cb (ev_loop loop, ev_io w, int revents)
		1334	{
		1335	// set the relevant poll flags
		1336	// could also call adns_processreadable etc. here
		1337	struct pollfd fd = (struct pollfd )w->data;
		1338	if (revents & EV_READ ) fd->revents \|= fd->events & POLLIN;
		1339	if (revents & EV_WRITE) fd->revents \|= fd->events & POLLOUT;
		1340	}
		1341
		1342	// create io watchers for each fd and a timer before blocking
		1343	static void
		1344	adns_prepare_cb (ev_loop loop, ev_prepare w, int revents)
		1345	{
		1346	int timeout = 3600000;truct pollfd fds [nfd];
		1347	// actual code will need to loop here and realloc etc.
		1348	adns_beforepoll (ads, fds, &nfd, &timeout, timeval_from (ev_time ()));
		1349
		1350	/* the callback is illegal, but won't be called as we stop during check */
		1351	ev_timer_init (&tw, 0, timeout * 1e-3);
		1352	ev_timer_start (loop, &tw);
		1353
		1354	// create on ev_io per pollfd
		1355	for (int i = 0; i < nfd; ++i)
		1356	{
		1357	ev_io_init (iow + i, io_cb, fds [i].fd,
		1358	((fds [i].events & POLLIN ? EV_READ : 0)
		1359	\| (fds [i].events & POLLOUT ? EV_WRITE : 0)));
		1360
		1361	fds [i].revents = 0;
		1362	iow [i].data = fds + i;
		1363	ev_io_start (loop, iow + i);
		1364	}
		1365	}
		1366
		1367	// stop all watchers after blocking
		1368	static void
		1369	adns_check_cb (ev_loop loop, ev_check w, int revents)
		1370	{
		1371	ev_timer_stop (loop, &tw);
		1372
		1373	for (int i = 0; i < nfd; ++i)
		1374	ev_io_stop (loop, iow + i);
		1375
		1376	adns_afterpoll (adns, fds, nfd, timeval_from (ev_now (loop));
		1377	}
		1378
		1379
1138	=head2 C<ev_embed> - when one backend isn't enough	1380	=head2 C<ev_embed> - when one backend isn't enough...
1139		1381
1140	This is a rather advanced watcher type that lets you embed one event loop	1382	This is a rather advanced watcher type that lets you embed one event loop
1141	into another (currently only C<ev_io> events are supported in the embedded	1383	into another (currently only C<ev_io> events are supported in the embedded
1142	loop, other types of watchers might be handled in a delayed or incorrect	1384	loop, other types of watchers might be handled in a delayed or incorrect
1143	fashion and must not be used).	1385	fashion and must not be used).
…		…
1221		1463
1222	Make a single, non-blocking sweep over the embedded loop. This works	1464	Make a single, non-blocking sweep over the embedded loop. This works
1223	similarly to C<ev_loop (embedded_loop, EVLOOP_NONBLOCK)>, but in the most	1465	similarly to C<ev_loop (embedded_loop, EVLOOP_NONBLOCK)>, but in the most
1224	apropriate way for embedded loops.	1466	apropriate way for embedded loops.
1225		1467
		1468	=item struct ev_loop *loop [read-only]
		1469
		1470	The embedded event loop.
		1471
1226	=back	1472	=back
1227		1473
1228		1474
1229	=head1 OTHER FUNCTIONS	1475	=head1 OTHER FUNCTIONS
1230		1476
…		…
1462	ev_vars.h	1708	ev_vars.h
1463	ev_wrap.h	1709	ev_wrap.h
1464		1710
1465	ev_win32.c required on win32 platforms only	1711	ev_win32.c required on win32 platforms only
1466		1712
1467	ev_select.c only when select backend is enabled (which is is by default)	1713	ev_select.c only when select backend is enabled (which is by default)
1468	ev_poll.c only when poll backend is enabled (disabled by default)	1714	ev_poll.c only when poll backend is enabled (disabled by default)
1469	ev_epoll.c only when the epoll backend is enabled (disabled by default)	1715	ev_epoll.c only when the epoll backend is enabled (disabled by default)
1470	ev_kqueue.c only when the kqueue backend is enabled (disabled by default)	1716	ev_kqueue.c only when the kqueue backend is enabled (disabled by default)
1471	ev_port.c only when the solaris port backend is enabled (disabled by default)	1717	ev_port.c only when the solaris port backend is enabled (disabled by default)
1472		1718
1473	F<ev.c> includes the backend files directly when enabled, so you only need	1719	F<ev.c> includes the backend files directly when enabled, so you only need
1474	to compile a single file.	1720	to compile this single file.
1475		1721
1476	=head3 LIBEVENT COMPATIBILITY API	1722	=head3 LIBEVENT COMPATIBILITY API
1477		1723
1478	To include the libevent compatibility API, also include:	1724	To include the libevent compatibility API, also include:
1479		1725
…		…
1492		1738
1493	=head3 AUTOCONF SUPPORT	1739	=head3 AUTOCONF SUPPORT
1494		1740
1495	Instead of using C<EV_STANDALONE=1> and providing your config in	1741	Instead of using C<EV_STANDALONE=1> and providing your config in
1496	whatever way you want, you can also C<m4_include([libev.m4])> in your	1742	whatever way you want, you can also C<m4_include([libev.m4])> in your
1497	F<configure.ac> and leave C<EV_STANDALONE> off. F<ev.c> will then include	1743	F<configure.ac> and leave C<EV_STANDALONE> undefined. F<ev.c> will then
1498	F<config.h> and configure itself accordingly.	1744	include F<config.h> and configure itself accordingly.
1499		1745
1500	For this of course you need the m4 file:	1746	For this of course you need the m4 file:
1501		1747
1502	libev.m4	1748	libev.m4
1503		1749
…		…
1583	otherwise another method will be used as fallback. This is the preferred	1829	otherwise another method will be used as fallback. This is the preferred
1584	backend for BSD and BSD-like systems, although on most BSDs kqueue only	1830	backend for BSD and BSD-like systems, although on most BSDs kqueue only
1585	supports some types of fds correctly (the only platform we found that	1831	supports some types of fds correctly (the only platform we found that
1586	supports ptys for example was NetBSD), so kqueue might be compiled in, but	1832	supports ptys for example was NetBSD), so kqueue might be compiled in, but
1587	not be used unless explicitly requested. The best way to use it is to find	1833	not be used unless explicitly requested. The best way to use it is to find
1588	out wether kqueue supports your type of fd properly and use an embedded	1834	out whether kqueue supports your type of fd properly and use an embedded
1589	kqueue loop.	1835	kqueue loop.
1590		1836
1591	=item EV_USE_PORT	1837	=item EV_USE_PORT
1592		1838
1593	If defined to be C<1>, libev will compile in support for the Solaris	1839	If defined to be C<1>, libev will compile in support for the Solaris
…		…
1629	will have the C<struct ev_loop *> as first argument, and you can create	1875	will have the C<struct ev_loop *> as first argument, and you can create
1630	additional independent event loops. Otherwise there will be no support	1876	additional independent event loops. Otherwise there will be no support
1631	for multiple event loops and there is no first event loop pointer	1877	for multiple event loops and there is no first event loop pointer
1632	argument. Instead, all functions act on the single default loop.	1878	argument. Instead, all functions act on the single default loop.
1633		1879
1634	=item EV_PERIODICS	1880	=item EV_PERIODIC_ENABLE
1635		1881
1636	If undefined or defined to be C<1>, then periodic timers are supported,	1882	If undefined or defined to be C<1>, then periodic timers are supported. If
1637	otherwise not. This saves a few kb of code.	1883	defined to be C<0>, then they are not. Disabling them saves a few kB of
		1884	code.
		1885
		1886	=item EV_EMBED_ENABLE
		1887
		1888	If undefined or defined to be C<1>, then embed watchers are supported. If
		1889	defined to be C<0>, then they are not.
		1890
		1891	=item EV_STAT_ENABLE
		1892
		1893	If undefined or defined to be C<1>, then stat watchers are supported. If
		1894	defined to be C<0>, then they are not.
		1895
		1896	=item EV_MINIMAL
		1897
		1898	If you need to shave off some kilobytes of code at the expense of some
		1899	speed, define this symbol to C<1>. Currently only used for gcc to override
		1900	some inlining decisions, saves roughly 30% codesize of amd64.
1638		1901
1639	=item EV_COMMON	1902	=item EV_COMMON
1640		1903
1641	By default, all watchers have a C<void *data> member. By redefining	1904	By default, all watchers have a C<void *data> member. By redefining
1642	this macro to a something else you can include more and other types of	1905	this macro to a something else you can include more and other types of
…		…
1647		1910
1648	#define EV_COMMON \	1911	#define EV_COMMON \
1649	SV self; / contains this struct */ \	1912	SV self; / contains this struct */ \
1650	SV cb_sv, fh /* note no trailing ";" */	1913	SV cb_sv, fh /* note no trailing ";" */
1651		1914
1652	=item EV_CB_DECLARE(type)	1915	=item EV_CB_DECLARE (type)
1653		1916
1654	=item EV_CB_INVOKE(watcher,revents)	1917	=item EV_CB_INVOKE (watcher, revents)
1655		1918
1656	=item ev_set_cb(ev,cb)	1919	=item ev_set_cb (ev, cb)
1657		1920
1658	Can be used to change the callback member declaration in each watcher,	1921	Can be used to change the callback member declaration in each watcher,
1659	and the way callbacks are invoked and set. Must expand to a struct member	1922	and the way callbacks are invoked and set. Must expand to a struct member
1660	definition and a statement, respectively. See the F<ev.v> header file for	1923	definition and a statement, respectively. See the F<ev.v> header file for
1661	their default definitions. One possible use for overriding these is to	1924	their default definitions. One possible use for overriding these is to
1662	avoid the ev_loop pointer as first argument in all cases, or to use method	1925	avoid the C<struct ev_loop *> as first argument in all cases, or to use
1663	calls instead of plain function calls in C++.	1926	method calls instead of plain function calls in C++.
1664		1927
1665	=head2 EXAMPLES	1928	=head2 EXAMPLES
1666		1929
1667	For a real-world example of a program the includes libev	1930	For a real-world example of a program the includes libev
1668	verbatim, you can have a look at the EV perl module	1931	verbatim, you can have a look at the EV perl module
…		…
1685	And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:	1948	And a F<ev_cpp.C> implementation file that contains libev proper and is compiled:
1686		1949
1687	#include "ev_cpp.h"	1950	#include "ev_cpp.h"
1688	#include "ev.c"	1951	#include "ev.c"
1689		1952
		1953
		1954	=head1 COMPLEXITIES
		1955
		1956	In this section the complexities of (many of) the algorithms used inside
		1957	libev will be explained. For complexity discussions about backends see the
		1958	documentation for C<ev_default_init>.
		1959
		1960	=over 4
		1961
		1962	=item Starting and stopping timer/periodic watchers: O(log skipped_other_timers)
		1963
		1964	=item Changing timer/periodic watchers (by autorepeat, again): O(log skipped_other_timers)
		1965
		1966	=item Starting io/check/prepare/idle/signal/child watchers: O(1)
		1967
		1968	=item Stopping check/prepare/idle watchers: O(1)
		1969
		1970	=item Stopping an io/signal/child watcher: O(number_of_watchers_for_this_(fd/signal/pid % 16))
		1971
		1972	=item Finding the next timer per loop iteration: O(1)
		1973
		1974	=item Each change on a file descriptor per loop iteration: O(number_of_watchers_for_this_fd)
		1975
		1976	=item Activating one watcher: O(1)
		1977
		1978	=back
		1979
		1980
1690	=head1 AUTHOR	1981	=head1 AUTHOR
1691		1982
1692	Marc Lehmann <libev@schmorp.de>.	1983	Marc Lehmann <libev@schmorp.de>.
1693		1984

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.40 by root, Sat Nov 24 10:15:16 2007 UTC vs. Revision 1.48 by root, Tue Nov 27 08:11:52 2007 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.40 by root, Sat Nov 24 10:15:16 2007 UTC vs.
Revision 1.48 by root, Tue Nov 27 08:11:52 2007 UTC