ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent/README
(Generate patch)

Comparing AnyEvent/README (file contents):
Revision 1.37 by root, Mon Apr 20 14:34:18 2009 UTC vs.
Revision 1.40 by root, Tue Jun 23 23:37:32 2009 UTC

1NAME 1NAME
2 AnyEvent - provide framework for multiple event loops 2 AnyEvent - provide framework for multiple event loops
3 3
4 EV, Event, Glib, Tk, Perl, Event::Lib, Qt, POE - various supported event 4 EV, Event, Glib, Tk, Perl, Event::Lib, Qt and POE are various supported
5 loops 5 event loops.
6 6
7SYNOPSIS 7SYNOPSIS
8 use AnyEvent; 8 use AnyEvent;
9 9
10 # file descriptor readable
10 my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub { ... }); 11 my $w = AnyEvent->io (fh => $fh, poll => "r", cb => sub { ... });
11 12
13 # one-shot or repeating timers
12 my $w = AnyEvent->timer (after => $seconds, cb => sub { ... }); 14 my $w = AnyEvent->timer (after => $seconds, cb => sub { ... });
13 my $w = AnyEvent->timer (after => $seconds, interval => $seconds, cb => ... 15 my $w = AnyEvent->timer (after => $seconds, interval => $seconds, cb => ...
14 16
15 print AnyEvent->now; # prints current event loop time 17 print AnyEvent->now; # prints current event loop time
16 print AnyEvent->time; # think Time::HiRes::time or simply CORE::time. 18 print AnyEvent->time; # think Time::HiRes::time or simply CORE::time.
17 19
20 # POSIX signal
18 my $w = AnyEvent->signal (signal => "TERM", cb => sub { ... }); 21 my $w = AnyEvent->signal (signal => "TERM", cb => sub { ... });
19 22
23 # child process exit
20 my $w = AnyEvent->child (pid => $pid, cb => sub { 24 my $w = AnyEvent->child (pid => $pid, cb => sub {
21 my ($pid, $status) = @_; 25 my ($pid, $status) = @_;
22 ... 26 ...
23 }); 27 });
28
29 # called when event loop idle (if applicable)
30 my $w = AnyEvent->idle (cb => sub { ... });
24 31
25 my $w = AnyEvent->condvar; # stores whether a condition was flagged 32 my $w = AnyEvent->condvar; # stores whether a condition was flagged
26 $w->send; # wake up current and all future recv's 33 $w->send; # wake up current and all future recv's
27 $w->recv; # enters "main loop" till $condvar gets ->send 34 $w->recv; # enters "main loop" till $condvar gets ->send
28 # use a condvar in callback mode: 35 # use a condvar in callback mode:
… …
385 you "fork" the child (alternatively, you can call "AnyEvent::detect"). 392 you "fork" the child (alternatively, you can call "AnyEvent::detect").
386 393
387 Example: fork a process and wait for it 394 Example: fork a process and wait for it
388 395
389 my $done = AnyEvent->condvar; 396 my $done = AnyEvent->condvar;
390 397
391 my $pid = fork or exit 5; 398 my $pid = fork or exit 5;
392 399
393 my $w = AnyEvent->child ( 400 my $w = AnyEvent->child (
394 pid => $pid, 401 pid => $pid,
395 cb => sub { 402 cb => sub {
396 my ($pid, $status) = @_; 403 my ($pid, $status) = @_;
397 warn "pid $pid exited with status $status"; 404 warn "pid $pid exited with status $status";
398 $done->send; 405 $done->send;
399 }, 406 },
400 ); 407 );
401 408
402 # do something else, then wait for process exit 409 # do something else, then wait for process exit
403 $done->recv; 410 $done->recv;
411
412 IDLE WATCHERS
413 Sometimes there is a need to do something, but it is not so important to
414 do it instantly, but only when there is nothing better to do. This
415 "nothing better to do" is usually defined to be "no other events need
416 attention by the event loop".
417
418 Idle watchers ideally get invoked when the event loop has nothing better
419 to do, just before it would block the process to wait for new events.
420 Instead of blocking, the idle watcher is invoked.
421
422 Most event loops unfortunately do not really support idle watchers (only
423 EV, Event and Glib do it in a usable fashion) - for the rest, AnyEvent
424 will simply call the callback "from time to time".
425
426 Example: read lines from STDIN, but only process them when the program
427 is otherwise idle:
428
429 my @lines; # read data
430 my $idle_w;
431 my $io_w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
432 push @lines, scalar <STDIN>;
433
434 # start an idle watcher, if not already done
435 $idle_w ||= AnyEvent->idle (cb => sub {
436 # handle only one line, when there are lines left
437 if (my $line = shift @lines) {
438 print "handled when idle: $line";
439 } else {
440 # otherwise disable the idle watcher again
441 undef $idle_w;
442 }
443 });
444 });
404 445
405 CONDITION VARIABLES 446 CONDITION VARIABLES
406 If you are familiar with some event loops you will know that all of them 447 If you are familiar with some event loops you will know that all of them
407 require you to run some blocking "loop", "run" or similar function that 448 require you to run some blocking "loop", "run" or similar function that
408 will actively watch for new events and call your callbacks. 449 will actively watch for new events and call your callbacks.
… …
842 "condvar->recv"), the Event and EV modules call "$Event/EV::DIED->()", 883 "condvar->recv"), the Event and EV modules call "$Event/EV::DIED->()",
843 Glib uses "install_exception_handler" and so on. 884 Glib uses "install_exception_handler" and so on.
844 885
845ENVIRONMENT VARIABLES 886ENVIRONMENT VARIABLES
846 The following environment variables are used by this module or its 887 The following environment variables are used by this module or its
847 submodules: 888 submodules.
889
890 Note that AnyEvent will remove *all* environment variables starting with
891 "PERL_ANYEVENT_" from %ENV when it is loaded while taint mode is
892 enabled.
848 893
849 "PERL_ANYEVENT_VERBOSE" 894 "PERL_ANYEVENT_VERBOSE"
850 By default, AnyEvent will be completely silent except in fatal 895 By default, AnyEvent will be completely silent except in fatal
851 conditions. You can set this environment variable to make AnyEvent 896 conditions. You can set this environment variable to make AnyEvent
852 more talkative. 897 more talkative.
… …
1357 1402
1358 Summary 1403 Summary
1359 * C-based event loops perform very well with small number of watchers, 1404 * C-based event loops perform very well with small number of watchers,
1360 as the management overhead dominates. 1405 as the management overhead dominates.
1361 1406
1407 THE IO::Lambda BENCHMARK
1408 Recently I was told about the benchmark in the IO::Lambda manpage, which
1409 could be misinterpreted to make AnyEvent look bad. In fact, the
1410 benchmark simply compares IO::Lambda with POE, and IO::Lambda looks
1411 better (which shouldn't come as a surprise to anybody). As such, the
1412 benchmark is fine, and shows that the AnyEvent backend from IO::Lambda
1413 isn't very optimal. But how would AnyEvent compare when used without the
1414 extra baggage? To explore this, I wrote the equivalent benchmark for
1415 AnyEvent.
1416
1417 The benchmark itself creates an echo-server, and then, for 500 times,
1418 connects to the echo server, sends a line, waits for the reply, and then
1419 creates the next connection. This is a rather bad benchmark, as it
1420 doesn't test the efficiency of the framework, but it is a benchmark
1421 nevertheless.
1422
1423 name runtime
1424 Lambda/select 0.330 sec
1425 + optimized 0.122 sec
1426 Lambda/AnyEvent 0.327 sec
1427 + optimized 0.138 sec
1428 Raw sockets/select 0.077 sec
1429 POE/select, components 0.662 sec
1430 POE/select, raw sockets 0.226 sec
1431 POE/select, optimized 0.404 sec
1432
1433 AnyEvent/select/nb 0.085 sec
1434 AnyEvent/EV/nb 0.068 sec
1435 +state machine 0.134 sec
1436
1437 The benchmark is also a bit unfair (my fault) - the IO::Lambda
1438 benchmarks actually make blocking connects and use 100% blocking I/O,
1439 defeating the purpose of an event-based solution. All of the newly
1440 written AnyEvent benchmarks use 100% non-blocking connects (using
1441 AnyEvent::Socket::tcp_connect and the asynchronous pure perl DNS
1442 resolver), so AnyEvent is at a disadvantage here as non-blocking
1443 connects generally require a lot more bookkeeping and event handling
1444 than blocking connects (which involve a single syscall only).
1445
1446 The last AnyEvent benchmark additionally uses AnyEvent::Handle, which
1447 offers similar expressive power as POE and IO::Lambda (using
1448 conventional Perl syntax), which means both the echo server and the
1449 client are 100% non-blocking w.r.t. I/O, further placing it at a
1450 disadvantage.
1451
1452 As you can see, AnyEvent + EV even beats the hand-optimised "raw sockets
1453 benchmark", while AnyEvent + its pure perl backend easily beats
1454 IO::Lambda and POE.
1455
1456 And even the 100% non-blocking version written using the high-level (and
1457 slow :) AnyEvent::Handle abstraction beats both POE and IO::Lambda, even
1458 thought it does all of DNS, tcp-connect and socket I/O in a non-blocking
1459 way.
1460
1461 The two AnyEvent benchmarks can be found as eg/ae0.pl and eg/ae2.pl in
1462 the AnyEvent distribution, the remaining benchmarks are part of the
1463 IO::lambda distribution and were used without any changes.
1464
1362SIGNALS 1465SIGNALS
1363 AnyEvent currently installs handlers for these signals: 1466 AnyEvent currently installs handlers for these signals:
1364 1467
1365 SIGCHLD 1468 SIGCHLD
1366 A handler for "SIGCHLD" is installed by AnyEvent's child watcher 1469 A handler for "SIGCHLD" is installed by AnyEvent's child watcher
… …
1401 1504
1402 You can make AnyEvent completely ignore this variable by deleting it 1505 You can make AnyEvent completely ignore this variable by deleting it
1403 before the first watcher gets created, e.g. with a "BEGIN" block: 1506 before the first watcher gets created, e.g. with a "BEGIN" block:
1404 1507
1405 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } 1508 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
1406 1509
1407 use AnyEvent; 1510 use AnyEvent;
1408 1511
1409 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can 1512 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1410 be used to probe what backend is used and gain other information (which 1513 be used to probe what backend is used and gain other information (which
1411 is probably even less useful to an attacker than PERL_ANYEVENT_MODEL), 1514 is probably even less useful to an attacker than PERL_ANYEVENT_MODEL),
1412 and $ENV{PERL_ANYEGENT_STRICT}. 1515 and $ENV{PERL_ANYEVENT_STRICT}.
1413 1516
1414BUGS 1517BUGS
1415 Perl 5.8 has numerous memleaks that sometimes hit this module and are 1518 Perl 5.8 has numerous memleaks that sometimes hit this module and are
1416 hard to work around. If you suffer from memleaks, first upgrade to Perl 1519 hard to work around. If you suffer from memleaks, first upgrade to Perl
1417 5.10 and check wether the leaks still show up. (Perl 5.10.0 has other 1520 5.10 and check wether the leaks still show up. (Perl 5.10.0 has other

Diff Legend

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