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

Comparing libev/ev.pod (file contents):
Revision 1.34 by root, Fri Nov 23 16:17:12 2007 UTC vs.
Revision 1.35 by root, Fri Nov 23 19:35:09 2007 UTC

…		…
105	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
106	returned by C<ev_supported_backends>, as for example kqueue is broken on	106	returned by C<ev_supported_backends>, as for example kqueue is broken on
107	most BSDs and will not be autodetected unless you explicitly request it	107	most BSDs and will not be autodetected unless you explicitly request it
108	(assuming you know what you are doing). This is the set of backends that	108	(assuming you know what you are doing). This is the set of backends that
109	libev will probe for if you specify no backends explicitly.	109	libev will probe for if you specify no backends explicitly.
		110
		111	=item unsigned int ev_embeddable_backends ()
		112
		113	Returns the set of backends that are embeddable in other event loops. This
		114	is the theoretical, all-platform, value. To find which backends
		115	might be supported on the current system, you would need to look at
		116	C<ev_embeddable_backends () & ev_supported_backends ()>, likewise for
		117	recommended ones.
		118
		119	See the description of C<ev_embed> watchers for more info.
110		120
111	=item ev_set_allocator (void (cb)(void *ptr, long size))	121	=item ev_set_allocator (void (cb)(void *ptr, long size))
112		122
113	Sets the allocation function to use (the prototype is similar to the	123	Sets the allocation function to use (the prototype is similar to the
114	realloc C function, the semantics are identical). It is used to allocate	124	realloc C function, the semantics are identical). It is used to allocate
…		…
923	Configures the watcher to trigger on the given signal number (usually one	933	Configures the watcher to trigger on the given signal number (usually one
924	of the C<SIGxxx> constants).	934	of the C<SIGxxx> constants).
925		935
926	=back	936	=back
927		937
		938
928	=head2 C<ev_child> - wait for pid status changes	939	=head2 C<ev_child> - wait for pid status changes
929		940
930	Child watchers trigger when your process receives a SIGCHLD in response to	941	Child watchers trigger when your process receives a SIGCHLD in response to
931	some child status changes (most typically when a child of yours dies).	942	some child status changes (most typically when a child of yours dies).
932		943
…		…
1006		1017
1007	Prepare and check watchers are usually (but not always) used in tandem:	1018	Prepare and check watchers are usually (but not always) used in tandem:
1008	prepare watchers get invoked before the process blocks and check watchers	1019	prepare watchers get invoked before the process blocks and check watchers
1009	afterwards.	1020	afterwards.
1010		1021
1011	Their main purpose is to integrate other event mechanisms into libev. This	1022	Their main purpose is to integrate other event mechanisms into libev and
1012	could be used, for example, to track variable changes, implement your own	1023	their use is somewhat advanced. This could be used, for example, to track
1013	watchers, integrate net-snmp or a coroutine library and lots more.	1024	variable changes, implement your own watchers, integrate net-snmp or a
		1025	coroutine library and lots more.
1014		1026
1015	This is done by examining in each prepare call which file descriptors need	1027	This is done by examining in each prepare call which file descriptors need
1016	to be watched by the other library, registering C<ev_io> watchers for	1028	to be watched by the other library, registering C<ev_io> watchers for
1017	them and starting an C<ev_timer> watcher for any timeouts (many libraries	1029	them and starting an C<ev_timer> watcher for any timeouts (many libraries
1018	provide just this functionality). Then, in the check watcher you check for	1030	provide just this functionality). Then, in the check watcher you check for
…		…
1043	=back	1055	=back
1044		1056
1045	Example: TODO.	1057	Example: TODO.
1046		1058
1047		1059
		1060	=head2 C<ev_embed> - when one backend isn't enough
		1061
		1062	This is a rather advanced watcher type that lets you embed one event loop
		1063	into another.
		1064
		1065	There are primarily two reasons you would want that: work around bugs and
		1066	prioritise I/O.
		1067
		1068	As an example for a bug workaround, the kqueue backend might only support
		1069	sockets on some platform, so it is unusable as generic backend, but you
		1070	still want to make use of it because you have many sockets and it scales
		1071	so nicely. In this case, you would create a kqueue-based loop and embed it
		1072	into your default loop (which might use e.g. poll). Overall operation will
		1073	be a bit slower because first libev has to poll and then call kevent, but
		1074	at least you can use both at what they are best.
		1075
		1076	As for prioritising I/O: rarely you have the case where some fds have
		1077	to be watched and handled very quickly (with low latency), and even
		1078	priorities and idle watchers might have too much overhead. In this case
		1079	you would put all the high priority stuff in one loop and all the rest in
		1080	a second one, and embed the second one in the first.
		1081
		1082	As long as the watcher is started it will automatically handle events. The
		1083	callback will be invoked whenever some events have been handled. You can
		1084	set the callback to C<0> to avoid having to specify one if you are not
		1085	interested in that.
		1086
		1087	Also, there have not currently been made special provisions for forking:
		1088	when you fork, you not only have to call C<ev_loop_fork> on both loops,
		1089	but you will also have to stop and restart any C<ev_embed> watchers
		1090	yourself.
		1091
		1092	Unfortunately, not all backends are embeddable, only the ones returned by
		1093	C<ev_embeddable_backends> are, which, unfortunately, does not include any
		1094	portable one.
		1095
		1096	So when you want to use this feature you will always have to be prepared
		1097	that you cannot get an embeddable loop. The recommended way to get around
		1098	this is to have a separate variables for your embeddable loop, try to
		1099	create it, and if that fails, use the normal loop for everything:
		1100
		1101	struct ev_loop *loop_hi = ev_default_init (0);
		1102	struct ev_loop *loop_lo = 0;
		1103	struct ev_embed embed;
		1104
		1105	// see if there is a chance of getting one that works
		1106	// (remember that a flags value of 0 means autodetection)
		1107	loop_lo = ev_embeddable_backends () & ev_recommended_backends ()
		1108	? ev_loop_new (ev_embeddable_backends () & ev_recommended_backends ())
		1109	: 0;
		1110
		1111	// if we got one, then embed it, otherwise default to loop_hi
		1112	if (loop_lo)
		1113	{
		1114	ev_embed_init (&embed, 0, loop_lo);
		1115	ev_embed_start (loop_hi, &embed);
		1116	}
		1117	else
		1118	loop_lo = loop_hi;
		1119
		1120	=over 4
		1121
		1122	=item ev_embed_init (ev_embed , callback, struct ev_loop loop)
		1123
		1124	=item ev_embed_set (ev_embed , callback, struct ev_loop loop)
		1125
		1126	Configures the watcher to embed the given loop, which must be embeddable.
		1127
		1128	=back
		1129
		1130
1048	=head1 OTHER FUNCTIONS	1131	=head1 OTHER FUNCTIONS
1049		1132
1050	There are some other functions of possible interest. Described. Here. Now.	1133	There are some other functions of possible interest. Described. Here. Now.
1051		1134
1052	=over 4	1135	=over 4

Diff Legend

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

Comparing libev/ev.pod (file contents): Revision 1.34 by root, Fri Nov 23 16:17:12 2007 UTC vs. Revision 1.35 by root, Fri Nov 23 19:35:09 2007 UTC

Diff Legend

Comparing libev/ev.pod (file contents):
Revision 1.34 by root, Fri Nov 23 16:17:12 2007 UTC vs.
Revision 1.35 by root, Fri Nov 23 19:35:09 2007 UTC