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

Comparing libev/ev.pod (file contents):
Revision 1.48 by root, Tue Nov 27 08:11:52 2007 UTC vs.
Revision 1.53 by root, Tue Nov 27 20:15:02 2007 UTC

…		…
2		2
3	libev - a high performance full-featured event loop written in C	3	libev - a high performance full-featured event loop written in C
4		4
5	=head1 SYNOPSIS	5	=head1 SYNOPSIS
6		6
		7	/* this is the only header you need */
7	#include <ev.h>	8	#include <ev.h>
		9
		10	/* what follows is a fully working example program */
		11	ev_io stdin_watcher;
		12	ev_timer timeout_watcher;
		13
		14	/* called when data readable on stdin */
		15	static void
		16	stdin_cb (EV_P_ struct ev_io *w, int revents)
		17	{
		18	/* puts ("stdin ready"); */
		19	ev_io_stop (EV_A_ w); /* just a syntax example */
		20	ev_unloop (EV_A_ EVUNLOOP_ALL); /* leave all loop calls */
		21	}
		22
		23	static void
		24	timeout_cb (EV_P_ struct ev_timer *w, int revents)
		25	{
		26	/* puts ("timeout"); */
		27	ev_unloop (EV_A_ EVUNLOOP_ONE); /* leave one loop call */
		28	}
		29
		30	int
		31	main (void)
		32	{
		33	struct ev_loop *loop = ev_default_loop (0);
		34
		35	/* initialise an io watcher, then start it */
		36	ev_io_init (&stdin_watcher, stdin_cb, /STDIN_FILENO/ 0, EV_READ);
		37	ev_io_start (loop, &stdin_watcher);
		38
		39	/* simple non-repeating 5.5 second timeout */
		40	ev_timer_init (&timeout_watcher, timeout_cb, 5.5, 0.);
		41	ev_timer_start (loop, &timeout_watcher);
		42
		43	/* loop till timeout or data ready */
		44	ev_loop (loop, 0);
		45
		46	return 0;
		47	}
