[ViewVC] Diff of: cvs/AnyEvent/lib/AnyEvent/Intro.pod

Comparing AnyEvent/lib/AnyEvent/Intro.pod (file contents):
Revision 1.13 by root, Mon Jun 2 09:33:43 2008 UTC vs.
Revision 1.23 by root, Mon Jun 29 20:59:08 2009 UTC

…		…
		1	=head1 NAME
		2
		3	AnyEvent::Intro - an introductory tutorial to AnyEvent
		4
1	=head1 Introduction to AnyEvent	5	=head1 Introduction to AnyEvent
2		6
3	This is a tutorial that will introduce you to the features of AnyEvent.	7	This is a tutorial that will introduce you to the features of AnyEvent.
4		8
5	The first part introduces the core AnyEvent module (after swamping you a	9	The first part introduces the core AnyEvent module (after swamping you a
6	bit in evangelism), which might already provide all you ever need.	10	bit in evangelism), which might already provide all you ever need. If you
		11	are only interested in AnyEvent's event handling capabilities, read no
		12	further.
7		13
8	The second part focuses on network programming using sockets, for which	14	The second part focuses on network programming using sockets, for which
9	AnyEvent offers a lot of support you can use.	15	AnyEvent offers a lot of support you can use, and a lot of workarounds
		16	around portability quirks.
10		17
11		18
12	=head1 What is AnyEvent?	19	=head1 What is AnyEvent?
13		20
14	If you don't care for the whys and want to see code, skip this section!	21	If you don't care for the whys and want to see code, skip this section!
101	);	108	);
102		109
103	# do something else here	110	# do something else here
104		111
105	Looks more complicated, and surely is, but the advantage of using events	112	Looks more complicated, and surely is, but the advantage of using events
106	is that your program can do something else instead of waiting for	113	is that your program can do something else instead of waiting for input
		114	(side note: combining AnyEvent with a thread package such as Coro can
		115	recoup much of the simplicity, effectively getting the best of two
		116	worlds).
		117
107	input. Waiting as in the first example is also called "blocking" because	118	Waiting as done in the first example is also called "blocking" the process
108	you "block" your process from executing anything else while you do so.	119	because you "block"/keep your process from executing anything else while
		120	you do so.
109		121
110	The second example avoids blocking, by only registering interest in a read	122	The second example avoids blocking by only registering interest in a read
111	event, which is fast and doesn't block your process. Only when read data	123	event, which is fast and doesn't block your process. Only when read data
112	is available will the callback be called, which can then proceed to read	124	is available will the callback be called, which can then proceed to read
113	the data.	125	the data.
114		126
115	The "interest" is represented by an object returned by C<< AnyEvent->io	127	The "interest" is represented by an object returned by C<< AnyEvent->io
116	>> called a "watcher" object - called like that because it "watches" your	128	>> called a "watcher" object - called like that because it "watches" your
117	file handle (or other event sources) for the event you are interested in.	129	file handle (or other event sources) for the event you are interested in.
118		130
119	In the example above, we create an I/O watcher by calling the C<<	131	In the example above, we create an I/O watcher by calling the C<<
120	AnyEvent->io >> method. Disinterest in some event is simply expressed by	132	AnyEvent->io >> method. Disinterest in some event is simply expressed
121	forgetting about the watcher, for example, by C<undef>'ing the variable it	133	by forgetting about the watcher, for example, by C<undef>'ing the only
122	is stored in. AnyEvent will automatically clean up the watcher if it is no	134	variable it is stored in. AnyEvent will automatically clean up the watcher
123	longer used, much like Perl closes your file handles if you no longer use	135	if it is no longer used, much like Perl closes your file handles if you no
124	them anywhere.	136	longer use them anywhere.
		137
		138	=head3 A short note on callbacks
		139
		140	A common issue that hits people is the problem of passing parameters
		141	to callbacks. Programmers used to languages such as C or C++ are often
		142	used to a style where one passes the address of a function (a function
		143	reference) and some data value, e.g.:
		144
		145	sub callback {
		146	my ($arg) = @_;
		147
		148	$arg->method;
		149	}
		150
		151	my $arg = ...;
		152
		153	call_me_back_later \&callback, $arg;
		154
		155	This is clumsy, as the place where behaviour is specified (when the
		156	callback is registered) is often far away from the place where behaviour
		157	is implemented. It also doesn't use Perl syntax to invoke the code. There
		158	is also an abstraction penalty to pay as one has to I<name> the callback,
		159	which often is unnecessary and leads to nonsensical or duplicated names.
		160
		161	In Perl, one can specify behaviour much more directly by using
		162	I<closures>. Closures are code blocks that take a reference to the
		163	enclosing scope(s) when they are created. This means lexical variables in
		164	scope at the time of creating the closure can simply be used inside the
		165	closure:
		166
		167	my $arg = ...;
		168
		169	call_me_back_later sub { $arg->method };
		170
		171	Under most circumstances, closures are faster, use fewer resources and
		172	result in much clearer code then the traditional approach. Faster,
		173	because parameter passing and storing them in local variables in Perl
		174	is relatively slow. Fewer resources, because closures take references
		175	to existing variables without having to create new ones, and clearer
		176	code because it is immediately obvious that the second example calls the
		177	C<method> method when the callback is invoked.
		178
		179	Apart from these, the strongest argument for using closures with AnyEvent
		180	is that AnyEvent does not allow passing parameters to the callback, so
		181	closures are the only way to achieve that in most cases :->
		182
		183
		184	=head3 A hint on debugging
		185
		186	AnyEvent does, by default, not do any argument checking. This can lead to
		187	strange and unexpected results especially if you are trying to learn your
		188	ways with AnyEvent.
		189
		190	AnyEvent supports a special "strict" mode, off by default, which does very
		191	strict argument checking, at the expense of being somewhat slower. During
		192	development, however, this mode is very useful.
		193
		194	You can enable this strict mode either by having an environment variable
		195	C<PERL_ANYEVENT_STRICT> with a true value in your environment:
		196
		197	PERL_ANYEVENT_STRICT=1 perl test.pl
		198
		199	Or you can write C<use AnyEvent::Strict> in your program, which has the
		200	same effect (do not do this in production, however).
		201
