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

Comparing libev/ev.html (file contents):
Revision 1.26 by root, Mon Nov 12 19:20:05 2007 UTC vs.
Revision 1.35 by root, Fri Nov 23 16:17:12 2007 UTC

…		…
4	<head>	4	<head>
5	<title>libev</title>	5	<title>libev</title>
6	<meta name="description" content="Pod documentation for libev" />	6	<meta name="description" content="Pod documentation for libev" />
7	<meta name="inputfile" content="<standard input>" />	7	<meta name="inputfile" content="<standard input>" />
8	<meta name="outputfile" content="<standard output>" />	8	<meta name="outputfile" content="<standard output>" />
9	<meta name="created" content="Mon Nov 12 20:19:59 2007" />	9	<meta name="created" content="Fri Nov 23 17:17:04 2007" />
10	<meta name="generator" content="Pod::Xhtml 1.57" />	10	<meta name="generator" content="Pod::Xhtml 1.57" />
11	<link rel="stylesheet" href="http://res.tst.eu/pod.css"/></head>	11	<link rel="stylesheet" href="http://res.tst.eu/pod.css"/></head>
12	<body>	12	<body>
13	<div class="pod">	13	<div class="pod">
14	<!-- INDEX START -->	14	<!-- INDEX START -->
…		…
96	<div id="TIME_REPRESENTATION_CONTENT">	96	<div id="TIME_REPRESENTATION_CONTENT">
97	<p>Libev represents time as a single floating point number, representing the	97	<p>Libev represents time as a single floating point number, representing the
98	(fractional) number of seconds since the (POSIX) epoch (somewhere near	98	(fractional) number of seconds since the (POSIX) epoch (somewhere near
99	the beginning of 1970, details are complicated, don't ask). This type is	99	the beginning of 1970, details are complicated, don't ask). This type is
100	called <code>ev_tstamp</code>, which is what you should use too. It usually aliases	100	called <code>ev_tstamp</code>, which is what you should use too. It usually aliases
101	to the double type in C.</p>	101	to the <code>double</code> type in C, and when you need to do any calculations on
		102	it, you should treat it as such.</p>
		103
		104
		105
		106
102		107
103	</div>	108	</div>
104	<h1 id="GLOBAL_FUNCTIONS">GLOBAL FUNCTIONS</h1><p><a href="#TOP" class="toplink">Top</a></p>	109	<h1 id="GLOBAL_FUNCTIONS">GLOBAL FUNCTIONS</h1><p><a href="#TOP" class="toplink">Top</a></p>
105	<div id="GLOBAL_FUNCTIONS_CONTENT">	110	<div id="GLOBAL_FUNCTIONS_CONTENT">
106	<p>These functions can be called anytime, even before initialising the	111	<p>These functions can be called anytime, even before initialising the
107	library in any way.</p>	112	library in any way.</p>
108	<dl>	113	<dl>
109	<dt>ev_tstamp ev_time ()</dt>	114	<dt>ev_tstamp ev_time ()</dt>
110	<dd>	115	<dd>
111	<p>Returns the current time as libev would use it.</p>	116	<p>Returns the current time as libev would use it. Please note that the
		117	<code>ev_now</code> function is usually faster and also often returns the timestamp
		118	you actually want to know.</p>
112	</dd>	119	</dd>
113	<dt>int ev_version_major ()</dt>	120	<dt>int ev_version_major ()</dt>
114	<dt>int ev_version_minor ()</dt>	121	<dt>int ev_version_minor ()</dt>
115	<dd>	122	<dd>
116	<p>You can find out the major and minor version numbers of the library	123	<p>You can find out the major and minor version numbers of the library
…		…
120	version of the library your program was compiled against.</p>	127	version of the library your program was compiled against.</p>
121	<p>Usually, it's a good idea to terminate if the major versions mismatch,	128	<p>Usually, it's a good idea to terminate if the major versions mismatch,
122	as this indicates an incompatible change. Minor versions are usually	129	as this indicates an incompatible change. Minor versions are usually
123	compatible to older versions, so a larger minor version alone is usually	130	compatible to older versions, so a larger minor version alone is usually
124	not a problem.</p>	131	not a problem.</p>
		132	<p>Example: make sure we haven't accidentally been linked against the wrong
		133	version:</p>
		134	<pre> assert (("libev version mismatch",
		135	ev_version_major () == EV_VERSION_MAJOR
		136	&& ev_version_minor () >= EV_VERSION_MINOR));
		137
		138	</pre>
		139	</dd>
		140	<dt>unsigned int ev_supported_backends ()</dt>
		141	<dd>
		142	<p>Return the set of all backends (i.e. their corresponding <code>EV_BACKEND_*</code>
		143	value) compiled into this binary of libev (independent of their
		144	availability on the system you are running on). See <code>ev_default_loop</code> for
		145	a description of the set values.</p>
		146	<p>Example: make sure we have the epoll method, because yeah this is cool and
		147	a must have and can we have a torrent of it please!!!11</p>
		148	<pre> assert (("sorry, no epoll, no sex",
		149	ev_supported_backends () & EVBACKEND_EPOLL));
		150
		151	</pre>
		152	</dd>
		153	<dt>unsigned int ev_recommended_backends ()</dt>
		154	<dd>
		155	<p>Return the set of all backends compiled into this binary of libev and also
		156	recommended for this platform. This set is often smaller than the one
		157	returned by <code>ev_supported_backends</code>, as for example kqueue is broken on
		158	most BSDs and will not be autodetected unless you explicitly request it
		159	(assuming you know what you are doing). This is the set of backends that
		160	libev will probe for if you specify no backends explicitly.</p>
125	</dd>	161	</dd>
126	<dt>ev_set_allocator (void (cb)(void *ptr, long size))</dt>	162	<dt>ev_set_allocator (void (cb)(void *ptr, long size))</dt>
127	<dd>	163	<dd>
128	<p>Sets the allocation function to use (the prototype is similar to the	164	<p>Sets the allocation function to use (the prototype is similar to the
129	realloc C function, the semantics are identical). It is used to allocate	165	realloc C function, the semantics are identical). It is used to allocate
…		…
131	needs to be allocated, the library might abort or take some potentially	167	needs to be allocated, the library might abort or take some potentially
132	destructive action. The default is your system realloc function.</p>	168	destructive action. The default is your system realloc function.</p>
133	<p>You could override this function in high-availability programs to, say,	169	<p>You could override this function in high-availability programs to, say,
134	free some memory if it cannot allocate memory, to use a special allocator,	170	free some memory if it cannot allocate memory, to use a special allocator,
135	or even to sleep a while and retry until some memory is available.</p>	171	or even to sleep a while and retry until some memory is available.</p>
		172	<p>Example: replace the libev allocator with one that waits a bit and then
		173	retries: better than mine).</p>
		174	<pre> static void *
		175	persistent_realloc (void *ptr, long size)
		176	{
		177	for (;;)
		178	{
		179	void *newptr = realloc (ptr, size);
		180
		181	if (newptr)
		182	return newptr;
		183
		184	sleep (60);
		185	}
		186	}
		187
		188	...
		189	ev_set_allocator (persistent_realloc);
		190
		191	</pre>
