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

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

…		…
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>
…		…
1235	returns its C<revents> bitset (as if its callback was invoked). If the	1239	returns its C<revents> bitset (as if its callback was invoked). If the
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.
		1244
		1245	=item ev_feed_event (loop, ev_TYPE *watcher, int revents)
		1246
		1247	Feeds the given event set into the event loop, as if the specified event
		1248	had happened for the specified watcher (which must be a pointer to an
		1249	initialised but not necessarily started event watcher). Obviously you must
		1250	not free the watcher as long as it has pending events.
		1251
		1252	Stopping the watcher, letting libev invoke it, or calling
		1253	C<ev_clear_pending> will clear the pending event, even if the watcher was
		1254	not started in the first place.
		1255
		1256	See also C<ev_feed_fd_event> and C<ev_feed_signal_event> for related
		1257	functions that do not need a watcher.
1240		1258
1241	=back	1259	=back
1242		1260
1243		1261
1244	=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER	1262	=head2 ASSOCIATING CUSTOM DATA WITH A WATCHER
…		…
1840	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.
1841		1859
1842	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
1843	usage example.	1861	usage example.
1844		1862
1845	=item ev_timer_remaining (loop, ev_timer *)	1863	=item ev_tstamp ev_timer_remaining (loop, ev_timer *)
1846		1864
1847	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,
1848	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
1849	the timeout value currently configured.	1867	the timeout value currently configured.
1850		1868
…		…
2117	C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should	2135	C<SA_RESTART> (or equivalent) behaviour enabled, so system calls should
2118	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
2119	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
2120	and unblock them in an C<ev_prepare> watcher.	2138	and unblock them in an C<ev_prepare> watcher.
2121		2139
2122	=head3 The special problem of inheritance over execve	2140	=head3 The special problem of inheritance over fork/execve/pthread_create
2123		2141
2124	Both the signal mask (C<sigprocmask>) and the signal disposition	2142	Both the signal mask (C<sigprocmask>) and the signal disposition
2125	(C<sigaction>) are unspecified after starting a signal watcher (and after	2143	(C<sigaction>) are unspecified after starting a signal watcher (and after
2126	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,
2127	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.
…		…
2137		2155
2138	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
2139	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
2140	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.
2141		2159
2142	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
2143	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
2144	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
2145	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.
2146		2169
2147	=head3 Watcher-Specific Functions and Data Members	2170	=head3 Watcher-Specific Functions and Data Members
2148		2171
2149	=over 4	2172	=over 4
2150		2173
…		…
2967	=head3 Queueing	2990	=head3 Queueing
2968		2991
2969	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
2970	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
2971	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
2972	need elaborate support such as pthreads.	2995	need elaborate support such as pthreads or unportable memory access
		2996	semantics.
2973		2997
2974	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
2975	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
2976	queue:	3000	queue:
2977		3001
…		…
3135	/* doh, nothing entered */;	3159	/* doh, nothing entered */;
3136	}	3160	}
3137		3161
3138	ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);	3162	ev_once (STDIN_FILENO, EV_READ, 10., stdin_ready, 0);
3139		3163
3140	=item ev_feed_event (struct ev_loop , watcher , int revents)
3141
3142	Feeds the given event set into the event loop, as if the specified event
3143	had happened for the specified watcher (which must be a pointer to an
3144	initialised but not necessarily started event watcher).
3145
3146	=item ev_feed_fd_event (struct ev_loop *, int fd, int revents)	3164	=item ev_feed_fd_event (loop, int fd, int revents)
3147		3165
3148	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
3149	the given events it.	3167	the given events it.
3150		3168
3151	=item ev_feed_signal_event (struct ev_loop *loop, int signum)	3169	=item ev_feed_signal_event (loop, int signum)
3152		3170
3153	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
3154	loop!).	3172	loop!).
3155		3173
3156	=back	3174	=back
…		…
3236		3254
3237	=over 4	3255	=over 4
3238		3256
3239	=item ev::TYPE::TYPE ()	3257	=item ev::TYPE::TYPE ()
3240		3258
3241	=item ev::TYPE::TYPE (struct ev_loop *)	3259	=item ev::TYPE::TYPE (loop)
3242		3260
3243	=item ev::TYPE::~TYPE	3261	=item ev::TYPE::~TYPE
3244		3262
3245	The constructor (optionally) takes an event loop to associate the watcher	3263	The constructor (optionally) takes an event loop to associate the watcher
3246	with. If it is omitted, it will use C<EV_DEFAULT>.	3264	with. If it is omitted, it will use C<EV_DEFAULT>.
…		…
3323	Example: Use a plain function as callback.	3341	Example: Use a plain function as callback.
3324		3342
3325	static void io_cb (ev::io &w, int revents) { }	3343	static void io_cb (ev::io &w, int revents) { }
3326	iow.set <io_cb> ();	3344	iow.set <io_cb> ();
3327		3345
3328	=item w->set (struct ev_loop *)	3346	=item w->set (loop)
3329		3347
3330	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
3331	do this when the watcher is inactive (and not pending either).	3349	do this when the watcher is inactive (and not pending either).
3332		3350
3333	=item w->set ([arguments])	3351	=item w->set ([arguments])

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.272 by root, Tue Nov 24 06:39:28 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.272 by root, Tue Nov 24 06:39:28 2009 UTC vs.
Revision 1.277 by root, Thu Dec 31 06:50:17 2009 UTC