lib/AnyEvent/FAQ.pod

=head1 NAME

AnyEvent::FAQ - frequently asked questions

The newest version of this document can be found at
L<http://pod.tst.eu/http://cvs.schmorp.de/AnyEvent/lib/AnyEvent/FAQ.pod>.

=head2 My program exits before doing anything, what's going on?

Programmers new to event-based programming often forget that you can
actually do other stuff while "waiting" for an event to occur and
therefore forget to actually wait when they do not, in fact, have anything
else to do.

Here is an example:

   use AnyEvent;

   my $timer = AnyEvent->timer (after => 5, cb => sub { say "hi" });

The expectation might be for the program to print "hi" after 5 seconds
and then probably to exit. However, if you run this, your program will
exit almost instantly: Creating the timer does not wait for it, instead
the C<timer> method returns immediately and perl executes the rest of the
program. But there is nothing left to execute, so perl exits.

To force AnyEvent to wait for something, use a condvar:

   use AnyEvent;

   my $quit_program = AnyEvent->condvar;
   my $timer = AnyEvent->timer (after => 5, cb => sub { $quit_program->send });

   $quit_program->recv;

Here the program doesn't immediately exit, because it first waits for
the "quit_program" condition.

In most cases, your main program should call the event library "loop"
function directly:

   use EV;
   use AnyEvent;

   ...

   EV::loop;

=head2 Why is my C<tcp_connect> callback never called?

Tricky: C<tcp_connect> (and a few other functions in L<AnyEvent::Socket>)
is critically sensitive to the caller context.

In void context, it will just do its thing and eventually call the
callback. In any other context, however, it will return a special "guard"
object - when it is destroyed (e.g. when you don't store it but throw it
away), tcp_connect will no longer try to connect or call any callbacks.

Often this happens when the C<tcp_connect> call is at the end of a function:

   sub do_connect {
      tcp_connect "www.example.com", 80, sub {
         ... lengthy code
      };
   }

Then the caller decides whether there is a void context or not. One can
avoid these cases by explicitly returning nothing:

   sub do_connect {
      tcp_connect "www.example.com", 80, sub {
         ... lengthy code
      };

      () # return nothing
   }

=head2 Why do some backends use a lot of CPU in C<< AE::cv->recv >>?

Many people try out this simple program, or its equivalent:

   use AnyEvent;
   AnyEvent->condvar->recv;

They are then shocked to see that this basically idles with the Perl
backend, but uses 100% CPU with the EV backend, which is supposed to be
sooo efficient.

The key to understand this is to understand that the above program
is actually I<buggy>: Nothing calls C<< ->send >> on the condvar,
ever. Worse, there are no event watchers whatsoever. Basically, it creates
a deadlock: there is no way to make progress, this program doesn't do
anything useful, and this will not change in the future: it is already an
ex-parrot.

Some backends react to this by freezing, some by idling, and some do a
100% CPU loop.

Since this program is not useful (and behaves as documented with all
backends, as AnyEvent makes no CPU time guarantees), this shouldn't be a
big deal: as soon as your program actually implements I<something>, the
CPU usage will be normal.

=head2 Why does this FAQ not deal with L<AnyEvent::Handle> questions?

Because L<AnyEvent::Handle> has a NONFAQ on its own that already deals
with common issues.

=head2 How can I combine L<Win32::GUI> applications with AnyEvent?

Well, not in the same OS thread, that's for sure :) What you can do is
create another ithread (or fork) and run AnyEvent inside that thread, or
better yet, run all your GUI code in a second ithread.

For example, you could load L<Win32::GUI> and L<AnyEvent::Util>, then
create a portable socketpair for GUI->AnyEvent communication.

Then fork/create a new ithread, in there, create a Window and send the C<<
$WINDOW->{-Handle} >> to the AnyEvent ithread so it can C<PostMessage>.

GUI to AnyEvent communication could work by pushing some data into a
L<Thread::Queue> and writing a byte into the socket. The AnyEvent watcher
on the other side will then look at the queue.

AnyEvent to GUI communications can also use a L<Thread::Queue>, but to
wake up the GUI thread, it would instead use C<< Win32::GUI::PostMessage
$WINDOW, 1030, 0, "" >>, and the GUI thread would listen for these
messages by using C<< $WINDOW->Hook (1030 (), sub { ... }) >>.

=head2 My callback dies and...

It must not - part of the contract betwene AnyEvent and user code is that
callbacks do not throw exceptions (and don't do even more evil things,
such as using C<last> outside a loop :). If your callback might die
sometimes, you need to use C<eval>.

If you want to track down such a case and you can reproduce it, you can
enable wrapping (by calling C<< L<AnyEvent::Debug>::wrap >> or by setting
C<PERL_ANYEVENT_DEBUG_WRAP=1> before starting your program). This will
wrap every callback into an eval and will report any exception complete
with a backtrace and some information about which watcher died, where it
was created and so on.

=head1 Author

Marc Lehmann <schmorp@schmorp.de>.

