AnyEvent/doc/Tutorial.pod

=head1 Network Programming with AnyEvent

This is a tutorial that will explain the usage of AnyEvent for
Network programming.

=head2 Introduction

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

The problem was usually that modules like L<Net::IRC> came with their own
event loop, where the program author needed to start the event loop
of L<Net::IRC>. That usually meant that he couldn't integrate it easily with
a L<Gtk2> GUI for instance.

Another example is L<LWP>, it provides no event interface at all. It's a pure
blocking HTTP 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>.

L<AnyEvent> now does B<not> force authors of modules, like L<Net::IRC>, 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.

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. It comes with
some very useful utility modules like L<AnyEvent::Handle>, L<AnyEvent::DNS>
and L<AnyEvent::Socket> that make your life as non-blocking network programmer
a lot easier.

Now an introduction into these three submodules:

=head3 L<AnyEvent::Handle>

This module handles non-blocking IO on filehandles in a event based
manner. It provides a wrapper object around your filehandle 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 internet 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.

=head3 L<AnyEvent::DNS>

This module allows fully asynchronous DNS resolution, and is used for example
by L<AnyEvent::Socket> to resolve hostnames and service ports.

=head2 First experiments with AnyEvent::Handle

Now lets start with something simple, a program that reads non-blocking
from standard input:

   #!/opt/perl/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->wait;

Lets go through it step by step:

   #!/opt/perl/bin/perl
   use AnyEvent;
   use AnyEvent::Handle;

Nothing new here, just load AnyEvent for the event loop and AnyEvent::Handle.

   my $end_prog = AnyEvent->condvar;

Here a 'condition variable' is created. It represents the condition when the
program wants to terminate. We will later 'wait' for that condition, which
will choose and create an event loop for us.

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

We create a handle which will read from the standard input filehandle.
Setting the C<on_eof> callback is required for every filehandle, as that is a
condition that we need to check always if we are working with filehandles,
to prevent reading or writing to a closed filehandle.

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

The C<on_error> callback is not required, but we set it here in case any
error happens when we read from the filehandle. It's usually a good idea to
set this callback also and at least print some diagnostics. Already in our
small example an error can happen. More to this later...

   $handle->push_read (sub {

Here we push a general read callback on the read queue, that will wait until we
received all the data we wanted to receive. L<AnyEvent::Handle> has two queues
per filehandle, a read and a write queue. The write queue queues pending data
that waits to be written to the filehandle. 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
   });

