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

Comparing libev/ev.pod (file contents):
Revision 1.273 by root, Tue Nov 24 14:46:59 2009 UTC vs.
Revision 1.277 by root, Thu Dec 31 06:50:17 2009 UTC

Diff Legend

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

…		…
118	Libev is very configurable. In this manual the default (and most common)	118	Libev is very configurable. In this manual the default (and most common)
119	configuration will be described, which supports multiple event loops. For	119	configuration will be described, which supports multiple event loops. For
120	more info about various configuration options please have a look at	120	more info about various configuration options please have a look at
121	B<EMBED> section in this manual. If libev was configured without support	121	B<EMBED> section in this manual. If libev was configured without support
122	for multiple event loops, then all functions taking an initial argument of	122	for multiple event loops, then all functions taking an initial argument of
123	name C<loop> (which is always of type C<ev_loop *>) will not have	123	name C<loop> (which is always of type C<struct ev_loop *>) will not have
124	this argument.	124	this argument.
125		125
126	=head2 TIME REPRESENTATION	126	=head2 TIME REPRESENTATION
127		127
128	Libev represents time as a single floating point number, representing	128	Libev represents time as a single floating point number, representing
…		…
370	When this flag is specified, then libev will not attempt to use the	370	When this flag is specified, then libev will not attempt to use the
371	I<inotify> API for it's C<ev_stat> watchers. Apart from debugging and	371	I<inotify> API for it's C<ev_stat> watchers. Apart from debugging and
372	testing, this flag can be useful to conserve inotify file descriptors, as	372	testing, this flag can be useful to conserve inotify file descriptors, as
373	otherwise each loop using C<ev_stat> watchers consumes one inotify handle.	373	otherwise each loop using C<ev_stat> watchers consumes one inotify handle.
374		374
375	=item C<EVFLAG_NOSIGFD>	375	=item C<EVFLAG_SIGNALFD>
376		376
377	When this flag is specified, then libev will not attempt to use the	377	When this flag is specified, then libev will attempt to use the
378	I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This is	378	I<signalfd> API for it's C<ev_signal> (and C<ev_child>) watchers. This API
379	probably only useful to work around any bugs in libev. Consequently, this	379	delivers signals synchronously, which makes is both faster and might make
380	flag might go away once the signalfd functionality is considered stable,	380	it possible to get the queued signal data.
381	so it's useful mostly in environment variables and not in program code.	381
		382	Signalfd will not be used by default as this changes your signal mask, and
		383	there are a lot of shoddy libraries and programs (glib's threadpool for
		384	example) that can't properly initialise their signal masks.
382		385
383	=item C<EVBACKEND_SELECT> (value 1, portable select backend)	386	=item C<EVBACKEND_SELECT> (value 1, portable select backend)
384		387
385	This is your standard select(2) backend. Not I<completely> standard, as	388	This is your standard select(2) backend. Not I<completely> standard, as
386	libev tries to roll its own fd_set with no limits on the number of fds,	389	libev tries to roll its own fd_set with no limits on the number of fds,
…		…
792		795
793	Ref/unref can be used to add or remove a reference count on the event	796	Ref/unref can be used to add or remove a reference count on the event
794	loop: Every watcher keeps one reference, and as long as the reference	797	loop: Every watcher keeps one reference, and as long as the reference
795	count is nonzero, C<ev_loop> will not return on its own.	798	count is nonzero, C<ev_loop> will not return on its own.
796		799
797	If you have a watcher you never unregister that should not keep C<ev_loop>	800	This is useful when you have a watcher that you never intend to
798	from returning, call ev_unref() after starting, and ev_ref() before	801	unregister, but that nevertheless should not keep C<ev_loop> from
		802	returning. In such a case, call C<ev_unref> after starting, and C<ev_ref>