125		202
126	=head2 Condition Variables	203	=head2 Condition Variables
127		204
128	However, the above is not a fully working program, and will not work	205	Back to the I/O watcher example: The code is not yet a fully working
129	as-is. The reason is that your callback will not be invoked out of the	206	program, and will not work as-is. The reason is that your callback will
130	blue, you have to run the event loop. Also, event-based programs sometimes	207	not be invoked out of the blue, you have to run the event loop. Also,
131	have to block, too, as when there simply is nothing else to do and	208	event-based programs sometimes have to block, too, as when there simply is
132	everything waits for some events, it needs to block the process as well.	209	nothing else to do and everything waits for some events, it needs to block
		210	the process as well until new events arrive.
133		211
134	In AnyEvent, this is done using condition variables. Condition variables	212	In AnyEvent, this is done using condition variables. Condition variables
135	are named "condition variables" because they represent a condition that is	213	are named "condition variables" because they represent a condition that is
136	initially false and needs to be fulfilled.	214	initially false and needs to be fulfilled.
137		215
…		…
139	or even callbacks and many other things (and they are often called like	217	or even callbacks and many other things (and they are often called like
140	this in other frameworks). The important point is that you can create them	218	this in other frameworks). The important point is that you can create them
141	freely and later wait for them to become true.	219	freely and later wait for them to become true.
142		220
143	Condition variables have two sides - one side is the "producer" of the	221	Condition variables have two sides - one side is the "producer" of the
144	condition (whatever code detects the condition), the other side is the	222	condition (whatever code detects and flags the condition), the other side
145	"consumer" (the code that waits for that condition).	223	is the "consumer" (the code that waits for that condition).
146		224
147	In our example in the previous section, the producer is the event callback	225	In our example in the previous section, the producer is the event callback
148	and there is no consumer yet - let's change that now:	226	and there is no consumer yet - let's change that right now:
149		227
150	use AnyEvent;	228	use AnyEvent;
151		229
152	$\| = 1; print "enter your name> ";	230	$\| = 1; print "enter your name> ";
153		231
…		…
174	print "your name is $name\n";	252	print "your name is $name\n";
175		253
176	This program creates an AnyEvent condvar by calling the C<<	254	This program creates an AnyEvent condvar by calling the C<<
177	AnyEvent->condvar >> method. It then creates a watcher as usual, but	255	AnyEvent->condvar >> method. It then creates a watcher as usual, but
178	inside the callback it C<send>'s the C<$name_ready> condition variable,	256	inside the callback it C<send>'s the C<$name_ready> condition variable,
179	which causes anybody waiting on it to continue.	257	which causes whoever is waiting on it to continue.
180		258
181	The "anybody" in this case is the code that follows, which calls C<<	259	The "whoever" in this case is the code that follows, which calls C<<
182	$name_ready->recv >>: The producer calls C<send>, the consumer calls	260	$name_ready->recv >>: The producer calls C<send>, the consumer calls
183	C<recv>.	261	C<recv>.
184		262
185	If there is no C<$name> available yet, then the call to C<<	263	If there is no C<$name> available yet, then the call to C<<
186	$name_ready->recv >> will halt your program until the condition becomes	264	$name_ready->recv >> will halt your program until the condition becomes
…		…
196		274
197	my $name_ready = AnyEvent->condvar;	275	my $name_ready = AnyEvent->condvar;
198		276
199	my $wait_for_input = AnyEvent->io (	277	my $wait_for_input = AnyEvent->io (
200	fh => \*STDIN, poll => "r",	278	fh => \*STDIN, poll => "r",
201	cb => sub { $name_ready->send (scalar = <STDIN>) }	279	cb => sub { $name_ready->send (scalar <STDIN>) }
202	);	280	);
203		281
204	# do something else here	282	# do something else here
205		283
206	# now wait and fetch the name	284	# now wait and fetch the name
…		…
268	This also shows that AnyEvent is quite flexible - you didn't have anything	346	This also shows that AnyEvent is quite flexible - you didn't have anything
269	to do to make the AnyEvent watcher use Gtk2 (actually Glib) - it just	347	to do to make the AnyEvent watcher use Gtk2 (actually Glib) - it just
270	worked.	348	worked.
271		349
272	Admittedly, the example is a bit silly - who would want to read names	350	Admittedly, the example is a bit silly - who would want to read names
273	form standard input in a Gtk+ application. But imagine that instead of	351	from standard input in a Gtk+ application. But imagine that instead of
274	doing that, you would make a HTTP request in the background and display	352	doing that, you would make a HTTP request in the background and display
275	it's results. In fact, with event-based programming you can make many	353	it's results. In fact, with event-based programming you can make many
276	http-requests in parallel in your program and still provide feedback to	354	http-requests in parallel in your program and still provide feedback to
277	the user and stay interactive.	355	the user and stay interactive.
278		356
279	In the next part you will see how to do just that - by implementing an	357	And in the next part you will see how to do just that - by implementing an
280	HTTP request, on our own, with the utility modules AnyEvent comes with.	358	HTTP request, on our own, with the utility modules AnyEvent comes with.
281		359
282	Before that, however, let's briefly look at how you would write your	360	Before that, however, let's briefly look at how you would write your
283	program with using only AnyEvent, without ever calling some other event	361	program with using only AnyEvent, without ever calling some other event
284	loop's run function.	362	loop's run function.
285		363
286	In the example using condition variables, we used that, and in fact, this	364	In the example using condition variables, we used those to start waiting
287	is the solution:	365	for events, and in fact, condition variables are the solution:
288		366
289	my $quit_program = AnyEvent->condvar;	367	my $quit_program = AnyEvent->condvar;
290		368
291	# create AnyEvent watchers (or not) here	369	# create AnyEvent watchers (or not) here
292		370
293	$quit_program->recv;	371	$quit_program->recv;
294		372
295	If any of your watcher callbacks decide to quit, they can simply call	373	If any of your watcher callbacks decide to quit (this is often
		374	called an "unloop" in other frameworks), they can simply call C<<