136	</dd>	192	</dd>
137	<dt>ev_set_syserr_cb (void (cb)(const char msg));</dt>	193	<dt>ev_set_syserr_cb (void (cb)(const char msg));</dt>
138	<dd>	194	<dd>
139	<p>Set the callback function to call on a retryable syscall error (such	195	<p>Set the callback function to call on a retryable syscall error (such
140	as failed select, poll, epoll_wait). The message is a printable string	196	as failed select, poll, epoll_wait). The message is a printable string
141	indicating the system call or subsystem causing the problem. If this	197	indicating the system call or subsystem causing the problem. If this
142	callback is set, then libev will expect it to remedy the sitution, no	198	callback is set, then libev will expect it to remedy the sitution, no
143	matter what, when it returns. That is, libev will generally retry the	199	matter what, when it returns. That is, libev will generally retry the
144	requested operation, or, if the condition doesn't go away, do bad stuff	200	requested operation, or, if the condition doesn't go away, do bad stuff
145	(such as abort).</p>	201	(such as abort).</p>
		202	<p>Example: do the same thing as libev does internally:</p>
		203	<pre> static void
		204	fatal_error (const char *msg)
		205	{
		206	perror (msg);
		207	abort ();
		208	}
		209
		210	...
		211	ev_set_syserr_cb (fatal_error);
		212
		213	</pre>
