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

Comparing libev/ev.pod (file contents):
Revision 1.33 by root, Fri Nov 23 15:26:08 2007 UTC vs.
Revision 1.34 by root, Fri Nov 23 16:17:12 2007 UTC

…		…
45		45
46	Libev represents time as a single floating point number, representing the	46	Libev represents time as a single floating point number, representing the
47	(fractional) number of seconds since the (POSIX) epoch (somewhere near	47	(fractional) number of seconds since the (POSIX) epoch (somewhere near
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 double type in C.	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.
		52
51		53
52	=head1 GLOBAL FUNCTIONS	54	=head1 GLOBAL FUNCTIONS
53		55
54	These functions can be called anytime, even before initialising the	56	These functions can be called anytime, even before initialising the
55	library in any way.	57	library in any way.
…		…
75	Usually, it's a good idea to terminate if the major versions mismatch,	77	Usually, it's a good idea to terminate if the major versions mismatch,
76	as this indicates an incompatible change. Minor versions are usually	78	as this indicates an incompatible change. Minor versions are usually
77	compatible to older versions, so a larger minor version alone is usually	79	compatible to older versions, so a larger minor version alone is usually
78	not a problem.	80	not a problem.
79		81
		82	Example: make sure we haven't accidentally been linked against the wrong
		83	version:
		84
		85	assert (("libev version mismatch",
		86	ev_version_major () == EV_VERSION_MAJOR
		87	&& ev_version_minor () >= EV_VERSION_MINOR));
		88
80	=item unsigned int ev_supported_backends ()	89	=item unsigned int ev_supported_backends ()
81		90
82	Return the set of all backends (i.e. their corresponding C<EV_BACKEND_*>	91	Return the set of all backends (i.e. their corresponding C<EV_BACKEND_*>
83	value) compiled into this binary of libev (independent of their	92	value) compiled into this binary of libev (independent of their
84	availability on the system you are running on). See C<ev_default_loop> for	93	availability on the system you are running on). See C<ev_default_loop> for
85	a description of the set values.	94	a description of the set values.
		95
		96	Example: make sure we have the epoll method, because yeah this is cool and
		97	a must have and can we have a torrent of it please!!!11
		98
		99	assert (("sorry, no epoll, no sex",
		100	ev_supported_backends () & EVBACKEND_EPOLL));
86		101
87	=item unsigned int ev_recommended_backends ()	102	=item unsigned int ev_recommended_backends ()
88		103
89	Return the set of all backends compiled into this binary of libev and also	104	Return the set of all backends compiled into this binary of libev and also
90	recommended for this platform. This set is often smaller than the one	105	recommended for this platform. This set is often smaller than the one
…		…
102	destructive action. The default is your system realloc function.	117	destructive action. The default is your system realloc function.
103		118
104	You could override this function in high-availability programs to, say,	119	You could override this function in high-availability programs to, say,
105	free some memory if it cannot allocate memory, to use a special allocator,	120	free some memory if it cannot allocate memory, to use a special allocator,
106	or even to sleep a while and retry until some memory is available.	121	or even to sleep a while and retry until some memory is available.
		122
		123	Example: replace the libev allocator with one that waits a bit and then
		124	retries: better than mine).
		125
		126	static void *
		127	persistent_realloc (void *ptr, long size)
		128	{
		129	for (;;)
		130	{
		131	void *newptr = realloc (ptr, size);
		132
		133	if (newptr)
		134	return newptr;
		135
		136	sleep (60);
		137	}
		138	}
		139
		140	...
		141	ev_set_allocator (persistent_realloc);
107		142
108	=item ev_set_syserr_cb (void (cb)(const char msg));	143	=item ev_set_syserr_cb (void (cb)(const char msg));
109		144
110	Set the callback function to call on a retryable syscall error (such	145	Set the callback function to call on a retryable syscall error (such
111	as failed select, poll, epoll_wait). The message is a printable string	146	as failed select, poll, epoll_wait). The message is a printable string
…		…
113	callback is set, then libev will expect it to remedy the sitution, no	148	callback is set, then libev will expect it to remedy the sitution, no
114	matter what, when it returns. That is, libev will generally retry the	149	matter what, when it returns. That is, libev will generally retry the
115	requested operation, or, if the condition doesn't go away, do bad stuff	150	requested operation, or, if the condition doesn't go away, do bad stuff
116	(such as abort).	151	(such as abort).
117		152
		153	Example: do the same thing as libev does internally:
		154
		155	static void
		156	fatal_error (const char *msg)
		157	{
		158	perror (msg);
		159	abort ();
		160	}
		161
		162	...
		163	ev_set_syserr_cb (fatal_error);
		164
118	=back	165	=back
119		166
120	=head1 FUNCTIONS CONTROLLING THE EVENT LOOP	167	=head1 FUNCTIONS CONTROLLING THE EVENT LOOP
121		168
122	An event loop is described by a C<struct ev_loop *>. The library knows two	169	An event loop is described by a C<struct ev_loop *>. The library knows two
…		…
257	Similar to C<ev_default_loop>, but always creates a new event loop that is	304	Similar to C<ev_default_loop>, but always creates a new event loop that is
258	always distinct from the default loop. Unlike the default loop, it cannot	305	always distinct from the default loop. Unlike the default loop, it cannot
259	handle signal and child watchers, and attempts to do so will be greeted by	306	handle signal and child watchers, and attempts to do so will be greeted by
260	undefined behaviour (or a failed assertion if assertions are enabled).	307	undefined behaviour (or a failed assertion if assertions are enabled).
261		308
		309	Example: try to create a event loop that uses epoll and nothing else.
		310
		311	struct ev_loop *epoller = ev_loop_new (EVBACKEND_EPOLL \| EVFLAG_NOENV);
		312	if (!epoller)
		313	fatal ("no epoll found here, maybe it hides under your chair");
		314
262	=item ev_default_destroy ()	315	=item ev_default_destroy ()
263		316
264	Destroys the default loop again (frees all memory and kernel state	317	Destroys the default loop again (frees all memory and kernel state
265	etc.). This stops all registered event watchers (by not touching them in	318	etc.). This stops all registered event watchers (by not touching them in
266	any way whatsoever, although you cannot rely on this :).	319	any way whatsoever, although you cannot rely on this :).
…		…
303	use.	356	use.
304		357
305	=item ev_tstamp ev_now (loop)	358	=item ev_tstamp ev_now (loop)
306		359
307	Returns the current "event loop time", which is the time the event loop	360	Returns the current "event loop time", which is the time the event loop
308	got events and started processing them. This timestamp does not change	361	received events and started processing them. This timestamp does not
309	as long as callbacks are being processed, and this is also the base time	362	change as long as callbacks are being processed, and this is also the base
310	used for relative timers. You can treat it as the timestamp of the event	363	time used for relative timers. You can treat it as the timestamp of the
311	occuring (or more correctly, the mainloop finding out about it).	364	event occuring (or more correctly, libev finding out about it).
312		365
313	=item ev_loop (loop, int flags)	366	=item ev_loop (loop, int flags)
314		367
315	Finally, this is it, the event handler. This function usually is called	368	Finally, this is it, the event handler. This function usually is called
316	after you initialised all your watchers and you want to start handling	369	after you initialised all your watchers and you want to start handling
317	events.	370	events.
318		371
319	If the flags argument is specified as C<0>, it will not return until	372	If the flags argument is specified as C<0>, it will not return until
320	either no event watchers are active anymore or C<ev_unloop> was called.	373	either no event watchers are active anymore or C<ev_unloop> was called.
		374
		375	Please note that an explicit C<ev_unloop> is usually better than
		376	relying on all watchers to be stopped when deciding when a program has
		377	finished (especially in interactive programs), but having a program that
		378	automatically loops as long as it has to and no longer by virtue of
		379	relying on its watchers stopping correctly is a thing of beauty.
321		380
322	A flags value of C<EVLOOP_NONBLOCK> will look for new events, will handle	381	A flags value of C<EVLOOP_NONBLOCK> will look for new events, will handle
323	those events and any outstanding ones, but will not block your process in	382	those events and any outstanding ones, but will not block your process in
324	case there are no events and will return after one iteration of the loop.	383	case there are no events and will return after one iteration of the loop.
325		384
…		…
350	Signals and child watchers are implemented as I/O watchers, and will	409	Signals and child watchers are implemented as I/O watchers, and will
351	be handled here by queueing them when their watcher gets executed.	410	be handled here by queueing them when their watcher gets executed.
352	- If ev_unloop has been called or EVLOOP_ONESHOT or EVLOOP_NONBLOCK	411	- If ev_unloop has been called or EVLOOP_ONESHOT or EVLOOP_NONBLOCK
353	were used, return, otherwise continue with step *.	412	were used, return, otherwise continue with step *.
354		413
		414	Example: queue some jobs and then loop until no events are outsanding
		415	anymore.
		416
		417	... queue jobs here, make sure they register event watchers as long
		418	... as they still have work to do (even an idle watcher will do..)
		419	ev_loop (my_loop, 0);
		420	... jobs done. yeah!
		421
355	=item ev_unloop (loop, how)	422	=item ev_unloop (loop, how)
356		423
357	Can be used to make a call to C<ev_loop> return early (but only after it	424	Can be used to make a call to C<ev_loop> return early (but only after it
358	has processed all outstanding events). The C<how> argument must be either	425	has processed all outstanding events). The C<how> argument must be either
359	C<EVUNLOOP_ONE>, which will make the innermost C<ev_loop> call return, or	426	C<EVUNLOOP_ONE>, which will make the innermost C<ev_loop> call return, or
…		…
372	visible to the libev user and should not keep C<ev_loop> from exiting if	439	visible to the libev user and should not keep C<ev_loop> from exiting if
373	no event watchers registered by it are active. It is also an excellent	440	no event watchers registered by it are active. It is also an excellent
374	way to do this for generic recurring timers or from within third-party	441	way to do this for generic recurring timers or from within third-party
375	libraries. Just remember to I<unref after start> and I<ref before stop>.	442	libraries. Just remember to I<unref after start> and I<ref before stop>.
376		443
		444	Example: create a signal watcher, but keep it from keeping C<ev_loop>
		445	running when nothing else is active.
		446
		447	struct dv_signal exitsig;
		448	ev_signal_init (&exitsig, sig_cb, SIGINT);
		449	ev_signal_start (myloop, &exitsig);
		450	evf_unref (myloop);
		451
		452	Example: for some weird reason, unregister the above signal handler again.
		453
		454	ev_ref (myloop);
		455	ev_signal_stop (myloop, &exitsig);
		456
377	=back	457	=back
378		458
379	=head1 ANATOMY OF A WATCHER	459	=head1 ANATOMY OF A WATCHER
380		460
381	A watcher is a structure that you create and register to record your	461	A watcher is a structure that you create and register to record your
…		…
521		601
522	=head1 WATCHER TYPES	602	=head1 WATCHER TYPES
523		603
524	This section describes each watcher in detail, but will not repeat	604	This section describes each watcher in detail, but will not repeat
525	information given in the last section.	605	information given in the last section.
		606
526		607
527	=head2 C<ev_io> - is this file descriptor readable or writable	608	=head2 C<ev_io> - is this file descriptor readable or writable
528		609
529	I/O watchers check whether a file descriptor is readable or writable	610	I/O watchers check whether a file descriptor is readable or writable
530	in each iteration of the event loop (This behaviour is called	611	in each iteration of the event loop (This behaviour is called
…		…
568	typical ways of handling events, so its a good idea to use non-blocking	649	typical ways of handling events, so its a good idea to use non-blocking
569	I/O unconditionally.	650	I/O unconditionally.
570		651
571	=back	652	=back
572		653
		654	Example: call C<stdin_readable_cb> when STDIN_FILENO has become, well
		655	readable, but only once. Since it is likely line-buffered, you could
		656	attempt to read a whole line in the callback:
		657
		658	static void
		659	stdin_readable_cb (struct ev_loop loop, struct ev_io w, int revents)
		660	{
		661	ev_io_stop (loop, w);
		662	.. read from stdin here (or from w->fd) and haqndle any I/O errors
		663	}
		664
		665	...
		666	struct ev_loop *loop = ev_default_init (0);
		667	struct ev_io stdin_readable;
		668	ev_io_init (&stdin_readable, stdin_readable_cb, STDIN_FILENO, EV_READ);
		669	ev_io_start (loop, &stdin_readable);
		670	ev_loop (loop, 0);
		671
		672
573	=head2 C<ev_timer> - relative and optionally recurring timeouts	673	=head2 C<ev_timer> - relative and optionally recurring timeouts
574		674
575	Timer watchers are simple relative timers that generate an event after a	675	Timer watchers are simple relative timers that generate an event after a
576	given time, and optionally repeating in regular intervals after that.	676	given time, and optionally repeating in regular intervals after that.
577		677
…		…
629	state where you do not expect data to travel on the socket, you can stop	729	state where you do not expect data to travel on the socket, you can stop
630	the timer, and again will automatically restart it if need be.	730	the timer, and again will automatically restart it if need be.
631		731
632	=back	732	=back
633		733
		734	Example: create a timer that fires after 60 seconds.
		735
		736	static void
		737	one_minute_cb (struct ev_loop loop, struct ev_timer w, int revents)
		738	{
		739	.. one minute over, w is actually stopped right here
		740	}
		741
		742	struct ev_timer mytimer;
		743	ev_timer_init (&mytimer, one_minute_cb, 60., 0.);
		744	ev_timer_start (loop, &mytimer);
		745
		746	Example: create a timeout timer that times out after 10 seconds of
		747	inactivity.
		748
		749	static void
		750	timeout_cb (struct ev_loop loop, struct ev_timer w, int revents)
		751	{
		752	.. ten seconds without any activity
		753	}
		754
		755	struct ev_timer mytimer;
		756	ev_timer_init (&mytimer, timeout_cb, 0., 10.); /* note, only repeat used */
		757	ev_timer_again (&mytimer); /* start timer */
		758	ev_loop (loop, 0);
		759
		760	// and in some piece of code that gets executed on any "activity":
		761	// reset the timeout to start ticking again at 10 seconds
		762	ev_timer_again (&mytimer);
		763
		764
634	=head2 C<ev_periodic> - to cron or not to cron	765	=head2 C<ev_periodic> - to cron or not to cron
635		766
636	Periodic watchers are also timers of a kind, but they are very versatile	767	Periodic watchers are also timers of a kind, but they are very versatile
637	(and unfortunately a bit complex).	768	(and unfortunately a bit complex).
638		769
…		…
733	a different time than the last time it was called (e.g. in a crond like	864	a different time than the last time it was called (e.g. in a crond like
734	program when the crontabs have changed).	865	program when the crontabs have changed).
735		866
736	=back	867	=back
737		868
		869	Example: call a callback every hour, or, more precisely, whenever the
		870	system clock is divisible by 3600. The callback invocation times have
		871	potentially a lot of jittering, but good long-term stability.
		872
		873	static void
		874	clock_cb (struct ev_loop loop, struct ev_io w, int revents)
		875	{
		876	... its now a full hour (UTC, or TAI or whatever your clock follows)
		877	}
		878
		879	struct ev_periodic hourly_tick;
		880	ev_periodic_init (&hourly_tick, clock_cb, 0., 3600., 0);
		881	ev_periodic_start (loop, &hourly_tick);
		882
		883	Example: the same as above, but use a reschedule callback to do it:
		884
		885	#include <math.h>
		886
		887	static ev_tstamp
		888	my_scheduler_cb (struct ev_periodic *w, ev_tstamp now)
		889	{
		890	return fmod (now, 3600.) + 3600.;
		891	}
		892
		893	ev_periodic_init (&hourly_tick, clock_cb, 0., 0., my_scheduler_cb);
		894
		895	Example: call a callback every hour, starting now:
		896
		897	struct ev_periodic hourly_tick;
		898	ev_periodic_init (&hourly_tick, clock_cb,
		899	fmod (ev_now (loop), 3600.), 3600., 0);
		900	ev_periodic_start (loop, &hourly_tick);
		901
		902
738	=head2 C<ev_signal> - signal me when a signal gets signalled	903	=head2 C<ev_signal> - signal me when a signal gets signalled
739		904
740	Signal watchers will trigger an event when the process receives a specific	905	Signal watchers will trigger an event when the process receives a specific
741	signal one or more times. Even though signals are very asynchronous, libev	906	signal one or more times. Even though signals are very asynchronous, libev
742	will try it's best to deliver signals synchronously, i.e. as part of the	907	will try it's best to deliver signals synchronously, i.e. as part of the
…		…
777	the status word (use the macros from C<sys/wait.h> and see your systems	942	the status word (use the macros from C<sys/wait.h> and see your systems
778	C<waitpid> documentation). The C<rpid> member contains the pid of the	943	C<waitpid> documentation). The C<rpid> member contains the pid of the
779	process causing the status change.	944	process causing the status change.
780		945
781	=back	946	=back
		947
		948	Example: try to exit cleanly on SIGINT and SIGTERM.
		949
		950	static void
		951	sigint_cb (struct ev_loop loop, struct ev_signal w, int revents)
		952	{
		953	ev_unloop (loop, EVUNLOOP_ALL);
		954	}
		955
		956	struct ev_signal signal_watcher;
		957	ev_signal_init (&signal_watcher, sigint_cb, SIGINT);
		958	ev_signal_start (loop, &sigint_cb);
		959
782		960
783	=head2 C<ev_idle> - when you've got nothing better to do	961	=head2 C<ev_idle> - when you've got nothing better to do
784		962
785	Idle watchers trigger events when there are no other events are pending	963	Idle watchers trigger events when there are no other events are pending
786	(prepare, check and other idle watchers do not count). That is, as long	964	(prepare, check and other idle watchers do not count). That is, as long
…		…
805	Initialises and configures the idle watcher - it has no parameters of any	983	Initialises and configures the idle watcher - it has no parameters of any
806	kind. There is a C<ev_idle_set> macro, but using it is utterly pointless,	984	kind. There is a C<ev_idle_set> macro, but using it is utterly pointless,
807	believe me.	985	believe me.
808		986
809	=back	987	=back
		988
		989	Example: dynamically allocate an C<ev_idle>, start it, and in the
		990	callback, free it. Alos, use no error checking, as usual.
		991
		992	static void
		993	idle_cb (struct ev_loop loop, struct ev_idle w, int revents)
		994	{
		995	free (w);
		996	// now do something you wanted to do when the program has
		997	// no longer asnything immediate to do.
		998	}
		999
		1000	struct ev_idle *idle_watcher = malloc (sizeof (struct ev_idle));
		1001	ev_idle_init (idle_watcher, idle_cb);
		1002	ev_idle_start (loop, idle_cb);
		1003
810		1004
811	=head2 C<ev_prepare> and C<ev_check> - customise your event loop	1005	=head2 C<ev_prepare> and C<ev_check> - customise your event loop
812		1006
813	Prepare and check watchers are usually (but not always) used in tandem:	1007	Prepare and check watchers are usually (but not always) used in tandem:
814	prepare watchers get invoked before the process blocks and check watchers	1008	prepare watchers get invoked before the process blocks and check watchers
…		…
846	parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set>	1040	parameters of any kind. There are C<ev_prepare_set> and C<ev_check_set>
847	macros, but using them is utterly, utterly and completely pointless.	1041	macros, but using them is utterly, utterly and completely pointless.
848		1042
849	=back	1043	=back
850		1044
		1045	Example: TODO.
		1046
		1047
851	=head1 OTHER FUNCTIONS	1048	=head1 OTHER FUNCTIONS
852		1049
853	There are some other functions of possible interest. Described. Here. Now.	1050	There are some other functions of possible interest. Described. Here. Now.
854		1051
855	=over 4	1052	=over 4
…		…
901		1098
902	Feed an event as if the given signal occured (loop must be the default loop!).	1099	Feed an event as if the given signal occured (loop must be the default loop!).
903		1100
904	=back	1101	=back
905		1102
		1103
906	=head1 LIBEVENT EMULATION	1104	=head1 LIBEVENT EMULATION
907		1105
908	Libev offers a compatibility emulation layer for libevent. It cannot	1106	Libev offers a compatibility emulation layer for libevent. It cannot
909	emulate the internals of libevent, so here are some usage hints:	1107	emulate the internals of libevent, so here are some usage hints:
910		1108

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.33 by root, Fri Nov 23 15:26:08 2007 UTC vs. Revision 1.34 by root, Fri Nov 23 16:17:12 2007 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.33 by root, Fri Nov 23 15:26:08 2007 UTC vs.
Revision 1.34 by root, Fri Nov 23 16:17:12 2007 UTC