lib/AnyEvent/Intro.pod

=head1 Network Programming with AnyEvent

This is a tutorial that will introduce you to AnyEvent by writing a small
event-based program.

=head2 Introduction

AnyEvent is first of all just a framework for multiple event loops. It is
a thin abstraction layer above all kinds of event loops. Its main purpose
is to move the choice of the event loop (whether it is Glib, Qt, EV or
Event, or even something else, see also L<AnyEvent>) from the module
author to the program author using the module.

A typical problem with modules such as L<Net::IRC> is that they come with
their own event loop. In L<Net::IRC>, the program who uses it needs to
start the event loop of L<Net::IRC>. That means that one cannot integrate
this module into a L<Gtk2> GUI for instance, as that module, too, enforces
the use of its own event loop.

Another example is L<LWP>: it provides no event interface at all. It's a
pure blocking HTTP (and FTP etc.) client library, which usually means that
you either have to start a thread or have to fork for a HTTP request, or
use L<Coro::LWP>, if you want to do something else while waiting for the
request to finish.

The motivation behind these designs is often that a module doesn't want to
depend on some complicated XS-module (Net::IRC), or that it doesn't want
to force the user to use some specific event loop (LWP).

L<AnyEvent> solves this dilemma, by B<not> forcing module authors to:

=over 4

=item 1. Write their own event loop.

=item 2. Choose one fixed event loop.

=back

If the module author uses L<AnyEvent> for all his event needs (IO events, timers,
signals, ...) all other modules can just use his module and don't have to choose
an event loop or adapt to his event loop. The choice of the event loop is ultimately
made by the program author who uses all the modules and writes the main
program. And even there he doesn't have to choose, he can just ask L<AnyEvent>
to choose any available event loop for him.

And while AnyEvent can make good use of event loops written in C, such as
EV or Glib, it also comes with a fast pure-perl event loop implementation
on its own, which means module authors can rely on AnyEvent without
fearing a worrisome dependency on some XS module.

Read more about this in the main documentation of the L<AnyEvent> module.

=head2 Network programming and AnyEvent

However, AnyEvent is not just a simple abstraction anymore. While the core
L<AnyEvent> module is still small and self-contained, the distribution
comes with some very useful utility modules such as L<AnyEvent::Handle>,
L<AnyEvent::DNS> and L<AnyEvent::Socket>. These can make your life as
non-blocking network programmer a lot easier.

Here is an introduction into these three submodules:

=head3 L<AnyEvent::Handle>

This module handles non-blocking IO on file handles in an event based
manner. It provides a wrapper object around your file handle that provides
queueing and buffering of incoming and outgoing data for you.

More about this later.

=head3 L<AnyEvent::Socket>

This module provides you with functions that handle socket creation
and IP address magic. The two main functions are C<tcp_connect> and
C<tcp_server>. The former will connect a (streaming) socket to an internet
host for you and the later will make a server socket for you, to accept
connections.

This module also comes with transparent IPv6 support, this means: If you
write your programs with this module, you will be IPv6 ready without doing
anything further.

It also works around a lot of portability quirks (especially on the
windows platform), which makes it even easier to write your programs in a
portable way.

=head3 L<AnyEvent::DNS>

This module allows fully asynchronous DNS resolution. It is used mainly
by L<AnyEvent::Socket> to resolve hostnames and service ports, but is a
great way to do other DNS resolution tasks, such as reverse lookups of IP
addresses for log files.

=head2 First experiments with AnyEvent::Handle

Now let's start with something simple: a program that reads from standard
input in a non-blocking way, that is, in a way that lets your program do
other things while it is waiting for input.

First, the full program listing:

   #!/usr/bin/perl

   use AnyEvent;
   use AnyEvent::Handle;

   my $end_prog = AnyEvent->condvar;

   my $handle =
      AnyEvent::Handle->new (
         fh => \*STDIN,
         on_eof => sub {
            print "received EOF, exiting...\n";
            $end_prog->broadcast;
         },
         on_error => sub {
            print "error while reading from STDIN: $!\n";
            $end_prog->broadcast;
         }
      );

   $handle->push_read (sub {
      my ($handle) = @_;

      if ($handle->rbuf =~ s/^.*?\bend\b.*$//s) {
         print "got 'end', existing...\n";
         $end_prog->broadcast;
         return 1
      }

      0
   });

   $end_prog->recv;