146	</dd>	214	</dd>
147	</dl>	215	</dl>
148		216
149	</div>	217	</div>
150	<h1 id="FUNCTIONS_CONTROLLING_THE_EVENT_LOOP">FUNCTIONS CONTROLLING THE EVENT LOOP</h1><p><a href="#TOP" class="toplink">Top</a></p>	218	<h1 id="FUNCTIONS_CONTROLLING_THE_EVENT_LOOP">FUNCTIONS CONTROLLING THE EVENT LOOP</h1><p><a href="#TOP" class="toplink">Top</a></p>
…		…
162	<dt>struct ev_loop *ev_default_loop (unsigned int flags)</dt>	230	<dt>struct ev_loop *ev_default_loop (unsigned int flags)</dt>
163	<dd>	231	<dd>
164	<p>This will initialise the default event loop if it hasn't been initialised	232	<p>This will initialise the default event loop if it hasn't been initialised
165	yet and return it. If the default loop could not be initialised, returns	233	yet and return it. If the default loop could not be initialised, returns
166	false. If it already was initialised it simply returns it (and ignores the	234	false. If it already was initialised it simply returns it (and ignores the
167	flags).</p>	235	flags. If that is troubling you, check <code>ev_backend ()</code> afterwards).</p>
168	<p>If you don't know what event loop to use, use the one returned from this	236	<p>If you don't know what event loop to use, use the one returned from this
169	function.</p>	237	function.</p>
170	<p>The flags argument can be used to specify special behaviour or specific	238	<p>The flags argument can be used to specify special behaviour or specific
171	backends to use, and is usually specified as 0 (or EVFLAG_AUTO).</p>	239	backends to use, and is usually specified as <code>0</code> (or <code>EVFLAG_AUTO</code>).</p>
172	<p>It supports the following flags:</p>	240	<p>The following flags are supported:</p>
173	<p>	241	<p>
174	<dl>	242	<dl>
175	<dt><code>EVFLAG_AUTO</code></dt>	243	<dt><code>EVFLAG_AUTO</code></dt>
176	<dd>	244	<dd>
177	<p>The default flags value. Use this if you have no clue (it's the right	245	<p>The default flags value. Use this if you have no clue (it's the right
…		…
184	<code>LIBEV_FLAGS</code>. Otherwise (the default), this environment variable will	252	<code>LIBEV_FLAGS</code>. Otherwise (the default), this environment variable will
185	override the flags completely if it is found in the environment. This is	253	override the flags completely if it is found in the environment. This is
186	useful to try out specific backends to test their performance, or to work	254	useful to try out specific backends to test their performance, or to work
187	around bugs.</p>	255	around bugs.</p>
188	</dd>	256	</dd>
189	<dt><code>EVMETHOD_SELECT</code> (portable select backend)</dt>	257	<dt><code>EVBACKEND_SELECT</code> (value 1, portable select backend)</dt>
190	<dt><code>EVMETHOD_POLL</code> (poll backend, available everywhere except on windows)</dt>
191	<dt><code>EVMETHOD_EPOLL</code> (linux only)</dt>
192	<dt><code>EVMETHOD_KQUEUE</code> (some bsds only)</dt>
193	<dt><code>EVMETHOD_DEVPOLL</code> (solaris 8 only)</dt>
194	<dt><code>EVMETHOD_PORT</code> (solaris 10 only)</dt>
195	<dd>	258	<dd>
196	<p>If one or more of these are ored into the flags value, then only these	259	<p>This is your standard select(2) backend. Not <i>completely</i> standard, as
197	backends will be tried (in the reverse order as given here). If one are	260	libev tries to roll its own fd_set with no limits on the number of fds,
198	specified, any backend will do.</p>	261	but if that fails, expect a fairly low limit on the number of fds when
		262	using this backend. It doesn't scale too well (O(highest_fd)), but its usually
		263	the fastest backend for a low number of fds.</p>
		264	</dd>
		265	<dt><code>EVBACKEND_POLL</code> (value 2, poll backend, available everywhere except on windows)</dt>
		266	<dd>
		267	<p>And this is your standard poll(2) backend. It's more complicated than
		268	select, but handles sparse fds better and has no artificial limit on the
		269	number of fds you can use (except it will slow down considerably with a
		270	lot of inactive fds). It scales similarly to select, i.e. O(total_fds).</p>
		271	</dd>
		272	<dt><code>EVBACKEND_EPOLL</code> (value 4, Linux)</dt>
		273	<dd>
		274	<p>For few fds, this backend is a bit little slower than poll and select,
		275	but it scales phenomenally better. While poll and select usually scale like
		276	O(total_fds) where n is the total number of fds (or the highest fd), epoll scales
		277	either O(1) or O(active_fds).</p>
		278	<p>While stopping and starting an I/O watcher in the same iteration will
		279	result in some caching, there is still a syscall per such incident
		280	(because the fd could point to a different file description now), so its
		281	best to avoid that. Also, dup()ed file descriptors might not work very
		282	well if you register events for both fds.</p>
		283	<p>Please note that epoll sometimes generates spurious notifications, so you
		284	need to use non-blocking I/O or other means to avoid blocking when no data
		285	(or space) is available.</p>
		286	</dd>
		287	<dt><code>EVBACKEND_KQUEUE</code> (value 8, most BSD clones)</dt>
		288	<dd>
		289	<p>Kqueue deserves special mention, as at the time of this writing, it
		290	was broken on all BSDs except NetBSD (usually it doesn't work with
		291	anything but sockets and pipes, except on Darwin, where of course its
		292	completely useless). For this reason its not being "autodetected"
		293	unless you explicitly specify it explicitly in the flags (i.e. using
		294	<code>EVBACKEND_KQUEUE</code>).</p>
		295	<p>It scales in the same way as the epoll backend, but the interface to the
		296	kernel is more efficient (which says nothing about its actual speed, of
		297	course). While starting and stopping an I/O watcher does not cause an
		298	extra syscall as with epoll, it still adds up to four event changes per
		299	incident, so its best to avoid that.</p>
		300	</dd>
		301	<dt><code>EVBACKEND_DEVPOLL</code> (value 16, Solaris 8)</dt>
		302	<dd>
		303	<p>This is not implemented yet (and might never be).</p>
		304	</dd>
		305	<dt><code>EVBACKEND_PORT</code> (value 32, Solaris 10)</dt>
		306	<dd>
		307	<p>This uses the Solaris 10 port mechanism. As with everything on Solaris,
		308	it's really slow, but it still scales very well (O(active_fds)).</p>
		309	<p>Please note that solaris ports can result in a lot of spurious
		310	notifications, so you need to use non-blocking I/O or other means to avoid
		311	blocking when no data (or space) is available.</p>
		312	</dd>
		313	<dt><code>EVBACKEND_ALL</code></dt>
		314	<dd>
		315	<p>Try all backends (even potentially broken ones that wouldn't be tried
		316	with <code>EVFLAG_AUTO</code>). Since this is a mask, you can do stuff such as
		317	<code>EVBACKEND_ALL & ~EVBACKEND_KQUEUE</code>.</p>
199	</dd>	318	</dd>
200	</dl>	319	</dl>
201	</p>	320	</p>
		321	<p>If one or more of these are ored into the flags value, then only these
		322	backends will be tried (in the reverse order as given here). If none are
		323	specified, most compiled-in backend will be tried, usually in reverse
		324	order of their flag values :)</p>
		325	<p>The most typical usage is like this:</p>
		326	<pre> if (!ev_default_loop (0))
		327	fatal ("could not initialise libev, bad $LIBEV_FLAGS in environment?");
		328
		329	</pre>
		330	<p>Restrict libev to the select and poll backends, and do not allow
		331	environment settings to be taken into account:</p>
		332	<pre> ev_default_loop (EVBACKEND_POLL \| EVBACKEND_SELECT \| EVFLAG_NOENV);
		333
		334	</pre>
		335	<p>Use whatever libev has to offer, but make sure that kqueue is used if
		336	available (warning, breaks stuff, best use only with your own private
		337	event loop and only if you know the OS supports your types of fds):</p>
		338	<pre> ev_default_loop (ev_recommended_backends () \| EVBACKEND_KQUEUE);
		339
		340	</pre>
202	</dd>	341	</dd>
203	<dt>struct ev_loop *ev_loop_new (unsigned int flags)</dt>	342	<dt>struct ev_loop *ev_loop_new (unsigned int flags)</dt>
204	<dd>	343	<dd>
205	<p>Similar to <code>ev_default_loop</code>, but always creates a new event loop that is	344	<p>Similar to <code>ev_default_loop</code>, but always creates a new event loop that is
206	always distinct from the default loop. Unlike the default loop, it cannot	345	always distinct from the default loop. Unlike the default loop, it cannot
207	handle signal and child watchers, and attempts to do so will be greeted by	346	handle signal and child watchers, and attempts to do so will be greeted by
208	undefined behaviour (or a failed assertion if assertions are enabled).</p>	347	undefined behaviour (or a failed assertion if assertions are enabled).</p>
		348	<p>Example: try to create a event loop that uses epoll and nothing else.</p>
		349	<pre> struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL \| EVFLAG_NOENV);
		350	if (!epoller)
		351	fatal ("no epoll found here, maybe it hides under your chair");
		352
		353	</pre>