296	C<< $quit_program->send >>. Of course, they could also decide not to and	375	$quit_program->send >>. Of course, they could also decide not to and
297	simply call C<exit> instead, or they could decide not to quit, ever (e.g.	376	simply call C<exit> instead, or they could decide not to quit, ever (e.g.
298	in a long-running daemon program).	377	in a long-running daemon program).
299		378
300	In that case, you can simply use:	379	If you don't need some clean quit functionality and just want to run the
		380	event loop, you can simply do this:
301		381
302	AnyEvent->condvar->recv;	382	AnyEvent->condvar->recv;
303		383
304	And this is, in fact, closest to the idea of a main loop run function that	384	And this is, in fact, closest to the idea of a main loop run function that
305	AnyEvent offers.	385	AnyEvent offers.
…		…
337		417
338	# now wait till our time has come	418	# now wait till our time has come
339	$cv->recv;	419	$cv->recv;
340		420
341	Unlike I/O watchers, timers are only interested in the amount of seconds	421	Unlike I/O watchers, timers are only interested in the amount of seconds
342	they have to wait. When that amount of time has passed, AnyEvent will	422	they have to wait. When (at least) that amount of time has passed,
343	invoke your callback.	423	AnyEvent will invoke your callback.
344		424
345	Unlike I/O watchers, which will call your callback as many times as there	425	Unlike I/O watchers, which will call your callback as many times as there
346	is data available, timers are one-shot: after they have "fired" once and	426	is data available, timers are normally one-shot: after they have "fired"
347	invoked your callback, they are dead and no longer do anything.	427	once and invoked your callback, they are dead and no longer do anything.
348		428
349	To get a repeating timer, such as a timer firing roughly once per second,	429	To get a repeating timer, such as a timer firing roughly once per second,
350	you have to recreate it:	430	you can specify an C<interval> parameter:
351		431
352	use AnyEvent;	432	my $once_per_second = AnyEvent->timer (
353		433	after => 0, # first invoke ASAP
354	my $time_watcher;	434	interval => 1, # then invoke every second
355		435	cb => sub { # the callback to invoke
356	sub once_per_second {	436	$cv->send;
357	print "tick\n";
358		437	},
359	# (re-)create the watcher
360	$time_watcher = AnyEvent->timer (
361	after => 1,
362	cb => \&once_per_second,
363	);	438	);
364	}
365
366	# now start the timer
367	once_per_second;
368
369	Having to recreate your timer is a restriction put on AnyEvent that is
370	present in most event libraries it uses. It is so annoying that some
371	future version might work around this limitation, but right now, it's the
372	only way to do repeating timers.
373
374	Fortunately most timers aren't really repeating but specify timeouts of
375	some sort.
376		439
377	=head3 More esoteric sources	440	=head3 More esoteric sources
378		441
379	AnyEvent also has some other, more esoteric event sources you can tap	442	AnyEvent also has some other, more esoteric event sources you can tap
380	into: signal and child watchers.	443	into: signal, child and idle watchers.
381		444
382	Signal watchers can be used to wait for "signal events", which simply	445	Signal watchers can be used to wait for "signal events", which simply
383	means your process got send a signal (such as C<SIGTERM> or C<SIGUSR1>).	446	means your process got send a signal (such as C<SIGTERM> or C<SIGUSR1>).
384		447
385	Process watchers wait for a child process to exit. They are useful when	448	Child-process watchers wait for a child process to exit. They are useful
386	you fork a separate process and need to know when it exits, but you do not	449	when you fork a separate process and need to know when it exits, but you
387	wait for that by blocking.	450	do not wait for that by blocking.
388		451
		452	Idle watchers invoke their callback when the event loop has handled all
		453	outstanding events, polled for new events and didn't find any, i.e., when
		454	your process is otherwise idle. They are useful if you want to do some
		455	non-trivial data processing that can be done when your program doesn't
		456	have anything better to do.
		457
389	Both watcher types are described in detail in the main L<AnyEvent> manual	458	All these watcher types are described in detail in the main L<AnyEvent>
390	page.	459	manual page.
391		460
		461	Sometimes you also need to know what the current time is: C<<
		462	AnyEvent->now >> returns the time the event toolkit uses to schedule
		463	relative timers, and is usually what you want. It is often cached (which
		464	means it can be a bit outdated). In that case, you can use the more costly
		465	C<< AnyEvent->time >> method which will ask your operating system for the
		466	current time, which is slower, but also more up to date.