That's a mouthful, so lets go through it step by step:

   #!/usr/bin/perl

   use AnyEvent;
   use AnyEvent::Handle;

Nothing unexpected here, just load AnyEvent for the event functionality
and AnyEvent::Handle for your file handling needs.

   my $end_prog = AnyEvent->condvar;

Here the program creates a so-called 'condition variable': Condition
variables are a great way to signal the completion of some event, or to
state that some condition became true (thus the name).

This condition variable represents the condition that the program wants to
terminate. Later in the progra, we will 'recv' that condition (call the
C<recv> method on it), which will wait until the condition gets signalled
(which is done by calling the C<send> method on it).

The next step is to create the handle object:

   my $handle =
      AnyEvent::Handle->new (
         fh     => \*STDIN,
         on_eof => sub {
            print "received EOF, exiting...\n";
            $end_prog->broadcast;
         },

This handle object will read from standard input. Setting the C<on_eof>
callback should be done for every file handle, as that is a condition that
we always need to check for when working with file handles, to prevent
reading or writing to a closed file handle, or getting stuck indefinitely
in case of an error.

Speaking of errors:

         on_error => sub {
            print "error while reading from STDIN: $!\n";
            $end_prog->broadcast;
         }
      );

The C<on_error> callback is also not required, but we set it here in case
any error happens when we read from the file handle. It is usually a good
idea to set this callback and at least print some diagnostic message: Even
in our small example an error can happen. More on this later...

   $handle->push_read (sub {

Next we push a general read callback on the read queue, which
will wait until we have received all the data we wanted to
receive. L<AnyEvent::Handle> has two queues per file handle, a read and a
write queue. The write queue queues pending data that waits to be written
to the file handle. And the read queue queues reading callbacks. For more
details see the documentation L<AnyEvent::Handle> about the READ QUEUE and
WRITE QUEUE.

      my ($handle) = @_;

      if ($handle->rbuf =~ s/^.*?\bend\b.*$//s) {
         print "got 'end', existing...\n";
         $end_prog->broadcast;
         return 1
      }

      0
   });

The actual callback waits until the word 'end' has been seen in the data
received on standard input. Once we encounter the stop word 'end' we
remove everything from the read buffer and call the condition variable
we setup earlier, that signals our 'end of program' condition. And the
callback returns with a true value, that signals we are done with reading
all the data we were interested in (all data until the word 'end' has been
seen).

In all other cases, when the stop word has not been seen yet, we just
return a false value, to indicate that we are not finished yet.