209	</dd>	354	</dd>
210	<dt>ev_default_destroy ()</dt>	355	<dt>ev_default_destroy ()</dt>
211	<dd>	356	<dd>
212	<p>Destroys the default loop again (frees all memory and kernel state	357	<p>Destroys the default loop again (frees all memory and kernel state
213	etc.). This stops all registered event watchers (by not touching them in	358	etc.). This stops all registered event watchers (by not touching them in
…		…
222	<dd>	367	<dd>
223	<p>This function reinitialises the kernel state for backends that have	368	<p>This function reinitialises the kernel state for backends that have
224	one. Despite the name, you can call it anytime, but it makes most sense	369	one. Despite the name, you can call it anytime, but it makes most sense
225	after forking, in either the parent or child process (or both, but that	370	after forking, in either the parent or child process (or both, but that
226	again makes little sense).</p>	371	again makes little sense).</p>
227	<p>You <i>must</i> call this function after forking if and only if you want to	372	<p>You <i>must</i> call this function in the child process after forking if and
228	use the event library in both processes. If you just fork+exec, you don't	373	only if you want to use the event library in both processes. If you just
229	have to call it.</p>	374	fork+exec, you don't have to call it.</p>
230	<p>The function itself is quite fast and it's usually not a problem to call	375	<p>The function itself is quite fast and it's usually not a problem to call
231	it just in case after a fork. To make this easy, the function will fit in	376	it just in case after a fork. To make this easy, the function will fit in
232	quite nicely into a call to <code>pthread_atfork</code>:</p>	377	quite nicely into a call to <code>pthread_atfork</code>:</p>
233	<pre> pthread_atfork (0, 0, ev_default_fork);	378	<pre> pthread_atfork (0, 0, ev_default_fork);
234		379
235	</pre>	380	</pre>
		381	<p>At the moment, <code>EVBACKEND_SELECT</code> and <code>EVBACKEND_POLL</code> are safe to use
		382	without calling this function, so if you force one of those backends you
		383	do not need to care.</p>
236	</dd>	384	</dd>
237	<dt>ev_loop_fork (loop)</dt>	385	<dt>ev_loop_fork (loop)</dt>
238	<dd>	386	<dd>
239	<p>Like <code>ev_default_fork</code>, but acts on an event loop created by	387	<p>Like <code>ev_default_fork</code>, but acts on an event loop created by
240	<code>ev_loop_new</code>. Yes, you have to call this on every allocated event loop	388	<code>ev_loop_new</code>. Yes, you have to call this on every allocated event loop
241	after fork, and how you do this is entirely your own problem.</p>	389	after fork, and how you do this is entirely your own problem.</p>
242	</dd>	390	</dd>
243	<dt>unsigned int ev_method (loop)</dt>	391	<dt>unsigned int ev_backend (loop)</dt>
244	<dd>	392	<dd>
245	<p>Returns one of the <code>EVMETHOD_*</code> flags indicating the event backend in	393	<p>Returns one of the <code>EVBACKEND_*</code> flags indicating the event backend in
246	use.</p>	394	use.</p>
247	</dd>	395	</dd>
248	<dt>ev_tstamp ev_now (loop)</dt>	396	<dt>ev_tstamp ev_now (loop)</dt>
249	<dd>	397	<dd>
250	<p>Returns the current "event loop time", which is the time the event loop	398	<p>Returns the current "event loop time", which is the time the event loop
251	got events and started processing them. This timestamp does not change	399	received events and started processing them. This timestamp does not
252	as long as callbacks are being processed, and this is also the base time	400	change as long as callbacks are being processed, and this is also the base
253	used for relative timers. You can treat it as the timestamp of the event	401	time used for relative timers. You can treat it as the timestamp of the
254	occuring (or more correctly, the mainloop finding out about it).</p>	402	event occuring (or more correctly, libev finding out about it).</p>
255	</dd>	403	</dd>
256	<dt>ev_loop (loop, int flags)</dt>	404	<dt>ev_loop (loop, int flags)</dt>
257	<dd>	405	<dd>
258	<p>Finally, this is it, the event handler. This function usually is called	406	<p>Finally, this is it, the event handler. This function usually is called
259	after you initialised all your watchers and you want to start handling	407	after you initialised all your watchers and you want to start handling
260	events.</p>	408	events.</p>
261	<p>If the flags argument is specified as 0, it will not return until either	409	<p>If the flags argument is specified as <code>0</code>, it will not return until
262	no event watchers are active anymore or <code>ev_unloop</code> was called.</p>	410	either no event watchers are active anymore or <code>ev_unloop</code> was called.</p>
		411	<p>Please note that an explicit <code>ev_unloop</code> is usually better than
		412	relying on all watchers to be stopped when deciding when a program has
		413	finished (especially in interactive programs), but having a program that
		414	automatically loops as long as it has to and no longer by virtue of
		415	relying on its watchers stopping correctly is a thing of beauty.</p>
263	<p>A flags value of <code>EVLOOP_NONBLOCK</code> will look for new events, will handle	416	<p>A flags value of <code>EVLOOP_NONBLOCK</code> will look for new events, will handle
264	those events and any outstanding ones, but will not block your process in	417	those events and any outstanding ones, but will not block your process in
265	case there are no events and will return after one iteration of the loop.</p>	418	case there are no events and will return after one iteration of the loop.</p>
266	<p>A flags value of <code>EVLOOP_ONESHOT</code> will look for new events (waiting if	419	<p>A flags value of <code>EVLOOP_ONESHOT</code> will look for new events (waiting if
267	neccessary) and will handle those and any outstanding ones. It will block	420	neccessary) and will handle those and any outstanding ones. It will block
268	your process until at least one new event arrives, and will return after	421	your process until at least one new event arrives, and will return after
269	one iteration of the loop.</p>	422	one iteration of the loop. This is useful if you are waiting for some
270	<p>This flags value could be used to implement alternative looping	423	external event in conjunction with something not expressible using other
271	constructs, but the <code>prepare</code> and <code>check</code> watchers provide a better and	424	libev watchers. However, a pair of <code>ev_prepare</code>/<code>ev_check</code> watchers is
272	more generic mechanism.</p>	425	usually a better approach for this kind of thing.</p>
		426	<p>Here are the gory details of what <code>ev_loop</code> does:</p>
		427	<pre> * If there are no active watchers (reference count is zero), return.
		428	- Queue prepare watchers and then call all outstanding watchers.
		429	- If we have been forked, recreate the kernel state.
		430	- Update the kernel state with all outstanding changes.
		431	- Update the "event loop time".
		432	- Calculate for how long to block.
		433	- Block the process, waiting for any events.
		434	- Queue all outstanding I/O (fd) events.
		435	- Update the "event loop time" and do time jump handling.
		436	- Queue all outstanding timers.
		437	- Queue all outstanding periodics.
		438	- If no events are pending now, queue all idle watchers.
		439	- Queue all check watchers.
		440	- Call all queued watchers in reverse order (i.e. check watchers first).
		441	Signals and child watchers are implemented as I/O watchers, and will
		442	be handled here by queueing them when their watcher gets executed.
		443	- If ev_unloop has been called or EVLOOP_ONESHOT or EVLOOP_NONBLOCK
		444	were used, return, otherwise continue with step *.
		445
		446	</pre>
		447	<p>Example: queue some jobs and then loop until no events are outsanding
		448	anymore.</p>
		449	<pre> ... queue jobs here, make sure they register event watchers as long
		450	... as they still have work to do (even an idle watcher will do..)
		451	ev_loop (my_loop, 0);
		452	... jobs done. yeah!
		453
		454	</pre>
273	</dd>	455	</dd>
274	<dt>ev_unloop (loop, how)</dt>	456	<dt>ev_unloop (loop, how)</dt>
275	<dd>	457	<dd>
276	<p>Can be used to make a call to <code>ev_loop</code> return early (but only after it	458	<p>Can be used to make a call to <code>ev_loop</code> return early (but only after it
277	has processed all outstanding events). The <code>how</code> argument must be either	459	has processed all outstanding events). The <code>how</code> argument must be either
278	<code>EVUNLOOP_ONCE</code>, which will make the innermost <code>ev_loop</code> call return, or	460	<code>EVUNLOOP_ONE</code>, which will make the innermost <code>ev_loop</code> call return, or
279	<code>EVUNLOOP_ALL</code>, which will make all nested <code>ev_loop</code> calls return.</p>	461	<code>EVUNLOOP_ALL</code>, which will make all nested <code>ev_loop</code> calls return.</p>
280	</dd>	462	</dd>
281	<dt>ev_ref (loop)</dt>	463	<dt>ev_ref (loop)</dt>
282	<dt>ev_unref (loop)</dt>	464	<dt>ev_unref (loop)</dt>
283	<dd>	465	<dd>
…		…
289	example, libev itself uses this for its internal signal pipe: It is not	471	example, libev itself uses this for its internal signal pipe: It is not
290	visible to the libev user and should not keep <code>ev_loop</code> from exiting if	472	visible to the libev user and should not keep <code>ev_loop</code> from exiting if
291	no event watchers registered by it are active. It is also an excellent	473	no event watchers registered by it are active. It is also an excellent
292	way to do this for generic recurring timers or from within third-party	474	way to do this for generic recurring timers or from within third-party
293	libraries. Just remember to <i>unref after start</i> and <i>ref before stop</i>.</p>	475	libraries. Just remember to <i>unref after start</i> and <i>ref before stop</i>.</p>
		476	<p>Example: create a signal watcher, but keep it from keeping <code>ev_loop</code>
		477	running when nothing else is active.</p>
		478	<pre> struct dv_signal exitsig;
		479	ev_signal_init (&exitsig, sig_cb, SIGINT);
		480	ev_signal_start (myloop, &exitsig);
		481	evf_unref (myloop);
		482
		483	</pre>
		484	<p>Example: for some weird reason, unregister the above signal handler again.</p>
		485	<pre> ev_ref (myloop);
		486	ev_signal_stop (myloop, &exitsig);
		487
		488	</pre>
294	</dd>	489	</dd>
295	</dl>	490	</dl>
296		491
297	</div>	492	</div>
298	<h1 id="ANATOMY_OF_A_WATCHER">ANATOMY OF A WATCHER</h1><p><a href="#TOP" class="toplink">Top</a></p>	493	<h1 id="ANATOMY_OF_A_WATCHER">ANATOMY OF A WATCHER</h1><p><a href="#TOP" class="toplink">Top</a></p>
…		…
330	with a watcher-specific start function (<code>ev_<type>_start (loop, watcher	525	with a watcher-specific start function (<code>ev_<type>_start (loop, watcher
331	*)</code>), and you can stop watching for events at any time by calling the	526	*)</code>), and you can stop watching for events at any time by calling the
332	corresponding stop function (<code>ev_<type>_stop (loop, watcher *)</code>.</p>	527	corresponding stop function (<code>ev_<type>_stop (loop, watcher *)</code>.</p>
333	<p>As long as your watcher is active (has been started but not stopped) you	528	<p>As long as your watcher is active (has been started but not stopped) you
334	must not touch the values stored in it. Most specifically you must never	529	must not touch the values stored in it. Most specifically you must never
335	reinitialise it or call its set method.</p>	530	reinitialise it or call its set macro.</p>
336	<p>You can check whether an event is active by calling the <code>ev_is_active	531	<p>You can check whether an event is active by calling the <code>ev_is_active
337	(watcher *)</code> macro. To see whether an event is outstanding (but the	532	(watcher *)</code> macro. To see whether an event is outstanding (but the
338	callback for it has not been called yet) you can use the <code>ev_is_pending	533	callback for it has not been called yet) you can use the <code>ev_is_pending
339	(watcher *)</code> macro.</p>	534	(watcher *)</code> macro.</p>
340	<p>Each and every callback receives the event loop pointer as first, the	535	<p>Each and every callback receives the event loop pointer as first, the
…		…
433	</div>	628	</div>
434	<h1 id="WATCHER_TYPES">WATCHER TYPES</h1><p><a href="#TOP" class="toplink">Top</a></p>	629	<h1 id="WATCHER_TYPES">WATCHER TYPES</h1><p><a href="#TOP" class="toplink">Top</a></p>
435	<div id="WATCHER_TYPES_CONTENT">	630	<div id="WATCHER_TYPES_CONTENT">
436	<p>This section describes each watcher in detail, but will not repeat	631	<p>This section describes each watcher in detail, but will not repeat
437	information given in the last section.</p>	632	information given in the last section.</p>
		633
		634
		635
		636
438		637
439	</div>	638	</div>
440	<h2 id="code_ev_io_code_is_this_file_descrip"><code>ev_io</code> - is this file descriptor readable or writable</h2>	639	<h2 id="code_ev_io_code_is_this_file_descrip"><code>ev_io</code> - is this file descriptor readable or writable</h2>
441	<div id="code_ev_io_code_is_this_file_descrip-2">	640	<div id="code_ev_io_code_is_this_file_descrip-2">
442	<p>I/O watchers check whether a file descriptor is readable or writable	641	<p>I/O watchers check whether a file descriptor is readable or writable
…		…
452	(the linux epoll backend is a notable example) cannot handle dup'ed file	651	(the linux epoll backend is a notable example) cannot handle dup'ed file
453	descriptors correctly if you register interest in two or more fds pointing	652	descriptors correctly if you register interest in two or more fds pointing
454	to the same underlying file/socket etc. description (that is, they share	653	to the same underlying file/socket etc. description (that is, they share
455	the same underlying "file open").</p>	654	the same underlying "file open").</p>
456	<p>If you must do this, then force the use of a known-to-be-good backend	655	<p>If you must do this, then force the use of a known-to-be-good backend
457	(at the time of this writing, this includes only EVMETHOD_SELECT and	656	(at the time of this writing, this includes only <code>EVBACKEND_SELECT</code> and
458	EVMETHOD_POLL).</p>	657	<code>EVBACKEND_POLL</code>).</p>
459	<dl>	658	<dl>
460	<dt>ev_io_init (ev_io *, callback, int fd, int events)</dt>	659	<dt>ev_io_init (ev_io *, callback, int fd, int events)</dt>
461	<dt>ev_io_set (ev_io *, int fd, int events)</dt>	660	<dt>ev_io_set (ev_io *, int fd, int events)</dt>
462	<dd>	661	<dd>
463	<p>Configures an <code>ev_io</code> watcher. The fd is the file descriptor to rceeive	662	<p>Configures an <code>ev_io</code> watcher. The fd is the file descriptor to rceeive
464	events for and events is either <code>EV_READ</code>, <code>EV_WRITE</code> or <code>EV_READ \|	663	events for and events is either <code>EV_READ</code>, <code>EV_WRITE</code> or <code>EV_READ \|
465	EV_WRITE</code> to receive the given events.</p>	664	EV_WRITE</code> to receive the given events.</p>
		665	<p>Please note that most of the more scalable backend mechanisms (for example
		666	epoll and solaris ports) can result in spurious readyness notifications
		667	for file descriptors, so you practically need to use non-blocking I/O (and
		668	treat callback invocation as hint only), or retest separately with a safe
		669	interface before doing I/O (XLib can do this), or force the use of either
		670	<code>EVBACKEND_SELECT</code> or <code>EVBACKEND_POLL</code>, which don't suffer from this
		671	problem. Also note that it is quite easy to have your callback invoked
		672	when the readyness condition is no longer valid even when employing
		673	typical ways of handling events, so its a good idea to use non-blocking
		674	I/O unconditionally.</p>
466	</dd>	675	</dd>
467	</dl>	676	</dl>
		677	<p>Example: call <code>stdin_readable_cb</code> when STDIN_FILENO has become, well
		678	readable, but only once. Since it is likely line-buffered, you could
		679	attempt to read a whole line in the callback:</p>
		680	<pre> static void
		681	stdin_readable_cb (struct ev_loop loop, struct ev_io w, int revents)
		682	{
		683	ev_io_stop (loop, w);
		684	.. read from stdin here (or from w->fd) and haqndle any I/O errors
		685	}
		686
		687	...
		688	struct ev_loop *loop = ev_default_init (0);
		689	struct ev_io stdin_readable;
		690	ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ);
		691	ev_io_start (loop, &stdin_readable);
		692	ev_loop (loop, 0);
		693
		694
		695
		696
		697	</pre>
468		698
469	</div>	699	</div>
470	<h2 id="code_ev_timer_code_relative_and_opti"><code>ev_timer</code> - relative and optionally recurring timeouts</h2>	700	<h2 id="code_ev_timer_code_relative_and_opti"><code>ev_timer</code> - relative and optionally recurring timeouts</h2>
471	<div id="code_ev_timer_code_relative_and_opti-2">	701	<div id="code_ev_timer_code_relative_and_opti-2">
472	<p>Timer watchers are simple relative timers that generate an event after a	702	<p>Timer watchers are simple relative timers that generate an event after a
473	given time, and optionally repeating in regular intervals after that.</p>	703	given time, and optionally repeating in regular intervals after that.</p>
474	<p>The timers are based on real time, that is, if you register an event that	704	<p>The timers are based on real time, that is, if you register an event that
475	times out after an hour and you reset your system clock to last years	705	times out after an hour and you reset your system clock to last years
476	time, it will still time out after (roughly) and hour. "Roughly" because	706	time, it will still time out after (roughly) and hour. "Roughly" because
477	detecting time jumps is hard, and soem inaccuracies are unavoidable (the	707	detecting time jumps is hard, and some inaccuracies are unavoidable (the
478	monotonic clock option helps a lot here).</p>	708	monotonic clock option helps a lot here).</p>
479	<p>The relative timeouts are calculated relative to the <code>ev_now ()</code>	709	<p>The relative timeouts are calculated relative to the <code>ev_now ()</code>
480	time. This is usually the right thing as this timestamp refers to the time	710	time. This is usually the right thing as this timestamp refers to the time
481	of the event triggering whatever timeout you are modifying/starting. If	711	of the event triggering whatever timeout you are modifying/starting. If
482	you suspect event processing to be delayed and you need to base the timeout	712	you suspect event processing to be delayed and you <i>need</i> to base the timeout
483	on the current time, use something like this to adjust for this:</p>	713	on the current time, use something like this to adjust for this:</p>
484	<pre> ev_timer_set (&timer, after + ev_now () - ev_time (), 0.);	714	<pre> ev_timer_set (&timer, after + ev_now () - ev_time (), 0.);
485		715
486	</pre>	716	</pre>
		717	<p>The callback is guarenteed to be invoked only when its timeout has passed,
		718	but if multiple timers become ready during the same loop iteration then
		719	order of execution is undefined.</p>
487	<dl>	720	<dl>
488	<dt>ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)</dt>	721	<dt>ev_timer_init (ev_timer *, callback, ev_tstamp after, ev_tstamp repeat)</dt>
489	<dt>ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)</dt>	722	<dt>ev_timer_set (ev_timer *, ev_tstamp after, ev_tstamp repeat)</dt>
490	<dd>	723	<dd>
491	<p>Configure the timer to trigger after <code>after</code> seconds. If <code>repeat</code> is	724	<p>Configure the timer to trigger after <code>after</code> seconds. If <code>repeat</code> is
…		…
513	time you successfully read or write some data. If you go into an idle	746	time you successfully read or write some data. If you go into an idle
514	state where you do not expect data to travel on the socket, you can stop	747	state where you do not expect data to travel on the socket, you can stop
515	the timer, and again will automatically restart it if need be.</p>	748	the timer, and again will automatically restart it if need be.</p>
516	</dd>	749	</dd>
517	</dl>	750	</dl>
		751	<p>Example: create a timer that fires after 60 seconds.</p>
		752	<pre> static void
		753	one_minute_cb (struct ev_loop loop, struct ev_timer w, int revents)
		754	{
		755	.. one minute over, w is actually stopped right here
		756	}
		757
		758	struct ev_timer mytimer;
		759	ev_timer_init (&mytimer, one_minute_cb, 60., 0.);
		760	ev_timer_start (loop, &mytimer);
		761
		762	</pre>
		763	<p>Example: create a timeout timer that times out after 10 seconds of
		764	inactivity.</p>
		765	<pre> static void
		766	timeout_cb (struct ev_loop loop, struct ev_timer w, int revents)
		767	{
		768	.. ten seconds without any activity
		769	}
		770
		771	struct ev_timer mytimer;
		772	ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */
		773	ev_timer_again (&mytimer); /* start timer */
		774	ev_loop (loop, 0);
		775
		776	// and in some piece of code that gets executed on any "activity":
		777	// reset the timeout to start ticking again at 10 seconds
		778	ev_timer_again (&mytimer);
		779
		780
		781
		782
		783	</pre>
518		784
519	</div>	785	</div>
520	<h2 id="code_ev_periodic_code_to_cron_or_not"><code>ev_periodic</code> - to cron or not to cron</h2>	786	<h2 id="code_ev_periodic_code_to_cron_or_not"><code>ev_periodic</code> - to cron or not to cron</h2>
521	<div id="code_ev_periodic_code_to_cron_or_not-2">	787	<div id="code_ev_periodic_code_to_cron_or_not-2">
522	<p>Periodic watchers are also timers of a kind, but they are very versatile	788	<p>Periodic watchers are also timers of a kind, but they are very versatile
…		…
529	take a year to trigger the event (unlike an <code>ev_timer</code>, which would trigger	795	take a year to trigger the event (unlike an <code>ev_timer</code>, which would trigger
530	roughly 10 seconds later and of course not if you reset your system time	796	roughly 10 seconds later and of course not if you reset your system time
531	again).</p>	797	again).</p>
532	<p>They can also be used to implement vastly more complex timers, such as	798	<p>They can also be used to implement vastly more complex timers, such as
533	triggering an event on eahc midnight, local time.</p>	799	triggering an event on eahc midnight, local time.</p>
		800	<p>As with timers, the callback is guarenteed to be invoked only when the
		801	time (<code>at</code>) has been passed, but if multiple periodic timers become ready
		802	during the same loop iteration then order of execution is undefined.</p>
534	<dl>	803	<dl>
535	<dt>ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)</dt>	804	<dt>ev_periodic_init (ev_periodic *, callback, ev_tstamp at, ev_tstamp interval, reschedule_cb)</dt>
536	<dt>ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)</dt>	805	<dt>ev_periodic_set (ev_periodic *, ev_tstamp after, ev_tstamp repeat, reschedule_cb)</dt>
537	<dd>	806	<dd>
538	<p>Lots of arguments, lets sort it out... There are basically three modes of	807	<p>Lots of arguments, lets sort it out... There are basically three modes of
539	operation, and we will explain them from simplest to complex:</p>	808	operation, and we will explain them from simplest to complex:</p>
540
541
542
543
544	<p>	809	<p>
545	<dl>	810	<dl>
546	<dt>* absolute timer (interval = reschedule_cb = 0)</dt>	811	<dt>* absolute timer (interval = reschedule_cb = 0)</dt>
547	<dd>	812	<dd>
548	<p>In this configuration the watcher triggers an event at the wallclock time	813	<p>In this configuration the watcher triggers an event at the wallclock time
…		…
607	when you changed some parameters or the reschedule callback would return	872	when you changed some parameters or the reschedule callback would return
608	a different time than the last time it was called (e.g. in a crond like	873	a different time than the last time it was called (e.g. in a crond like
609	program when the crontabs have changed).</p>	874	program when the crontabs have changed).</p>
610	</dd>	875	</dd>
611	</dl>	876	</dl>
		877	<p>Example: call a callback every hour, or, more precisely, whenever the
		878	system clock is divisible by 3600. The callback invocation times have
		879	potentially a lot of jittering, but good long-term stability.</p>
		880	<pre> static void
		881	clock_cb (struct ev_loop loop, struct ev_io w, int revents)
		882	{
		883	... its now a full hour (UTC, or TAI or whatever your clock follows)
		884	}
		885
		886	struct ev_periodic hourly_tick;
		887	ev_periodic_init (&hourly_tick, clock_cb, 0., 3600., 0);
		888	ev_periodic_start (loop, &hourly_tick);
		889
		890	</pre>
		891	<p>Example: the same as above, but use a reschedule callback to do it:</p>
		892	<pre> #include <math.h>
		893
		894	static ev_tstamp
		895	my_scheduler_cb (struct ev_periodic *w, ev_tstamp now)
		896	{
		897	return fmod (now, 3600.) + 3600.;
		898	}
		899
		900	ev_periodic_init (&hourly_tick, clock_cb, 0., 0., my_scheduler_cb);
		901
		902	</pre>
		903	<p>Example: call a callback every hour, starting now:</p>
		904	<pre> struct ev_periodic hourly_tick;
		905	ev_periodic_init (&hourly_tick, clock_cb,
		906	fmod (ev_now (loop), 3600.), 3600., 0);
		907	ev_periodic_start (loop, &hourly_tick);
		908
		909
		910
		911
		912	</pre>