This code 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) {


   $end_prog->wait;

This last line will wait blocking for the condition that our program wants to
exit. C<wait> will setup an event loop for us and wait for IO, timers or signals.

The key points were:

=over 4

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

=item * Registering the basic callbacks on AnyEvent::Handles.

=item * Processing data in the read buffer.

=back
Revision:	1.2
Committed:	Sun May 25 14:35:53 2008 UTC (18 years, 4 months ago) by elmex
Branch:	MAIN
Changes since 1.1:	+130 -1 lines
Log Message:	further work on the tutorial
#	User	Rev	Content
1	elmex	1.1	=head1 Network Programming with AnyEvent
2
3			This is a tutorial that will explain the usage of AnyEvent for
4			Network programming.
5
6			=head2 Introduction
7
8			AnyEvent is first of all just a framework for multiple event loops. It's a
9			thin abstraction layer above all kinds of event loops. It's main purpose is to
10			move the choice of the event loop (whether it should be Glib, Qt, EV or Event,
11			or even something else, see also L<AnyEvent>) from the module author to the
12			program author.
13
14			The problem was usually that modules like L<Net::IRC> came with their own
15			event loop, where the program author needed to start the event loop
16			of L<Net::IRC>. That usually meant that he couldn't integrate it easily with
17			a L<Gtk2> GUI for instance.
18
19			Another example is L<LWP>, it provides no event interface at all. It's a pure
20			blocking HTTP client library, which usually means that you either have to
21			start a thread or have to fork for a HTTP request, or use L<Coro::LWP>.
22
23			L<AnyEvent> now does B<not> force authors of modules, like L<Net::IRC>, to:
24
25			=over 4
26
27			=item 1. Write their own event loop.
28
29			=item 2. Choose one fixed event loop.
30
31			=back
32
33			If the module author uses L<AnyEvent> for all his event needs (IO events, timers,
34			signals, ...) all other modules can just use his module and don't have to choose
35			an event loop or adapt to his event loop. The choice of the event loop is ultimately
36			made by the program author who uses all the modules and writes the main
37			program. And even there he doesn't have to choose, he can just ask L<AnyEvent>
38			to choose any available event loop for him.
39
40			Read more about this in the main documentation of the L<AnyEvent> module.
41
42	elmex	1.2	=head2 Network programming and AnyEvent
43	elmex	1.1
44			However, AnyEvent is not just a simple abstraction anymore. It comes with
45			some very useful utility modules like L<AnyEvent::Handle>, L<AnyEvent::DNS>
46			and L<AnyEvent::Socket> that make your life as non-blocking network programmer
47			a lot easier.
48
49			Now an introduction into these three submodules:
50
51			=head3 L<AnyEvent::Handle>
52
53			This module handles non-blocking IO on filehandles in a event based
54			manner. It provides a wrapper object around your filehandle that provides
55			queueing and buffering of incoming and outgoing data for you.
56
57			More about this later.
58
59			=head3 L<AnyEvent::Socket>
60
61			This module provides you with functions that handle internet socket creation
62			and IP address magic. The two main functions are C<tcp_connect> and
63			C<tcp_server>. The former will connect a (streaming) socket to an internet host
64			for you and the later will make a server socket for you, to accept connections.
65
66			This module also comes with transparent IPv6 support, this means: If you
67			write your programs with this module, you will be IPv6 ready.
68
69			=head3 L<AnyEvent::DNS>
70
71			This module allows fully asynchronous DNS resolution, and is used for example
72			by L<AnyEvent::Socket> to resolve hostnames and service ports.
73	elmex	1.2
74			=head2 First experiments with AnyEvent::Handle
75
76			Now lets start with something simple, a program that reads non-blocking
77			from standard input:
78
79			#!/opt/perl/bin/perl
80			use AnyEvent;
81			use AnyEvent::Handle;
82
83			my $end_prog = AnyEvent->condvar;
84
85			my $handle =
86			AnyEvent::Handle->new (
87			fh => \*STDIN,
88			on_eof => sub {
89			print "received EOF, exiting...\n";
90			$end_prog->broadcast;
91			},
92			on_error => sub {
93			print "error while reading from STDIN: $!\n";
94			$end_prog->broadcast;
95			}
96			);
97
98			$handle->push_read (sub {
99			my ($handle) = @_;
100
101			if ($handle->rbuf =~ s/^.?\bend\b.$//s) {
102			print "got 'end', existing...\n";
103			$end_prog->broadcast;
104			return 1
105			}
106
107			0
108			});
109
110			$end_prog->wait;
111
112			Lets go through it step by step:
113
114			#!/opt/perl/bin/perl
115			use AnyEvent;
116			use AnyEvent::Handle;
117
118			Nothing new here, just load AnyEvent for the event loop and AnyEvent::Handle.
119
120			my $end_prog = AnyEvent->condvar;
121
122			Here a 'condition variable' is created. It represents the condition when the
123			program wants to terminate. We will later 'wait' for that condition, which
124			will choose and create an event loop for us.
125
126			my $handle =
127			AnyEvent::Handle->new (
128			fh => \*STDIN,
129			on_eof => sub {
130			print "received EOF, exiting...\n";
131			$end_prog->broadcast;
132			},
133
134			We create a handle which will read from the standard input filehandle.
135			Setting the C<on_eof> callback is required for every filehandle, as that is a
136			condition that we need to check always if we are working with filehandles,
137			to prevent reading or writing to a closed filehandle.
138
139			on_error => sub {
140			print "error while reading from STDIN: $!\n";
141			$end_prog->broadcast;
142			}
143			);
144
145			The C<on_error> callback is not required, but we set it here in case any
146			error happens when we read from the filehandle. It's usually a good idea to
147			set this callback also and at least print some diagnostics. Already in our
148			small example an error can happen. More to this later...
149
150			$handle->push_read (sub {
151
152			Here we push a general read callback on the read queue, that will wait until we
153			received all the data we wanted to receive. L<AnyEvent::Handle> has two queues
154			per filehandle, a read and a write queue. The write queue queues pending data
155			that waits to be written to the filehandle. And the read queue queues reading
156			callbacks. For more details see the documentation L<AnyEvent::Handle> about the
157			READ QUEUE and WRITE QUEUE.
158
159			my ($handle) = @_;
160
161			if ($handle->rbuf =~ s/^.?\bend\b.$//s) {
162			print "got 'end', existing...\n";
163			$end_prog->broadcast;
164			return 1
165			}
166
167			0
168			});
169
170			This code waits until the word 'end' has been seen in the data received
171			on standard input. Once we encounter the stop word 'end' we remove everything from
172			the read buffer and call the condition variable we setup earlier, that signals
173			our 'end of program' condition. And the callback returns with a true value,
174			that signals we are done with reading all the data we were interested in (all data until
175			the word 'end' has been seen).
176
177			In all other cases, when the stop word has not been seen yet, we just return a false
178			value, to indicate that we are not finished yet.
179
180			The C<rbuf> method returns our read buffer, that we can directly modify as lvalue.
181			Alternatively we also could have written:
182
183			if ($handle->{rbuf} =~ s/^.?\bend\b.$//s) {
184
185
186			$end_prog->wait;
187
188			This last line will wait blocking for the condition that our program wants to
189			exit. C<wait> will setup an event loop for us and wait for IO, timers or signals.
190
191			The key points were:
192
193			=over 4
194
195			=item * Condition variables used to start an event loop.
196
197			=item * Registering the basic callbacks on AnyEvent::Handles.
198
199			=item * Processing data in the read buffer.
200
201			=back