392		467
393	=head1 Network programming and AnyEvent	468	=head1 Network programming and AnyEvent
394		469
395	So far you have seen how to register event watchers and handle events.	470	So far you have seen how to register event watchers and handle events.
396		471
397	This is a great foundation to write network clients and servers, and might be	472	This is a great foundation to write network clients and servers, and might
398	all that your module (or program) ever requires, but writing your own I/O	473	be all that your module (or program) ever requires, but writing your own
399	buffering again and again becomes tedious, not to mention that it attracts	474	I/O buffering again and again becomes tedious, not to mention that it
400	errors.	475	attracts errors.
401		476
402	While the core L<AnyEvent> module is still small and self-contained,	477	While the core L<AnyEvent> module is still small and self-contained,
403	the distribution comes with some very useful utility modules such as	478	the distribution comes with some very useful utility modules such as
404	L<AnyEvent::Handle>, L<AnyEvent::DNS> and L<AnyEvent::Socket>. These can	479	L<AnyEvent::Handle>, L<AnyEvent::DNS> and L<AnyEvent::Socket>. These can
405	make your life as non-blocking network programmer a lot easier.	480	make your life as non-blocking network programmer a lot easier.
…		…
413	a great way to do other DNS resolution tasks, such as reverse lookups of	488	a great way to do other DNS resolution tasks, such as reverse lookups of
414	IP addresses for log files.	489	IP addresses for log files.
415		490
416	=head2 L<AnyEvent::Handle>	491	=head2 L<AnyEvent::Handle>
417		492
418	This module handles non-blocking IO on file handles in an event based	493	This module handles non-blocking IO on (socket-, pipe- etc.) file handles
419	manner. It provides a wrapper object around your file handle that provides	494	in an event based manner. It provides a wrapper object around your file
420	queueing and buffering of incoming and outgoing data for you.	495	handle that provides queueing and buffering of incoming and outgoing data
		496	for you.
421		497
422	It also implements the most common data formats, such as text lines, or	498	It also implements the most common data formats, such as text lines, or
423	fixed and variable-width data blocks.	499	fixed and variable-width data blocks.
424		500
425	=head2 L<AnyEvent::Socket>	501	=head2 L<AnyEvent::Socket>
…		…
443	to your program? That C<WSAEINPROGRESS> means your C<connect> call was	519	to your program? That C<WSAEINPROGRESS> means your C<connect> call was
444	ignored instead of being in progress? AnyEvent::Socket works around all of	520	ignored instead of being in progress? AnyEvent::Socket works around all of
445	these Windows/Perl bugs for you).	521	these Windows/Perl bugs for you).
446		522
447	=head2 Implementing a parallel finger client with non-blocking connects	523	=head2 Implementing a parallel finger client with non-blocking connects
		524	and AnyEvent::Socket