612		913
613	</div>	914	</div>
614	<h2 id="code_ev_signal_code_signal_me_when_a"><code>ev_signal</code> - signal me when a signal gets signalled</h2>	915	<h2 id="code_ev_signal_code_signal_me_when_a"><code>ev_signal</code> - signal me when a signal gets signalled</h2>
615	<div id="code_ev_signal_code_signal_me_when_a-2">	916	<div id="code_ev_signal_code_signal_me_when_a-2">
616	<p>Signal watchers will trigger an event when the process receives a specific	917	<p>Signal watchers will trigger an event when the process receives a specific
…		…
647	the status word (use the macros from <code>sys/wait.h</code> and see your systems	948	the status word (use the macros from <code>sys/wait.h</code> and see your systems
648	<code>waitpid</code> documentation). The <code>rpid</code> member contains the pid of the	949	<code>waitpid</code> documentation). The <code>rpid</code> member contains the pid of the
649	process causing the status change.</p>	950	process causing the status change.</p>
650	</dd>	951	</dd>
651	</dl>	952	</dl>
		953	<p>Example: try to exit cleanly on SIGINT and SIGTERM.</p>
		954	<pre> static void
		955	sigint_cb (struct ev_loop loop, struct ev_signal w, int revents)
		956	{
		957	ev_unloop (loop, EVUNLOOP_ALL);
		958	}
		959
		960	struct ev_signal signal_watcher;
		961	ev_signal_init (&signal_watcher, sigint_cb, SIGINT);
		962	ev_signal_start (loop, &sigint_cb);
		963
		964
		965
		966
		967	</pre>