The C<rbuf> method returns our read buffer, that we can directly modify as
lvalue.  Alternatively we also could have written:

      if ($handle->{rbuf} =~ s/^.*?\bend\b.*$//s) {

The last line will wait for the condition that our program wants to exit:

   $end_prog->recv;

The call to C<recv> will setup an event loop for us and wait for IO, timer
or signal events and will handle them until the condition gets sent (by
calling its C<send> method).

The key points to learn from this example are:

=over 4

=item * Condition variables are used to start an event loop.

=item * How to registering some basic callbacks on AnyEvent::Handle's.

=item * How to process data in the read buffer.

=back

Revision:	1.1
Committed:	Fri May 30 23:17:49 2008 UTC (16 years, 1 month ago) by root
Branch:	MAIN
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	=head1 Network Programming with AnyEvent
2
3			This is a tutorial that will introduce you to AnyEvent by writing a small
4			event-based program.
5
6			=head2 Introduction
7
8			AnyEvent is first of all just a framework for multiple event loops. It is
9			a thin abstraction layer above all kinds of event loops. Its main purpose
10			is to move the choice of the event loop (whether it is Glib, Qt, EV or
11			Event, or even something else, see also L<AnyEvent>) from the module
12			author to the program author using the module.
13
14			A typical problem with modules such as L<Net::IRC> is that they come with
15			their own event loop. In L<Net::IRC>, the program who uses it needs to
16			start the event loop of L<Net::IRC>. That means that one cannot integrate
17			this module into a L<Gtk2> GUI for instance, as that module, too, enforces
18			the use of its own event loop.
19
20			Another example is L<LWP>: it provides no event interface at all. It's a
21			pure blocking HTTP (and FTP etc.) client library, which usually means that
22			you either have to start a thread or have to fork for a HTTP request, or
23			use L<Coro::LWP>, if you want to do something else while waiting for the
24			request to finish.
25
26			The motivation behind these designs is often that a module doesn't want to
27			depend on some complicated XS-module (Net::IRC), or that it doesn't want
28			to force the user to use some specific event loop (LWP).
29
30			L<AnyEvent> solves this dilemma, by B<not> forcing module authors to:
31
32			=over 4
33
34			=item 1. Write their own event loop.
35
36			=item 2. Choose one fixed event loop.
37
38			=back
39
40			If the module author uses L<AnyEvent> for all his event needs (IO events, timers,
41			signals, ...) all other modules can just use his module and don't have to choose
42			an event loop or adapt to his event loop. The choice of the event loop is ultimately
43			made by the program author who uses all the modules and writes the main
44			program. And even there he doesn't have to choose, he can just ask L<AnyEvent>
45			to choose any available event loop for him.
46
47			And while AnyEvent can make good use of event loops written in C, such as
48			EV or Glib, it also comes with a fast pure-perl event loop implementation
49			on its own, which means module authors can rely on AnyEvent without
50			fearing a worrisome dependency on some XS module.
51
52			Read more about this in the main documentation of the L<AnyEvent> module.
53
54			=head2 Network programming and AnyEvent
55
56			However, AnyEvent is not just a simple abstraction anymore. While the core
57			L<AnyEvent> module is still small and self-contained, the distribution
58			comes with some very useful utility modules such as L<AnyEvent::Handle>,
59			L<AnyEvent::DNS> and L<AnyEvent::Socket>. These can make your life as
60			non-blocking network programmer a lot easier.
61
62			Here is an introduction into these three submodules:
63
64			=head3 L<AnyEvent::Handle>
65
66			This module handles non-blocking IO on file handles in an event based
67			manner. It provides a wrapper object around your file handle that provides
68			queueing and buffering of incoming and outgoing data for you.
69
70			More about this later.
71
72			=head3 L<AnyEvent::Socket>
73
74			This module provides you with functions that handle socket creation
75			and IP address magic. The two main functions are C<tcp_connect> and
76			C<tcp_server>. The former will connect a (streaming) socket to an internet
77			host for you and the later will make a server socket for you, to accept
78			connections.
79
80			This module also comes with transparent IPv6 support, this means: If you
81			write your programs with this module, you will be IPv6 ready without doing
82			anything further.
83
84			It also works around a lot of portability quirks (especially on the
85			windows platform), which makes it even easier to write your programs in a
86			portable way.
87
88			=head3 L<AnyEvent::DNS>
89
90			This module allows fully asynchronous DNS resolution. It is used mainly
91			by L<AnyEvent::Socket> to resolve hostnames and service ports, but is a
92			great way to do other DNS resolution tasks, such as reverse lookups of IP
93			addresses for log files.
94
95			=head2 First experiments with AnyEvent::Handle
96
97			Now let's start with something simple: a program that reads from standard
98			input in a non-blocking way, that is, in a way that lets your program do
99			other things while it is waiting for input.
100
101			First, the full program listing:
102
103			#!/usr/bin/perl
104
105			use AnyEvent;
106			use AnyEvent::Handle;
107
108			my $end_prog = AnyEvent->condvar;
109
110			my $handle =
111			AnyEvent::Handle->new (
112			fh => \*STDIN,
113			on_eof => sub {
114			print "received EOF, exiting...\n";
115			$end_prog->broadcast;
116			},
117			on_error => sub {
118			print "error while reading from STDIN: $!\n";
119			$end_prog->broadcast;
120			}
121			);
122
123			$handle->push_read (sub {
124			my ($handle) = @_;
125
126			if ($handle->rbuf =~ s/^.?\bend\b.$//s) {
127			print "got 'end', existing...\n";
128			$end_prog->broadcast;
129			return 1
130			}
131
132			0
133			});
134
135			$end_prog->recv;
136
137			That's a mouthful, so lets go through it step by step:
138
139			#!/usr/bin/perl
140
141			use AnyEvent;
142			use AnyEvent::Handle;
143
144			Nothing unexpected here, just load AnyEvent for the event functionality
145			and AnyEvent::Handle for your file handling needs.
146
147			my $end_prog = AnyEvent->condvar;
148
149			Here the program creates a so-called 'condition variable': Condition
150			variables are a great way to signal the completion of some event, or to
151			state that some condition became true (thus the name).
152
153			This condition variable represents the condition that the program wants to
154			terminate. Later in the progra, we will 'recv' that condition (call the
155			C<recv> method on it), which will wait until the condition gets signalled
156			(which is done by calling the C<send> method on it).
157
158			The next step is to create the handle object:
159
160			my $handle =
161			AnyEvent::Handle->new (
162			fh => \*STDIN,
163			on_eof => sub {
164			print "received EOF, exiting...\n";
165			$end_prog->broadcast;
166			},
167
168			This handle object will read from standard input. Setting the C<on_eof>
169			callback should be done for every file handle, as that is a condition that
170			we always need to check for when working with file handles, to prevent
171			reading or writing to a closed file handle, or getting stuck indefinitely
172			in case of an error.
173
174			Speaking of errors:
175
176			on_error => sub {
177			print "error while reading from STDIN: $!\n";
178			$end_prog->broadcast;
179			}
180			);
181
182			The C<on_error> callback is also not required, but we set it here in case
183			any error happens when we read from the file handle. It is usually a good
184			idea to set this callback and at least print some diagnostic message: Even
185			in our small example an error can happen. More on this later...
186
187			$handle->push_read (sub {
188
189			Next we push a general read callback on the read queue, which
190			will wait until we have received all the data we wanted to
191			receive. L<AnyEvent::Handle> has two queues per file handle, a read and a
192			write queue. The write queue queues pending data that waits to be written
193			to the file handle. And the read queue queues reading callbacks. For more
194			details see the documentation L<AnyEvent::Handle> about the READ QUEUE and
195			WRITE QUEUE.
196
197			my ($handle) = @_;
198
199			if ($handle->rbuf =~ s/^.?\bend\b.$//s) {
200			print "got 'end', existing...\n";
201			$end_prog->broadcast;
202			return 1
203			}
204
205			0
206			});
207
208			The actual callback waits until the word 'end' has been seen in the data
209			received on standard input. Once we encounter the stop word 'end' we
210			remove everything from the read buffer and call the condition variable
211			we setup earlier, that signals our 'end of program' condition. And the
212			callback returns with a true value, that signals we are done with reading
213			all the data we were interested in (all data until the word 'end' has been
214			seen).
215
216			In all other cases, when the stop word has not been seen yet, we just
217			return a false value, to indicate that we are not finished yet.
218
219			The C<rbuf> method returns our read buffer, that we can directly modify as
220			lvalue. Alternatively we also could have written:
221
222			if ($handle->{rbuf} =~ s/^.?\bend\b.$//s) {
223
224			The last line will wait for the condition that our program wants to exit:
225
226			$end_prog->recv;
227
228			The call to C<recv> will setup an event loop for us and wait for IO, timer
229			or signal events and will handle them until the condition gets sent (by
230			calling its C<send> method).
231
232			The key points to learn from this example are:
233
234			=over 4
235
236			=item * Condition variables are used to start an event loop.
237
238			=item * How to registering some basic callbacks on AnyEvent::Handle's.
239
240			=item * How to process data in the read buffer.
241
242			=back
243