Revision:	1.9
Committed:	Sun Aug 21 02:24:56 2011 UTC (12 years, 10 months ago) by root
Branch:	MAIN
CVS Tags:	rel-7_0, rel-6_1, rel-6_14, rel-6_11, rel-6_12, rel-6_13, rel-7_04, rel-7_05, rel-7_07, rel-7_01, rel-7_02, rel-7_03, rel-7_08, rel-7_09, rel-6_02, rel-6_01, rel-7_14, rel-7_13, rel-7_12, rel-7_11
Changes since 1.8:	+14 -0 lines
Log Message:	* empty log message *
#	Content
1	=head1 NAME
2
3	AnyEvent::FAQ - frequently asked questions
4
5	The newest version of this document can be found at
6	L<http://pod.tst.eu/http://cvs.schmorp.de/AnyEvent/lib/AnyEvent/FAQ.pod>.
7
8	=head2 My program exits before doing anything, what's going on?
9
10	Programmers new to event-based programming often forget that you can
11	actually do other stuff while "waiting" for an event to occur and
12	therefore forget to actually wait when they do not, in fact, have anything
13	else to do.
14
15	Here is an example:
16
17	use AnyEvent;
18
19	my $timer = AnyEvent->timer (after => 5, cb => sub { say "hi" });
20
21	The expectation might be for the program to print "hi" after 5 seconds
22	and then probably to exit. However, if you run this, your program will
23	exit almost instantly: Creating the timer does not wait for it, instead
24	the C<timer> method returns immediately and perl executes the rest of the
25	program. But there is nothing left to execute, so perl exits.
26
27	To force AnyEvent to wait for something, use a condvar:
28
29	use AnyEvent;
30
31	my $quit_program = AnyEvent->condvar;
32	my $timer = AnyEvent->timer (after => 5, cb => sub { $quit_program->send });
33
34	$quit_program->recv;
35
36	Here the program doesn't immediately exit, because it first waits for
37	the "quit_program" condition.
38
39	In most cases, your main program should call the event library "loop"
40	function directly:
41
42	use EV;
43	use AnyEvent;
44
45	...
46
47	EV::loop;
48
49	=head2 Why is my C<tcp_connect> callback never called?
50
51	Tricky: C<tcp_connect> (and a few other functions in L<AnyEvent::Socket>)
52	is critically sensitive to the caller context.
53
54	In void context, it will just do its thing and eventually call the
55	callback. In any other context, however, it will return a special "guard"
56	object - when it is destroyed (e.g. when you don't store it but throw it
57	away), tcp_connect will no longer try to connect or call any callbacks.
58
59	Often this happens when the C<tcp_connect> call is at the end of a function:
60
61	sub do_connect {
62	tcp_connect "www.example.com", 80, sub {
63	... lengthy code
64	};
65	}
66
67	Then the caller decides whether there is a void context or not. One can
68	avoid these cases by explicitly returning nothing:
69
70	sub do_connect {
71	tcp_connect "www.example.com", 80, sub {
72	... lengthy code
73	};
74
75	() # return nothing
76	}
77
78	=head2 Why do some backends use a lot of CPU in C<< AE::cv->recv >>?
79
80	Many people try out this simple program, or its equivalent:
81
82	use AnyEvent;
83	AnyEvent->condvar->recv;
84
85	They are then shocked to see that this basically idles with the Perl
86	backend, but uses 100% CPU with the EV backend, which is supposed to be
87	sooo efficient.
88
89	The key to understand this is to understand that the above program
90	is actually I<buggy>: Nothing calls C<< ->send >> on the condvar,
91	ever. Worse, there are no event watchers whatsoever. Basically, it creates
92	a deadlock: there is no way to make progress, this program doesn't do
93	anything useful, and this will not change in the future: it is already an
94	ex-parrot.
95
96	Some backends react to this by freezing, some by idling, and some do a
97	100% CPU loop.
98
99	Since this program is not useful (and behaves as documented with all
100	backends, as AnyEvent makes no CPU time guarantees), this shouldn't be a
101	big deal: as soon as your program actually implements I<something>, the
102	CPU usage will be normal.
103
104	=head2 Why does this FAQ not deal with L<AnyEvent::Handle> questions?
105
106	Because L<AnyEvent::Handle> has a NONFAQ on its own that already deals
107	with common issues.
108
109	=head2 How can I combine L<Win32::GUI> applications with AnyEvent?
110
111	Well, not in the same OS thread, that's for sure :) What you can do is
112	create another ithread (or fork) and run AnyEvent inside that thread, or
113	better yet, run all your GUI code in a second ithread.
114
115	For example, you could load L<Win32::GUI> and L<AnyEvent::Util>, then
116	create a portable socketpair for GUI->AnyEvent communication.
117
118	Then fork/create a new ithread, in there, create a Window and send the C<<
119	$WINDOW->{-Handle} >> to the AnyEvent ithread so it can C<PostMessage>.
120
121	GUI to AnyEvent communication could work by pushing some data into a
122	L<Thread::Queue> and writing a byte into the socket. The AnyEvent watcher
123	on the other side will then look at the queue.
124
125	AnyEvent to GUI communications can also use a L<Thread::Queue>, but to
126	wake up the GUI thread, it would instead use C<< Win32::GUI::PostMessage
127	$WINDOW, 1030, 0, "" >>, and the GUI thread would listen for these
128	messages by using C<< $WINDOW->Hook (1030 (), sub { ... }) >>.
129
130	=head2 My callback dies and...
131
132	It must not - part of the contract betwene AnyEvent and user code is that
133	callbacks do not throw exceptions (and don't do even more evil things,
134	such as using C<last> outside a loop :). If your callback might die
135	sometimes, you need to use C<eval>.
136
137	If you want to track down such a case and you can reproduce it, you can
138	enable wrapping (by calling C<< L<AnyEvent::Debug>::wrap >> or by setting
139	C<PERL_ANYEVENT_DEBUG_WRAP=1> before starting your program). This will
140	wrap every callback into an eval and will report any exception complete
141	with a backtrace and some information about which watcher died, where it
142	was created and so on.
143
144	=head1 Author
145
146	Marc Lehmann <schmorp@schmorp.de>.
147