652		968
653	</div>	969	</div>
654	<h2 id="code_ev_idle_code_when_you_ve_got_no"><code>ev_idle</code> - when you've got nothing better to do</h2>	970	<h2 id="code_ev_idle_code_when_you_ve_got_no"><code>ev_idle</code> - when you've got nothing better to do</h2>
655	<div id="code_ev_idle_code_when_you_ve_got_no-2">	971	<div id="code_ev_idle_code_when_you_ve_got_no-2">
656	<p>Idle watchers trigger events when there are no other events are pending	972	<p>Idle watchers trigger events when there are no other events are pending
…		…
672	<p>Initialises and configures the idle watcher - it has no parameters of any	988	<p>Initialises and configures the idle watcher - it has no parameters of any
673	kind. There is a <code>ev_idle_set</code> macro, but using it is utterly pointless,	989	kind. There is a <code>ev_idle_set</code> macro, but using it is utterly pointless,
674	believe me.</p>	990	believe me.</p>
675	</dd>	991	</dd>
676	</dl>	992	</dl>
		993	<p>Example: dynamically allocate an <code>ev_idle</code>, start it, and in the
		994	callback, free it. Alos, use no error checking, as usual.</p>
		995	<pre> static void
		996	idle_cb (struct ev_loop loop, struct ev_idle w, int revents)
		997	{
		998	free (w);
		999	// now do something you wanted to do when the program has
		1000	// no longer asnything immediate to do.
		1001	}
		1002
		1003	struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle));
		1004	ev_idle_init (idle_watcher, idle_cb);
		1005	ev_idle_start (loop, idle_cb);
		1006
		1007
		1008
		1009
		1010	</pre>