799	stopping it.	803	before stopping it.
800		804
801	As an example, libev itself uses this for its internal signal pipe: It	805	As an example, libev itself uses this for its internal signal pipe: It
802	is not visible to the libev user and should not keep C<ev_loop> from	806	is not visible to the libev user and should not keep C<ev_loop> from
803	exiting if no event watchers registered by it are active. It is also an	807	exiting if no event watchers registered by it are active. It is also an
804	excellent way to do this for generic recurring timers or from within	808	excellent way to do this for generic recurring timers or from within
…		…
919		923
920	While event loop modifications are allowed between invocations of	924	While event loop modifications are allowed between invocations of
921	C<release> and C<acquire> (that's their only purpose after all), no	925	C<release> and C<acquire> (that's their only purpose after all), no
922	modifications done will affect the event loop, i.e. adding watchers will	926	modifications done will affect the event loop, i.e. adding watchers will
923	have no effect on the set of file descriptors being watched, or the time	927	have no effect on the set of file descriptors being watched, or the time
924	waited. USe an C<ev_async> watcher to wake up C<ev_loop> when you want it	928	waited. Use an C<ev_async> watcher to wake up C<ev_loop> when you want it
925	to take note of any changes you made.	929	to take note of any changes you made.
926		930
927	In theory, threads executing C<ev_loop> will be async-cancel safe between	931	In theory, threads executing C<ev_loop> will be async-cancel safe between
928	invocations of C<release> and C<acquire>.	932	invocations of C<release> and C<acquire>.
929		933
…		…
1126		1130
1127	ev_io w;	1131	ev_io w;
1128	ev_init (&w, my_cb);	1132	ev_init (&w, my_cb);
1129	ev_io_set (&w, STDIN_FILENO, EV_READ);	1133	ev_io_set (&w, STDIN_FILENO, EV_READ);
1130		1134
1131	=item C<ev_TYPE_set> (ev_TYPE *, [args])	1135	=item C<ev_TYPE_set> (ev_TYPE *watcher, [args])
1132		1136
1133	This macro initialises the type-specific parts of a watcher. You need to	1137	This macro initialises the type-specific parts of a watcher. You need to
1134	call C<ev_init> at least once before you call this macro, but you can	1138	call C<ev_init> at least once before you call this macro, but you can
1135	call C<ev_TYPE_set> any number of times. You must not, however, call this	1139	call C<ev_TYPE_set> any number of times. You must not, however, call this
1136	macro on a watcher that is active (it can be pending, however, which is a	1140	macro on a watcher that is active (it can be pending, however, which is a
…		…
1149		1153
1150	Example: Initialise and set an C<ev_io> watcher in one step.	1154	Example: Initialise and set an C<ev_io> watcher in one step.
1151		1155
1152	ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ);	1156	ev_io_init (&w, my_cb, STDIN_FILENO, EV_READ);
1153		1157
1154	=item C<ev_TYPE_start> (loop , ev_TYPE watcher)	1158	=item C<ev_TYPE_start> (loop, ev_TYPE *watcher)
1155		1159
1156	Starts (activates) the given watcher. Only active watchers will receive	1160	Starts (activates) the given watcher. Only active watchers will receive
1157	events. If the watcher is already active nothing will happen.	1161	events. If the watcher is already active nothing will happen.
1158		1162
1159	Example: Start the C<ev_io> watcher that is being abused as example in this	1163	Example: Start the C<ev_io> watcher that is being abused as example in this
1160	whole section.	1164	whole section.
1161		1165
1162	ev_io_start (EV_DEFAULT_UC, &w);	1166	ev_io_start (EV_DEFAULT_UC, &w);
1163		1167
1164	=item C<ev_TYPE_stop> (loop , ev_TYPE watcher)	1168	=item C<ev_TYPE_stop> (loop, ev_TYPE *watcher)
1165		1169
1166	Stops the given watcher if active, and clears the pending status (whether	1170	Stops the given watcher if active, and clears the pending status (whether
1167	the watcher was active or not).	1171	the watcher was active or not).
1168		1172
1169	It is possible that stopped watchers are pending - for example,	1173	It is possible that stopped watchers are pending - for example,
…		…
1194	=item ev_cb_set (ev_TYPE *watcher, callback)	1198	=item ev_cb_set (ev_TYPE *watcher, callback)
1195		1199
1196	Change the callback. You can change the callback at virtually any time	1200	Change the callback. You can change the callback at virtually any time
1197	(modulo threads).	1201	(modulo threads).
1198		1202
1199	=item ev_set_priority (ev_TYPE *watcher, priority)	1203	=item ev_set_priority (ev_TYPE *watcher, int priority)
1200		1204
1201	=item int ev_priority (ev_TYPE *watcher)	1205	=item int ev_priority (ev_TYPE *watcher)
1202		1206
1203	Set and query the priority of the watcher. The priority is a small	1207	Set and query the priority of the watcher. The priority is a small
1204	integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI>	1208	integer between C<EV_MAXPRI> (default: C<2>) and C<EV_MINPRI>
…		…
1236	watcher isn't pending it does nothing and returns C<0>.	1240	watcher isn't pending it does nothing and returns C<0>.
1237		1241
1238	Sometimes it can be useful to "poll" a watcher instead of waiting for its	1242	Sometimes it can be useful to "poll" a watcher instead of waiting for its
1239	callback to be invoked, which can be accomplished with this function.	1243	callback to be invoked, which can be accomplished with this function.
1240		1244
1241	=item ev_feed_event (struct ev_loop , watcher , int revents)	1245	=item ev_feed_event (loop, ev_TYPE *watcher, int revents)
1242		1246
1243	Feeds the given event set into the event loop, as if the specified event	1247	Feeds the given event set into the event loop, as if the specified event
1244	had happened for the specified watcher (which must be a pointer to an	1248	had happened for the specified watcher (which must be a pointer to an
1245	initialised but not necessarily started event watcher). Obviously you must	1249	initialised but not necessarily started event watcher). Obviously you must
1246	not free the watcher as long as it has pending events.	1250	not free the watcher as long as it has pending events.
…		…
1854	C<repeat> value), or reset the running timer to the C<repeat> value.	1858	C<repeat> value), or reset the running timer to the C<repeat> value.
1855		1859
1856	This sounds a bit complicated, see L<Be smart about timeouts>, above, for a	1860	This sounds a bit complicated, see L<Be smart about timeouts>, above, for a
1857	usage example.	1861	usage example.
1858		1862
1859	=item ev_timer_remaining (loop, ev_timer *)	1863	=item ev_tstamp ev_timer_remaining (loop, ev_timer *)
1860		1864
1861	Returns the remaining time until a timer fires. If the timer is active,	1865	Returns the remaining time until a timer fires. If the timer is active,
1862	then this time is relative to the current event loop time, otherwise it's	1866	then this time is relative to the current event loop time, otherwise it's
1863	the timeout value currently configured.	1867	the timeout value currently configured.
1864		1868
…		…
2131	C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should	2135	C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should
2132	not be unduly interrupted. If you have a problem with system calls getting	2136	not be unduly interrupted. If you have a problem with system calls getting
2133	interrupted by signals you can block all signals in an C<ev_check> watcher	2137	interrupted by signals you can block all signals in an C<ev_check> watcher
2134	and unblock them in an C<ev_prepare> watcher.	2138	and unblock them in an C<ev_prepare> watcher.
2135		2139
2136	=head3 The special problem of inheritance over execve	2140	=head3 The special problem of inheritance over fork/execve/pthread_create
2137		2141
2138	Both the signal mask (C<sigprocmask>) and the signal disposition	2142	Both the signal mask (C<sigprocmask>) and the signal disposition
2139	(C<sigaction>) are unspecified after starting a signal watcher (and after	2143	(C<sigaction>) are unspecified after starting a signal watcher (and after
2140	stopping it again), that is, libev might or might not block the signal,	2144	stopping it again), that is, libev might or might not block the signal,
2141	and might or might not set or restore the installed signal handler.	2145	and might or might not set or restore the installed signal handler.
…		…
2151		2155
2152	The simplest way to ensure that the signal mask is reset in the child is	2156	The simplest way to ensure that the signal mask is reset in the child is
2153	to install a fork handler with C<pthread_atfork> that resets it. That will	2157	to install a fork handler with C<pthread_atfork> that resets it. That will
2154	catch fork calls done by libraries (such as the libc) as well.	2158	catch fork calls done by libraries (such as the libc) as well.
2155		2159
2156	In current versions of libev, you can also ensure that the signal mask is	2160	In current versions of libev, the signal will not be blocked indefinitely
2157	not blocking any signals (except temporarily, so thread users watch out)	2161	unless you use the C<signalfd> API (C<EV_SIGNALFD>). While this reduces
2158	by specifying the C<EVFLAG_NOSIGFD> when creating the event loop. This	2162	the window of opportunity for problems, it will not go away, as libev
2159	is not guaranteed for future versions, however.	2163	I<has> to modify the signal mask, at least temporarily.
		2164
		2165	So I can't stress this enough I<if you do not reset your signal mask
		2166	when you expect it to be empty, you have a race condition in your
		2167	program>. This is not a libev-specific thing, this is true for most event
		2168	libraries.