448		525
449	The finger protocol is one of the simplest protocols in use on the	526	The finger protocol is one of the simplest protocols in use on the
450	internet. Or in use in the past, as almost nobody uses it anymore.	527	internet. Or in use in the past, as almost nobody uses it anymore.
451		528
452	It works by connecting to the finger port on another host, writing a	529	It works by connecting to the finger port on another host, writing a
453	single line with a user name and then reading the finger response, as	530	single line with a user name and then reading the finger response, as
454	specified by that user. OK, RFC 1288 specifies a vastly more complex	531	specified by that user. OK, RFC 1288 specifies a vastly more complex
455	protocol, but it basically boils down to this:	532	protocol, but it basically boils down to this:
456		533
457	# telnet idsoftware.com finger	534	# telnet kernel.org finger
458	Trying 192.246.40.37...	535	Trying 204.152.191.37...
459	Connected to idsoftware.com (192.246.40.37).	536	Connected to kernel.org (204.152.191.37).
460	Escape character is '^]'.	537	Escape character is '^]'.
461	johnc	538
462	Welcome to id Software's Finger Service V1.5!	539	The latest stable version of the Linux kernel is: [...]
463
464	[...]
465	Now on the web:
466	[...]
467
468	Connection closed by foreign host.	540	Connection closed by foreign host.
469		541
470	"Now on the web..." yeah, I<was> used indeed, but at least the finger	542	So let's write a little AnyEvent function that makes a finger request:
471	daemon still works, so let's write a little AnyEvent function that makes a
472	finger request:
473		543
474	use AnyEvent;	544	use AnyEvent;
475	use AnyEvent::Socket;	545	use AnyEvent::Socket;
476		546
477	sub finger($$) {	547	sub finger($$) {
…		…
542	socket handle as first argument, otherwise, nothing will be passed to our	612	socket handle as first argument, otherwise, nothing will be passed to our
543	callback. The important point is that it will always be called as soon as	613	callback. The important point is that it will always be called as soon as
544	the outcome of the TCP connect is known.	614	the outcome of the TCP connect is known.
545		615
546	This style of programming is also called "continuation style": the	616	This style of programming is also called "continuation style": the
547	"continuation" is simply the way the program continues - normally, a	617	"continuation" is simply the way the program continues - normally at the
548	program continues at the next line after some statement (the exception	618	next line after some statement (the exception is loops or things like
549	is loops or things like C<return>). When we are interested in events,	619	C<return>). When we are interested in events, however, we instead specify
550	however, we instead specify the "continuation" of our program by passing a	620	the "continuation" of our program by passing a closure, which makes that
551	closure, which makes that closure the "continuation" of the program. The	621	closure the "continuation" of the program.
		622
552	C<tcp_connect> call is like saying "return now, and when the connection is	623	The C<tcp_connect> call is like saying "return now, and when the
553	established or it failed, continue there".	624	connection is established or it failed, continue there".
554		625
555	Now let's look at the callback/closure in more detail:	626	Now let's look at the callback/closure in more detail:
556		627
557	# the callback receives the socket handle - or nothing	628	# the callback receives the socket handle - or nothing
558	my ($fh) = @_	629	my ($fh) = @_
…		…
570	report the results to anybody, certainly not the caller of our C<finger>	641	report the results to anybody, certainly not the caller of our C<finger>
571	function, and most event loops continue even after a C<die>!	642	function, and most event loops continue even after a C<die>!
572		643
573	This is why we instead C<return>, but also call C<< $cv->send >> without	644	This is why we instead C<return>, but also call C<< $cv->send >> without
574	any arguments to signal to the condvar consumer that something bad has	645	any arguments to signal to the condvar consumer that something bad has
575	happened. The return value of C<< $cv->send >> is irrelevant, as is the	646	happened. The return value of C<< $cv->send >> is irrelevant, as is
576	return value of our callback. The return statement is simply used for the	647	the return value of our callback. The C<return> statement is simply
577	side effect of, well, returning immediately from the callback. Checking	648	used for the side effect of, well, returning immediately from the
578	for errors and handling them this way is very common, which is why this	649	callback. Checking for errors and handling them this way is very common,
579	compact idiom is so handy.	650	which is why this compact idiom is so handy.
580		651
581	As the next step in the finger protocol, we send the username to the	652	As the next step in the finger protocol, we send the username to the
582	finger daemon on the other side of our connection:	653	finger daemon on the other side of our connection (the kernel.org finger
		654	service doesn't actually wait for a username, but the net is running out
		655	of finger servers fast):
583		656
584	syswrite $fh, "$user\015\012";	657	syswrite $fh, "$user\015\012";
585		658
586	Note that this isn't 100% clean socket programming - the socket could,	659	Note that this isn't 100% clean socket programming - the socket could,
587	for whatever reasons, not accept our data. When writing a small amount	660	for whatever reasons, not accept our data. When writing a small amount
…		…
605	variable, but in a local one - if the callback returns, it would normally	678	variable, but in a local one - if the callback returns, it would normally
606	destroy the variable and its contents, which would in turn unregister our	679	destroy the variable and its contents, which would in turn unregister our
607	watcher.	680	watcher.
608		681
609	To avoid that, we C<undef>ine the variable in the watcher callback. This	682	To avoid that, we C<undef>ine the variable in the watcher callback. This
610	means that, when the C<tcp_connect> callback returns, that perl thinks	683	means that, when the C<tcp_connect> callback returns, perl thinks (quite
611	(quite correctly) that the read watcher is still in use - namely in the	684	correctly) that the read watcher is still in use - namely in the callback,
612	callback.	685	and thus keeps it alive even if nothing else in the program refers to it
		686	anymore (it is much like Baron Münchhausen keeping himself from dying by
		687	pulling himself out of a swamp).
613		688
614	The trick, however, is that instead of:	689	The trick, however, is that instead of:
615		690
616	my $read_watcher = AnyEvent->io (...	691	my $read_watcher = AnyEvent->io (...
617		692
…		…
636	my $len = sysread $fh, $response, 1024, length $response;	711	my $len = sysread $fh, $response, 1024, length $response;
637		712
638	if ($len <= 0) {	713	if ($len <= 0) {
639		714
640	Note that C<sysread> has the ability to append data it reads to a scalar,	715	Note that C<sysread> has the ability to append data it reads to a scalar,
641	by specifying an offset, which is what we make good use of in this	716	by specifying an offset, a feature of which we make good use of in this
642	example.	717	example.
643		718
644	When C<sysread> indicates we are done, the callback C<undef>ines	719	When C<sysread> indicates we are done, the callback C<undef>ines
645	the watcher and then C<send>'s the response data to the condition	720	the watcher and then C<send>'s the response data to the condition
646	variable. All this has the following effects:	721	variable. All this has the following effects:
…		…
660	But the main advantage is that we can not only run this finger function in	735	But the main advantage is that we can not only run this finger function in
661	the background, we even can run multiple sessions in parallel, like this:	736	the background, we even can run multiple sessions in parallel, like this:
662		737
663	my $f1 = finger "trouble", "noc.dfn.de"; # check for trouble tickets	738	my $f1 = finger "trouble", "noc.dfn.de"; # check for trouble tickets
664	my $f2 = finger "1736" , "noc.dfn.de"; # fetch ticket 1736	739	my $f2 = finger "1736" , "noc.dfn.de"; # fetch ticket 1736
665	my $f3 = finger "johnc", "idsoftware.com"; # finger john	740	my $f3 = finger "hpa" , "kernel.org"; # finger hpa
666		741
667	print "trouble tickets:\n", $f1->recv, "\n";	742	print "trouble tickets:\n" , $f1->recv, "\n";
668	print "trouble ticket #1736:\n", $f2->recv, "\n";	743	print "trouble ticket #1736:\n", $f2->recv, "\n";
669	print "john carmacks finger file: ", $f3->recv, "\n";	744	print "kernel release info: " , $f3->recv, "\n";
670		745
671	It doesn't look like it, but in fact all three requests run in	746	It doesn't look like it, but in fact all three requests run in
672	parallel. The code waits for the first finger request to finish first, but	747	parallel. The code waits for the first finger request to finish first, but
673	that doesn't keep it from executing them parallel: when the first C<recv>	748	that doesn't keep it from executing them parallel: when the first C<recv>
674	call sees that the data isn't ready yet, it serves events for all three	749	call sees that the data isn't ready yet, it serves events for all three
…		…
702	How you implement it is a matter of taste - if you expect your function to	777	How you implement it is a matter of taste - if you expect your function to
703	be used mainly in an event-based program you would normally prefer to pass	778	be used mainly in an event-based program you would normally prefer to pass
704	a callback directly. If you write a module and expect your users to use	779	a callback directly. If you write a module and expect your users to use
705	it "synchronously" often (for example, a simple http-get script would not	780	it "synchronously" often (for example, a simple http-get script would not
706	really care much for events), then you would use a condition variable and	781	really care much for events), then you would use a condition variable and
707	tell them "simply ->recv the data".	782	tell them "simply C<< ->recv >> the data".
708		783
709	=head3 Problems with the implementation and how to fix them	784	=head3 Problems with the implementation and how to fix them
710		785
711	To make this example more real-world-ready, we would not only implement	786	To make this example more real-world-ready, we would not only implement
712	some write buffering (for the paranoid), but we would also have to handle	787	some write buffering (for the paranoid, or maybe denial-of-service aware
713	timeouts and maybe protocol errors.	788	security expert), but we would also have to handle timeouts and maybe
		789	protocol errors.
714		790
715	Doing this quickly gets unwieldy, which is why we introduce	791	Doing this quickly gets unwieldy, which is why we introduce
716	L<AnyEvent::Handle> in the next section, which takes care of all these	792	L<AnyEvent::Handle> in the next section, which takes care of all these
717	details for you and let's you concentrate on the actual protocol.	793	details for you and let's you concentrate on the actual protocol.
718		794
719		795
720	=head2 Implementing simple HTTP and HTTPS GET requests with AnyEvent::Handle	796	=head2 Implementing simple HTTP and HTTPS GET requests with AnyEvent::Handle
721		797
722	The L<AnyEvent::Handle> module has been hyped quite a bit so far, so let's	798	The L<AnyEvent::Handle> module has been hyped quite a bit in this document
723	see what it really offers.	799	so far, so let's see what it really offers.
724		800
725	As finger is such a simple protocol, let's try something slightly more	801	As finger is such a simple protocol, let's try something slightly more
726	complicated: HTTP/1.0.	802	complicated: HTTP/1.0.
727		803
728	An HTTP GET request works by sending a single request line that indicates	804	An HTTP GET request works by sending a single request line that indicates
…		…
879	of the headers to the server.	955	of the headers to the server.
880		956
881	The more interesting question is why the method is called C<push_write>	957	The more interesting question is why the method is called C<push_write>
882	and not just write. The reason is that you can I<always> add some write	958	and not just write. The reason is that you can I<always> add some write
883	data without blocking, and to do this, AnyEvent::Handle needs some write	959	data without blocking, and to do this, AnyEvent::Handle needs some write
884	queue internally - and C<push_write> simply pushes some data at the end of	960	queue internally - and C<push_write> simply pushes some data onto the end
885	that queue, just like Perl's C<push> pushes data at the end of an array.	961	of that queue, just like Perl's C<push> pushes data onto the end of an
		962	array.
886		963
887	The deeper reason is that at some point in the future, there might	964	The deeper reason is that at some point in the future, there might
888	be C<unshift_write> as well, and in any case, we will shortly meet	965	be C<unshift_write> as well, and in any case, we will shortly meet
889	C<push_read> and C<unshift_read>, and it's usually easiest if all those	966	C<push_read> and C<unshift_read>, and it's usually easiest to remember if
890	functions have some symmetry in their name.	967	all those functions have some symmetry in their name.
891		968
892	If C<push_write> is called with more than one argument, then you can even	969	If C<push_write> is called with more than one argument, then you can even
893	do I<formatted> I/O, which simply means your data will be transformed in	970	do I<formatted> I/O, which simply means your data will be transformed in
894	some ways. For example, this would JSON-encode your data before pushing it	971	some ways. For example, this would JSON-encode your data before pushing it
895	to the write queue:	972	to the write queue:
…		…
897	$handle->push_write (json => [1, 2, 3]);	974	$handle->push_write (json => [1, 2, 3]);
898		975
899	Apart from that, this pretty much summarises the write queue, there is	976	Apart from that, this pretty much summarises the write queue, there is
900	little else to it.	977	little else to it.
901		978
902	Reading the response if far more interesting:	979	Reading the response is far more interesting, because it involves the more
		980	powerful and complex I<read queue>:
903		981
904	=head3 The read queue	982	=head3 The read queue
905		983
906	The response consists of three parts: a single line of response status, a	984	The response consists of three parts: a single line with the response
907	single paragraph of headers ended by an empty line, and the request body,	985	status, a single paragraph of headers ended by an empty line, and the
908	which is simply the remaining data on that connection.	986	request body, which is simply the remaining data on that connection.
909		987
910	For the first two, we push two read requests onto the read queue:	988	For the first two, we push two read requests onto the read queue:
911		989
912	# now fetch response status line	990	# now fetch response status line
913	$handle->push_read (line => sub {	991	$handle->push_read (line => sub {
…		…
919	$handle->push_read (line => "\015\012\015\012", sub {	997	$handle->push_read (line => "\015\012\015\012", sub {
920	my ($handle, $line) = @_;	998	my ($handle, $line) = @_;
921	$header = $line;	999	$header = $line;
922	});	1000	});
923		1001
924	While one can simply push a single callback to the queue, I<formatted> I/O	1002	While one can simply push a single callback to parse the data the
925	really comes to out advantage here, as there is a ready-made "read line"	1003	queue, I<formatted> I/O really comes to our advantage here, as there
926	read type. The first read expects a single line, ended by C<\015\012> (the	1004	is a ready-made "read line" read type. The first read expects a single
927	standard end-of-line marker in internet protocols).	1005	line, ended by C<\015\012> (the standard end-of-line marker in internet
		1006	protocols).
928		1007
929	The second "line" is actually a single paragraph - instead of reading it	1008	The second "line" is actually a single paragraph - instead of reading it
930	line by line we tell C<push_read> that the end-of-line marker is really	1009	line by line we tell C<push_read> that the end-of-line marker is really
931	C<\015\012\015\012>, which is an empty line. The result is that the whole	1010	C<\015\012\015\012>, which is an empty line. The result is that the whole
932	header paragraph will be treated as a single line and read. The word	1011	header paragraph will be treated as a single line and read. The word
…		…
950	header have been read. The C<on_read> callback could actually have been	1029	header have been read. The C<on_read> callback could actually have been
951	specified when constructing the object, but doing it this way preserves	1030	specified when constructing the object, but doing it this way preserves
952	logical ordering.	1031	logical ordering.
953		1032
954	The read callback simply adds the current read buffer to it's C<$body>	1033	The read callback simply adds the current read buffer to it's C<$body>
955	variable and, most importantly, I<empties> it by assign the empty string	1034	variable and, most importantly, I<empties> the buffer by assigning the
956	to it.	1035	empty string to it.
957		1036
958	After AnyEvent::Handle has been so instructed, it will now handle incoming	1037	After AnyEvent::Handle has been so instructed, it will handle incoming
959	data according to these instructions - if all goes well, the callback will	1038	data according to these instructions - if all goes well, the callback will
960	be invoked with the response data, if not, it will get an error.	1039	be invoked with the response data, if not, it will get an error.
961		1040
962	In general, you get pipelining very easy with AnyEvent::Handle: If	1041	In general, you can implement pipelining (a semi-advanced feature of many
963	you have a protocol with a request/response structure, your request	1042	protocols) very easy with AnyEvent::Handle: If you have a protocol with a
964	methods/functions will all look like this (simplified):	1043	request/response structure, your request methods/functions will all look
		1044	like this (simplified):
965		1045
966	sub request {	1046	sub request {
967		1047
968	# send the request to the server	1048	# send the request to the server
969	$handle->push_write (...);	1049	$handle->push_write (...);
970		1050
971	# push some response handlers	1051	# push some response handlers
972	$handle->push_read (...);	1052	$handle->push_read (...);
973	}	1053	}
974		1054
975	=head3 Using it	1055	This means you can queue as many requests as you want, and while
		1056	AnyEvent::Handle goes through its read queue to handle the response data,
		1057	the other side can work on the next request - queueing the request just
		1058	appends some data to the write queue and installs a handler to be called
		1059	later.
976		1060
		1061	You might ask yourself how to handle decisions you can only make I<after>
		1062	you have received some data (such as handling a short error response or a
		1063	long and differently-formatted response). The answer to this problem is
		1064	C<unshift_read>, which we will introduce together with an example in the
		1065	coming sections.
		1066
		1067	=head3 Using C<http_get>
		1068
977	And here is how you would use it:	1069	Finally, here is how you would use C<http_get>:
978		1070
979	http_get "www.google.com", "/", sub {	1071	http_get "www.google.com", "/", sub {
980	my ($response, $header, $body) = @_;	1072	my ($response, $header, $body) = @_;
981		1073
982	print	1074	print
…		…
993	correctly, let's change our C<http_get> function into a function that	1085	correctly, let's change our C<http_get> function into a function that
994	speaks HTTPS instead.	1086	speaks HTTPS instead.
995		1087
996	HTTPS is, quite simply, a standard TLS connection (B<T>ransport B<L>ayer	1088	HTTPS is, quite simply, a standard TLS connection (B<T>ransport B<L>ayer
997	B<S>ecurity is the official name for what most people refer to as C<SSL>)	1089	B<S>ecurity is the official name for what most people refer to as C<SSL>)
998	that contains standard HTTP protocol exchanges. The other difference to	1090	that contains standard HTTP protocol exchanges. The only other difference
999	HTTP is that it uses port C<443> instead of port C<80>.	1091	to HTTP is that by default it uses port C<443> instead of port C<80>.
1000		1092
1001	To implement these two differences we need two tiny changes, first, in the C<tcp_connect> call	1093	To implement these two differences we need two tiny changes, first, in the
1002	we replace C<http> by C<https>):	1094	C<tcp_connect> call we replace C<http> by C<https>):
1003		1095
1004	tcp_connect $host, "https", sub { ...	1096	tcp_connect $host, "https", sub { ...
1005		1097
1006	The other change deals with TLS, which is something L<AnyEvent::Handle>	1098	The other change deals with TLS, which is something L<AnyEvent::Handle>
1007	does for us, as long as I<you> made sure that the L<Net::SSLeay> module is	1099	does for us, as long as I<you> made sure that the L<Net::SSLeay> module
1008	around. To enable TLS with L<AnyEvent::Handle>, we simply pass an addition	1100	is around. To enable TLS with L<AnyEvent::Handle>, we simply pass an
1009	C<tls> parameter to the call to C<AnyEvent::Handle::new>:	1101	additional C<tls> parameter to the call to C<AnyEvent::Handle::new>:
1010		1102
1011	tls => "connect",	1103	tls => "connect",
1012		1104
1013	Specifying C<tls> enables TLS, and the argument specifies whether	1105	Specifying C<tls> enables TLS, and the argument specifies whether
1014	AnyEvent::Handle is the server side ("accept") or the client side	1106	AnyEvent::Handle is the server side ("accept") or the client side
1015	("connect") for the TLS connection, as unlike TCP, there is a clear	1107	("connect") for the TLS connection, as unlike TCP, there is a clear
1016	server/client relationship in TLS.	1108	server/client relationship in TLS.
1017		1109
		1110	That's all.
		1111
1018	That's all. Of course, all this should be handled transparently by	1112	Of course, all this should be handled transparently by C<http_get>
1019	C<http_get> after parsing the URL. See the part about exercising your	1113	after parsing the URL. If you need this, see the part about exercising
1020	inspiration earlier in this document.	1114	your inspiration earlier in this document. You could also use the
		1115	L<AnyEvent::HTTP> module from CPAN, which implements all this and works
		1116	around a lot of quirks for you, too.
1021		1117
1022	=head3 The read queue - revisited	1118	=head3 The read queue - revisited
1023		1119
1024	HTTP always uses the same structure in its responses, but many protocols	1120	HTTP always uses the same structure in its responses, but many protocols
1025	require parsing responses different depending on the response itself.	1121	require parsing responses differently depending on the response itself.
1026		1122
1027	For example, in SMTP, you normally get a single response line:	1123	For example, in SMTP, you normally get a single response line:
1028		1124
1029	220 mail.example.net Neverusesendmail 8.8.8 <mailme@example.net>	1125	220 mail.example.net Neverusesendmail 8.8.8 <mailme@example.net>
1030		1126
…		…
1033	220-mail.example.net Neverusesendmail 8.8.8 <mailme@example.net>	1129	220-mail.example.net Neverusesendmail 8.8.8 <mailme@example.net>
1034	220-hey guys	1130	220-hey guys
1035	220 my response is longer than yours	1131	220 my response is longer than yours
1036		1132
1037	To handle this, we need C<unshift_read>. As the name (hopefully) implies,	1133	To handle this, we need C<unshift_read>. As the name (hopefully) implies,
1038	C<unshift_read> will not append your read request tot he end of the read	1134	C<unshift_read> will not append your read request to the end of the read
1039	queue, but instead it will prepend it to the queue.	1135	queue, but instead it will prepend it to the queue.
1040		1136
1041	This is useful for this this situation: You push your response-line read	1137	This is useful in the situation above: Just push your response-line read
1042	request when sending the SMTP command, and when handling it, you look at	1138	request when sending the SMTP command, and when handling it, you look at
1043	the line to see if more is to come, and C<unshift_read> another reader,	1139	the line to see if more is to come, and C<unshift_read> another reader
1044	like this:	1140	callback if required, like this:
1045		1141
1046	my $response; # response lines end up in here	1142	my $response; # response lines end up in here
1047		1143
1048	my $read_response; $read_response = sub {	1144	my $read_response; $read_response = sub {
1049	my ($handle, $line) = @_;	1145	my ($handle, $line) = @_;
…		…
1067		1163
1068	$handle->push_read (line => $read_response);	1164	$handle->push_read (line => $read_response);
1069		1165
1070	This recipe can be used for all similar parsing problems, for example in	1166	This recipe can be used for all similar parsing problems, for example in
1071	NNTP, the response code to some commands indicates that more data will be	1167	NNTP, the response code to some commands indicates that more data will be
1072	sent.	1168	sent:
1073		1169
1074	=head1 AUTHORS	1170	$handle->push_write ("article 42");
		1171
		1172	# read response line
		1173	$handle->push_read (line => sub {
		1174	my ($handle, $status) = @_;
		1175
		1176	# article data following?
		1177	if ($status =~ /^2/) {
		1178	# yes, read article body
		1179
		1180	$handle->unshift_read (line => "\012.\015\012", sub {
		1181	my ($handle, $body) = @_;
		1182
		1183	$finish->($status, $body);
		1184	});
		1185
		1186	} else {
		1187	# some error occured, no article data
		1188
		1189	$finish->($status);
		1190	}
		1191	}
		1192
		1193	=head3 Your own read queue handler
		1194
		1195	Sometimes, your protocol doesn't play nice and uses lines or chunks of
		1196	data not formatted in a way handled by AnyEvent::Handle out of the box. In
		1197	this case you have to implement your own read parser.
		1198
		1199	To make up a contorted example, imagine you are looking for an even
		1200	number of characters followed by a colon (":"). Also imagine that
		1201	AnyEvent::Handle had no C<regex> read type which could be used, so you'd
		1202	had to do it manually.
		1203
		1204	To implement a read handler for this, you would C<push_read> (or
		1205	C<unshift_read>) just a single code reference.
		1206
		1207	This code reference will then be called each time there is (new) data
		1208	available in the read buffer, and is expected to either successfully
		1209	eat/consume some of that data (and return true) or to return false to
		1210	indicate that it wants to be called again.
		1211
		1212	If the code reference returns true, then it will be removed from the
		1213	read queue (because it has parsed/consumed whatever it was supposed to
		1214	consume), otherwise it stays in the front of it.
		1215
		1216	The example above could be coded like this:
		1217
		1218	$handle->push_read (sub {
		1219	my ($handle) = @_;
		1220
		1221	# check for even number of characters + ":"
		1222	# and remove the data if a match is found.
		1223	# if not, return false (actually nothing)
		1224
		1225	$handle->{rbuf} =~ s/^( (?:..)* ) ://x
		1226	or return;
		1227
		1228	# we got some data in $1, pass it to whoever wants it
		1229	$finish->($1);
		1230
		1231	# and return true to indicate we are done
		1232	1
		1233	});
		1234
		1235	This concludes our little tutorial.
		1236
		1237	=head1 Where to go from here?
		1238
		1239	This introduction should have explained the key concepts of L<AnyEvent>
		1240	- event watchers and condition variables, L<AnyEvent::Socket> - basic
		1241	networking utilities, and L<AnyEvent::Handle> - a nice wrapper around
		1242	handles.
		1243
		1244	You could either start coding stuff right away, look at those manual
		1245	pages for the gory details, or roam CPAN for other AnyEvent modules (such
		1246	as L<AnyEvent::IRC> or L<AnyEvent::HTTP>) to see more code examples (or
		1247	simply to use them).
		1248
		1249	If you need a protocol that doesn't have an implementation using AnyEvent,
		1250	remember that you can mix AnyEvent with one other event framework, such as
		1251	L<POE>, so you can always use AnyEvent for your own tasks plus modules of
		1252	one other event framework to fill any gaps.
		1253
		1254	And last not least, you could also look at L<Coro>, especially
		1255	L<Coro::AnyEvent>, to see how you can turn event-based programming from
		1256	callback style back to the usual imperative style (also called "inversion
		1257	of control" - AnyEvent calls I<you>, but Coro lets I<you> call AnyEvent).
		1258
		1259	=head1 Authors
1075		1260
1076	Robin Redeker C<< <elmex at ta-sa.org> >>, Marc Lehmann <schmorp@schmorp.de>.	1261	Robin Redeker C<< <elmex at ta-sa.org> >>, Marc Lehmann <schmorp@schmorp.de>.
1077		1262

Diff Legend

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

Comparing AnyEvent/lib/AnyEvent/Intro.pod (file contents): Revision 1.13 by root, Mon Jun 2 09:33:43 2008 UTC vs. Revision 1.23 by root, Mon Jun 29 20:59:08 2009 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent/Intro.pod (file contents):
Revision 1.13 by root, Mon Jun 2 09:33:43 2008 UTC vs.
Revision 1.23 by root, Mon Jun 29 20:59:08 2009 UTC