677		1011
678	</div>	1012	</div>
679	<h2 id="code_ev_prepare_code_and_code_ev_che"><code>ev_prepare</code> and <code>ev_check</code> - customise your event loop</h2>	1013	<h2 id="code_ev_prepare_code_and_code_ev_che"><code>ev_prepare</code> and <code>ev_check</code> - customise your event loop</h2>
680	<div id="code_ev_prepare_code_and_code_ev_che-2">	1014	<div id="code_ev_prepare_code_and_code_ev_che-2">
681	<p>Prepare and check watchers are usually (but not always) used in tandem:	1015	<p>Prepare and check watchers are usually (but not always) used in tandem:
…		…
707	<p>Initialises and configures the prepare or check watcher - they have no	1041	<p>Initialises and configures the prepare or check watcher - they have no
708	parameters of any kind. There are <code>ev_prepare_set</code> and <code>ev_check_set</code>	1042	parameters of any kind. There are <code>ev_prepare_set</code> and <code>ev_check_set</code>
709	macros, but using them is utterly, utterly and completely pointless.</p>	1043	macros, but using them is utterly, utterly and completely pointless.</p>
710	</dd>	1044	</dd>
711	</dl>	1045	</dl>
		1046	<p>Example: TODO.</p>
		1047
		1048
		1049
		1050
