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

Comparing libev/ev.pod (file contents):
Revision 1.49 by root, Tue Nov 27 08:20:42 2007 UTC vs.
Revision 1.52 by root, Tue Nov 27 19:41:52 2007 UTC

…		…
48	the beginning of 1970, details are complicated, don't ask). This type is	48	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	49	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	50	to the C<double> type in C, and when you need to do any calculations on
51	it, you should treat it as such.	51	it, you should treat it as such.
52		52
53
54	=head1 GLOBAL FUNCTIONS	53	=head1 GLOBAL FUNCTIONS
55		54
56	These functions can be called anytime, even before initialising the	55	These functions can be called anytime, even before initialising the
57	library in any way.	56	library in any way.
58		57
…		…
116	C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for	115	C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for
117	recommended ones.	116	recommended ones.
118		117
119	See the description of C<ev_embed> watchers for more info.	118	See the description of C<ev_embed> watchers for more info.
120		119
121	=item ev_set_allocator (void (cb)(void *ptr, long size))	120	=item ev_set_allocator (void (cb)(void *ptr, size_t size))
122		121
123	Sets the allocation function to use (the prototype is similar to the	122	Sets the allocation function to use (the prototype and semantics are
124	realloc C function, the semantics are identical). It is used to allocate	123	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	124	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	125	allocated, the library might abort or take some potentially destructive
127	destructive action. The default is your system realloc function.	126	action. The default is your system realloc function.
128		127
129	You could override this function in high-availability programs to, say,	128	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,	129	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.	130	or even to sleep a while and retry until some memory is available.
132		131
133	Example: replace the libev allocator with one that waits a bit and then	132	Example: replace the libev allocator with one that waits a bit and then
134	retries: better than mine).	133	retries: better than mine).
135		134
136	static void *	135	static void *
137	persistent_realloc (void *ptr, long size)	136	persistent_realloc (void *ptr, size_t size)
138	{	137	{
139	for (;;)	138	for (;;)
140	{	139	{
141	void *newptr = realloc (ptr, size);	140	void *newptr = realloc (ptr, size);
142		141
…		…
565	received events. Callbacks of both watcher types can start and stop as	564	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	565	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	566	(for example, a C<ev_prepare> watcher might start an idle watcher to keep
568	C<ev_loop> from blocking).	567	C<ev_loop> from blocking).
569		568
		569	=item C<EV_EMBED>
		570
		571	The embedded event loop specified in the C<ev_embed> watcher needs attention.
		572
		573	=item C<EV_FORK>
		574
		575	The event loop has been resumed in the child process after fork (see
		576	C<ev_fork>).
		577
570	=item C<EV_ERROR>	578	=item C<EV_ERROR>
571		579
572	An unspecified error has occured, the watcher has been stopped. This might	580	An unspecified error has occured, the watcher has been stopped. This might
573	happen because the watcher could not be properly started because libev	581	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	582	ran out of memory, a file descriptor was found to be closed or any other
…		…
1470	The embedded event loop.	1478	The embedded event loop.
1471		1479
1472	=back	1480	=back
1473		1481
1474		1482
		1483	=head2 C<ev_fork> - the audacity to resume the event loop after a fork
		1484
		1485	Fork watchers are called when a C<fork ()> was detected (usually because
		1486	whoever is a good citizen cared to tell libev about it by calling
		1487	C<ev_default_fork> or C<ev_loop_fork>). The invocation is done before the
		1488	event loop blocks next and before C<ev_check> watchers are being called,
		1489	and only in the child after the fork. If whoever good citizen calling
		1490	C<ev_default_fork> cheats and calls it in the wrong process, the fork
		1491	handlers will be invoked, too, of course.
		1492
		1493	=over 4
		1494
		1495	=item ev_fork_init (ev_signal *, callback)
		1496
		1497	Initialises and configures the fork watcher - it has no parameters of any
		1498	kind. There is a C<ev_fork_set> macro, but using it is utterly pointless,
		1499	believe me.
		1500
		1501	=back
		1502
		1503
1475	=head1 OTHER FUNCTIONS	1504	=head1 OTHER FUNCTIONS
1476		1505
1477	There are some other functions of possible interest. Described. Here. Now.	1506	There are some other functions of possible interest. Described. Here. Now.
1478		1507
1479	=over 4	1508	=over 4
…		…
1663	: io (this, &myclass::io_cb),	1692	: io (this, &myclass::io_cb),
1664	idle (this, &myclass::idle_cb)	1693	idle (this, &myclass::idle_cb)
1665	{	1694	{
1666	io.start (fd, ev::READ);	1695	io.start (fd, ev::READ);
1667	}	1696	}
		1697
		1698
		1699	=head1 MACRO MAGIC
		1700
		1701	Libev can be compiled with a variety of options, the most fundemantal is
		1702	C<EV_MULTIPLICITY>. This option determines wether (most) functions and
		1703	callbacks have an initial C<struct ev_loop *> argument.
		1704
		1705	To make it easier to write programs that cope with either variant, the
		1706	following macros are defined:
		1707
		1708	=over 4
		1709
		1710	=item C<EV_A>, C<EV_A_>
		1711
		1712	This provides the loop I<argument> for functions, if one is required ("ev
		1713	loop argument"). The C<EV_A> form is used when this is the sole argument,
		1714	C<EV_A_> is used when other arguments are following. Example:
		1715
		1716	ev_unref (EV_A);
		1717	ev_timer_add (EV_A_ watcher);
		1718	ev_loop (EV_A_ 0);
		1719
		1720	It assumes the variable C<loop> of type C<struct ev_loop *> is in scope,
		1721	which is often provided by the following macro.
		1722
		1723	=item C<EV_P>, C<EV_P_>
		1724
		1725	This provides the loop I<parameter> for functions, if one is required ("ev
		1726	loop parameter"). The C<EV_P> form is used when this is the sole parameter,
		1727	C<EV_P_> is used when other parameters are following. Example:
		1728
		1729	// this is how ev_unref is being declared
		1730	static void ev_unref (EV_P);
		1731
		1732	// this is how you can declare your typical callback
		1733	static void cb (EV_P_ ev_timer *w, int revents)
		1734
		1735	It declares a parameter C<loop> of type C<struct ev_loop *>, quite
		1736	suitable for use with C<EV_A>.
		1737
		1738	=item C<EV_DEFAULT>, C<EV_DEFAULT_>
		1739
		1740	Similar to the other two macros, this gives you the value of the default
		1741	loop, if multiple loops are supported ("ev loop default").
		1742
		1743	=back
		1744
		1745	Example: Declare and initialise a check watcher, working regardless of
		1746	wether multiple loops are supported or not.
		1747
		1748	static void
		1749	check_cb (EV_P_ ev_timer *w, int revents)
		1750	{
		1751	ev_check_stop (EV_A_ w);
		1752	}
		1753
		1754	ev_check check;
		1755	ev_check_init (&check, check_cb);
		1756	ev_check_start (EV_DEFAULT_ &check);
		1757	ev_loop (EV_DEFAULT_ 0);
		1758
1668		1759
1669	=head1 EMBEDDING	1760	=head1 EMBEDDING
1670		1761
1671	Libev can (and often is) directly embedded into host	1762	Libev can (and often is) directly embedded into host
1672	applications. Examples of applications that embed it include the Deliantra	1763	applications. Examples of applications that embed it include the Deliantra
…		…
1895	=item EV_STAT_ENABLE	1986	=item EV_STAT_ENABLE
1896		1987
1897	If undefined or defined to be C<1>, then stat watchers are supported. If	1988	If undefined or defined to be C<1>, then stat watchers are supported. If
1898	defined to be C<0>, then they are not.	1989	defined to be C<0>, then they are not.
1899		1990
		1991	=item EV_FORK_ENABLE
		1992
		1993	If undefined or defined to be C<1>, then fork watchers are supported. If
		1994	defined to be C<0>, then they are not.
		1995
1900	=item EV_MINIMAL	1996	=item EV_MINIMAL
1901		1997
1902	If you need to shave off some kilobytes of code at the expense of some	1998	If you need to shave off some kilobytes of code at the expense of some
1903	speed, define this symbol to C<1>. Currently only used for gcc to override	1999	speed, define this symbol to C<1>. Currently only used for gcc to override
1904	some inlining decisions, saves roughly 30% codesize of amd64.	2000	some inlining decisions, saves roughly 30% codesize of amd64.
		2001
		2002	=item EV_PID_HASHSIZE
		2003
		2004	C<ev_child> watchers use a small hash table to distribute workload by
		2005	pid. The default size is C<16> (or C<1> with C<EV_MINIMAL>), usually more
		2006	than enough. If you need to manage thousands of children you might want to
		2007	increase this value.
1905		2008
1906	=item EV_COMMON	2009	=item EV_COMMON
1907		2010
1908	By default, all watchers have a C<void *data> member. By redefining	2011	By default, all watchers have a C<void *data> member. By redefining
1909	this macro to a something else you can include more and other types of	2012	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.49 by root, Tue Nov 27 08:20:42 2007 UTC vs. Revision 1.52 by root, Tue Nov 27 19:41:52 2007 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.49 by root, Tue Nov 27 08:20:42 2007 UTC vs.
Revision 1.52 by root, Tue Nov 27 19:41:52 2007 UTC