2160		2169
2161	=head3 Watcher-Specific Functions and Data Members	2170	=head3 Watcher-Specific Functions and Data Members
2162		2171
2163	=over 4	2172	=over 4
2164		2173
…		…
2981	=head3 Queueing	2990	=head3 Queueing
2982		2991
2983	C<ev_async> does not support queueing of data in any way. The reason	2992	C<ev_async> does not support queueing of data in any way. The reason
2984	is that the author does not know of a simple (or any) algorithm for a	2993	is that the author does not know of a simple (or any) algorithm for a
2985	multiple-writer-single-reader queue that works in all cases and doesn't	2994	multiple-writer-single-reader queue that works in all cases and doesn't
2986	need elaborate support such as pthreads.	2995	need elaborate support such as pthreads or unportable memory access
		2996	semantics.
2987		2997
2988	That means that if you want to queue data, you have to provide your own	2998	That means that if you want to queue data, you have to provide your own
2989	queue. But at least I can tell you how to implement locking around your	2999	queue. But at least I can tell you how to implement locking around your
2990	queue:	3000	queue:
2991		3001
…		…
3149	/* doh, nothing entered */;	3159	/* doh, nothing entered */;
3150	}	3160	}
3151		3161
3152	ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);	3162	ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
3153		3163
3154	=item ev_feed_fd_event (struct ev_loop *, int fd, int revents)	3164	=item ev_feed_fd_event (loop, int fd, int revents)
3155		3165
3156	Feed an event on the given fd, as if a file descriptor backend detected	3166	Feed an event on the given fd, as if a file descriptor backend detected
3157	the given events it.	3167	the given events it.
3158		3168
3159	=item ev_feed_signal_event (struct ev_loop *loop, int signum)	3169	=item ev_feed_signal_event (loop, int signum)
3160		3170
3161	Feed an event as if the given signal occurred (C<loop> must be the default	3171	Feed an event as if the given signal occurred (C<loop> must be the default
3162	loop!).	3172	loop!).
3163		3173
3164	=back	3174	=back
…		…
3244		3254
3245	=over 4	3255	=over 4
3246		3256
3247	=item ev::TYPE::TYPE ()	3257	=item ev::TYPE::TYPE ()
3248		3258
3249	=item ev::TYPE::TYPE (struct ev_loop *)	3259	=item ev::TYPE::TYPE (loop)
3250		3260
3251	=item ev::TYPE::~TYPE	3261	=item ev::TYPE::~TYPE
3252		3262
3253	The constructor (optionally) takes an event loop to associate the watcher	3263	The constructor (optionally) takes an event loop to associate the watcher
3254	with. If it is omitted, it will use C<EV_DEFAULT>.	3264	with. If it is omitted, it will use C<EV_DEFAULT>.
…		…
3331	Example: Use a plain function as callback.	3341	Example: Use a plain function as callback.
3332		3342
3333	static void io_cb (ev::io &w, int revents) { }	3343	static void io_cb (ev::io &w, int revents) { }
3334	iow.set <io_cb> ();	3344	iow.set <io_cb> ();
3335		3345
3336	=item w->set (struct ev_loop *)	3346	=item w->set (loop)
3337		3347
3338	Associates a different C<struct ev_loop> with this watcher. You can only	3348	Associates a different C<struct ev_loop> with this watcher. You can only
3339	do this when the watcher is inactive (and not pending either).	3349	do this when the watcher is inactive (and not pending either).
3340		3350
3341	=item w->set ([arguments])	3351	=item w->set ([arguments])

Comparing libev/ev.pod (file contents): Revision 1.273 by root, Tue Nov 24 14:46:59 2009 UTC vs. Revision 1.277 by root, Thu Dec 31 06:50:17 2009 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.273 by root, Tue Nov 24 14:46:59 2009 UTC vs.
Revision 1.277 by root, Thu Dec 31 06:50:17 2009 UTC