712		1051
713	</div>	1052	</div>
714	<h1 id="OTHER_FUNCTIONS">OTHER FUNCTIONS</h1><p><a href="#TOP" class="toplink">Top</a></p>	1053	<h1 id="OTHER_FUNCTIONS">OTHER FUNCTIONS</h1><p><a href="#TOP" class="toplink">Top</a></p>
715	<div id="OTHER_FUNCTIONS_CONTENT">	1054	<div id="OTHER_FUNCTIONS_CONTENT">
716	<p>There are some other functions of possible interest. Described. Here. Now.</p>	1055	<p>There are some other functions of possible interest. Described. Here. Now.</p>
…		…
760	<dd>	1099	<dd>
761	<p>Feed an event as if the given signal occured (loop must be the default loop!).</p>	1100	<p>Feed an event as if the given signal occured (loop must be the default loop!).</p>
762	</dd>	1101	</dd>
763	</dl>	1102	</dl>
764		1103
		1104
		1105
		1106
		1107
765	</div>	1108	</div>
766	<h1 id="LIBEVENT_EMULATION">LIBEVENT EMULATION</h1><p><a href="#TOP" class="toplink">Top</a></p>	1109	<h1 id="LIBEVENT_EMULATION">LIBEVENT EMULATION</h1><p><a href="#TOP" class="toplink">Top</a></p>
767	<div id="LIBEVENT_EMULATION_CONTENT">	1110	<div id="LIBEVENT_EMULATION_CONTENT">
768	<p>Libev offers a compatibility emulation layer for libevent. It cannot	1111	<p>Libev offers a compatibility emulation layer for libevent. It cannot
769	emulate the internals of libevent, so here are some usage hints:</p>	1112	emulate the internals of libevent, so here are some usage hints:</p>

Diff Legend

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

Comparing libev/ev.html (file contents): Revision 1.26 by root, Mon Nov 12 19:20:05 2007 UTC vs. Revision 1.35 by root, Fri Nov 23 16:17:12 2007 UTC

Diff Legend

Comparing libev/ev.html (file contents):
Revision 1.26 by root, Mon Nov 12 19:20:05 2007 UTC vs.
Revision 1.35 by root, Fri Nov 23 16:17:12 2007 UTC