8		48
9	=head1 DESCRIPTION	49	=head1 DESCRIPTION
10		50
11	Libev is an event loop: you register interest in certain events (such as a	51	Libev is an event loop: you register interest in certain events (such as a
12	file descriptor being readable or a timeout occuring), and it will manage	52	file descriptor being readable or a timeout occuring), and it will manage
…		…
48	the beginning of 1970, details are complicated, don't ask). This type is	88	the beginning of 1970, details are complicated, don't ask). This type is
49	called C<ev_tstamp>, which is what you should use too. It usually aliases	89	called C<ev_tstamp>, which is what you should use too. It usually aliases
50	to the C<double> type in C, and when you need to do any calculations on	90	to the C<double> type in C, and when you need to do any calculations on
51	it, you should treat it as such.	91	it, you should treat it as such.
52		92
53
54	=head1 GLOBAL FUNCTIONS	93	=head1 GLOBAL FUNCTIONS
55		94
56	These functions can be called anytime, even before initialising the	95	These functions can be called anytime, even before initialising the
57	library in any way.	96	library in any way.
58		97
…		…
116	C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for	155	C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for
117	recommended ones.	156	recommended ones.
118		157
119	See the description of C<ev_embed> watchers for more info.	158	See the description of C<ev_embed> watchers for more info.
120		159
121	=item ev_set_allocator (void (cb)(void *ptr, long size))	160	=item ev_set_allocator (void (cb)(void *ptr, size_t size))
122		161
123	Sets the allocation function to use (the prototype is similar to the	162	Sets the allocation function to use (the prototype and semantics are
124	realloc C function, the semantics are identical). It is used to allocate	163	identical to the realloc C function). It is used to allocate and free
125	and free memory (no surprises here). If it returns zero when memory	164	memory (no surprises here). If it returns zero when memory needs to be
126	needs to be allocated, the library might abort or take some potentially	165	allocated, the library might abort or take some potentially destructive
127	destructive action. The default is your system realloc function.	166	action. The default is your system realloc function.
128		167
129	You could override this function in high-availability programs to, say,	168	You could override this function in high-availability programs to, say,
130	free some memory if it cannot allocate memory, to use a special allocator,	169	free some memory if it cannot allocate memory, to use a special allocator,
131	or even to sleep a while and retry until some memory is available.	170	or even to sleep a while and retry until some memory is available.
132		171
133	Example: replace the libev allocator with one that waits a bit and then	172	Example: replace the libev allocator with one that waits a bit and then
134	retries: better than mine).	173	retries: better than mine).
135		174
136	static void *	175	static void *
137	persistent_realloc (void *ptr, long size)	176	persistent_realloc (void *ptr, size_t size)
138	{	177	{
139	for (;;)	178	for (;;)
140	{	179	{
141	void *newptr = realloc (ptr, size);	180	void *newptr = realloc (ptr, size);
142		181
…		…
565	received events. Callbacks of both watcher types can start and stop as	604	received events. Callbacks of both watcher types can start and stop as
566	many watchers as they want, and all of them will be taken into account	605	many watchers as they want, and all of them will be taken into account
567	(for example, a C<ev_prepare> watcher might start an idle watcher to keep	606	(for example, a C<ev_prepare> watcher might start an idle watcher to keep
568	C<ev_loop> from blocking).	607	C<ev_loop> from blocking).
569		608
		609	=item C<EV_EMBED>
		610
		611	The embedded event loop specified in the C<ev_embed> watcher needs attention.
		612
		613	=item C<EV_FORK>
		614
		615	The event loop has been resumed in the child process after fork (see
		616	C<ev_fork>).
		617
570	=item C<EV_ERROR>	618	=item C<EV_ERROR>
571		619
572	An unspecified error has occured, the watcher has been stopped. This might	620	An unspecified error has occured, the watcher has been stopped. This might
573	happen because the watcher could not be properly started because libev	621	happen because the watcher could not be properly started because libev
574	ran out of memory, a file descriptor was found to be closed or any other	622	ran out of memory, a file descriptor was found to be closed or any other
…		…
1470	The embedded event loop.	1518	The embedded event loop.
1471		1519
1472	=back	1520	=back
1473		1521
1474		1522
		1523	=head2 C<ev_fork> - the audacity to resume the event loop after a fork
		1524
		1525	Fork watchers are called when a C<fork ()> was detected (usually because
		1526	whoever is a good citizen cared to tell libev about it by calling
		1527	C<ev_default_fork> or C<ev_loop_fork>). The invocation is done before the
		1528	event loop blocks next and before C<ev_check> watchers are being called,
		1529	and only in the child after the fork. If whoever good citizen calling
		1530	C<ev_default_fork> cheats and calls it in the wrong process, the fork
		1531	handlers will be invoked, too, of course.
		1532
		1533	=over 4
		1534
		1535	=item ev_fork_init (ev_signal *, callback)
		1536
		1537	Initialises and configures the fork watcher - it has no parameters of any
		1538	kind. There is a C<ev_fork_set> macro, but using it is utterly pointless,
		1539	believe me.
		1540
		1541	=back
		1542
		1543
1475	=head1 OTHER FUNCTIONS	1544	=head1 OTHER FUNCTIONS
1476		1545
1477	There are some other functions of possible interest. Described. Here. Now.	1546	There are some other functions of possible interest. Described. Here. Now.
1478		1547
1479	=over 4	1548	=over 4
…		…
1638		1707
1639	=item w->sweep () C<ev::embed> only	1708	=item w->sweep () C<ev::embed> only
1640		1709
1641	Invokes C<ev_embed_sweep>.	1710	Invokes C<ev_embed_sweep>.
1642		1711
		1712	=item w->update () C<ev::stat> only
		1713
		1714	Invokes C<ev_stat_stat>.
		1715
1643	=back	1716	=back
1644		1717
1645	=back	1718	=back
1646		1719
1647	Example: Define a class with an IO and idle watcher, start one of them in	1720	Example: Define a class with an IO and idle watcher, start one of them in
…		…
1659	: io (this, &myclass::io_cb),	1732	: io (this, &myclass::io_cb),
1660	idle (this, &myclass::idle_cb)	1733	idle (this, &myclass::idle_cb)
1661	{	1734	{
1662	io.start (fd, ev::READ);	1735	io.start (fd, ev::READ);
1663	}	1736	}
		1737
		1738
		1739	=head1 MACRO MAGIC
		1740
		1741	Libev can be compiled with a variety of options, the most fundemantal is
		1742	C<EV_MULTIPLICITY>. This option determines wether (most) functions and
		1743	callbacks have an initial C<struct ev_loop *> argument.
		1744
		1745	To make it easier to write programs that cope with either variant, the
		1746	following macros are defined:
		1747
		1748	=over 4
		1749
		1750	=item C<EV_A>, C<EV_A_>
		1751
		1752	This provides the loop I<argument> for functions, if one is required ("ev
		1753	loop argument"). The C<EV_A> form is used when this is the sole argument,
		1754	C<EV_A_> is used when other arguments are following. Example:
		1755
		1756	ev_unref (EV_A);
		1757	ev_timer_add (EV_A_ watcher);
		1758	ev_loop (EV_A_ 0);
		1759
		1760	It assumes the variable C<loop> of type C<struct ev_loop *> is in scope,
		1761	which is often provided by the following macro.
		1762
		1763	=item C<EV_P>, C<EV_P_>
		1764
		1765	This provides the loop I<parameter> for functions, if one is required ("ev
		1766	loop parameter"). The C<EV_P> form is used when this is the sole parameter,
		1767	C<EV_P_> is used when other parameters are following. Example:
		1768
		1769	// this is how ev_unref is being declared
		1770	static void ev_unref (EV_P);
		1771
		1772	// this is how you can declare your typical callback
		1773	static void cb (EV_P_ ev_timer *w, int revents)
		1774
		1775	It declares a parameter C<loop> of type C<struct ev_loop *>, quite
		1776	suitable for use with C<EV_A>.
		1777
		1778	=item C<EV_DEFAULT>, C<EV_DEFAULT_>
		1779
		1780	Similar to the other two macros, this gives you the value of the default
		1781	loop, if multiple loops are supported ("ev loop default").
		1782
		1783	=back
		1784
		1785	Example: Declare and initialise a check watcher, working regardless of
		1786	wether multiple loops are supported or not.
		1787
		1788	static void
		1789	check_cb (EV_P_ ev_timer *w, int revents)
		1790	{
		1791	ev_check_stop (EV_A_ w);
		1792	}
		1793
		1794	ev_check check;
		1795	ev_check_init (&check, check_cb);
		1796	ev_check_start (EV_DEFAULT_ &check);
		1797	ev_loop (EV_DEFAULT_ 0);
		1798
1664		1799
1665	=head1 EMBEDDING	1800	=head1 EMBEDDING
1666		1801
1667	Libev can (and often is) directly embedded into host	1802	Libev can (and often is) directly embedded into host
1668	applications. Examples of applications that embed it include the Deliantra	1803	applications. Examples of applications that embed it include the Deliantra
…		…
1891	=item EV_STAT_ENABLE	2026	=item EV_STAT_ENABLE
1892		2027
1893	If undefined or defined to be C<1>, then stat watchers are supported. If	2028	If undefined or defined to be C<1>, then stat watchers are supported. If
1894	defined to be C<0>, then they are not.	2029	defined to be C<0>, then they are not.
1895		2030
		2031	=item EV_FORK_ENABLE
		2032
		2033	If undefined or defined to be C<1>, then fork watchers are supported. If
		2034	defined to be C<0>, then they are not.
		2035
1896	=item EV_MINIMAL	2036	=item EV_MINIMAL
1897		2037
1898	If you need to shave off some kilobytes of code at the expense of some	2038	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	2039	speed, define this symbol to C<1>. Currently only used for gcc to override
1900	some inlining decisions, saves roughly 30% codesize of amd64.	2040	some inlining decisions, saves roughly 30% codesize of amd64.
		2041
		2042	=item EV_PID_HASHSIZE
		2043
		2044	C<ev_child> watchers use a small hash table to distribute workload by
		2045	pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more
		2046	than enough. If you need to manage thousands of children you might want to
		2047	increase this value.
1901		2048
1902	=item EV_COMMON	2049	=item EV_COMMON
1903		2050
1904	By default, all watchers have a C<void *data> member. By redefining	2051	By default, all watchers have a C<void *data> member. By redefining
1905	this macro to a something else you can include more and other types of	2052	this macro to a something else you can include more and other types of

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.48 by root, Tue Nov 27 08:11:52 2007 UTC vs. Revision 1.53 by root, Tue Nov 27 20:15:02 2007 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.48 by root, Tue Nov 27 08:11:52 2007 UTC vs.
Revision 1.53 by root, Tue Nov 27 20:15:02 2007 UTC