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

Comparing AnyEvent/README (file contents):
Revision 1.36 by root, Fri Mar 27 10:49:50 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:
… …
314 In either case, if you care (and in most cases, you don't), then you 321 In either case, if you care (and in most cases, you don't), then you
315 can get whatever behaviour you want with any event loop, by taking 322 can get whatever behaviour you want with any event loop, by taking
316 the difference between "AnyEvent->time" and "AnyEvent->now" into 323 the difference between "AnyEvent->time" and "AnyEvent->now" into
317 account. 324 account.
318 325
326 AnyEvent->now_update
327 Some event loops (such as EV or AnyEvent::Impl::Perl) cache the
328 current time for each loop iteration (see the discussion of
329 AnyEvent->now, above).
330
331 When a callback runs for a long time (or when the process sleeps),
332 then this "current" time will differ substantially from the real
333 time, which might affect timers and time-outs.
334
335 When this is the case, you can call this method, which will update
336 the event loop's idea of "current time".
337
338 Note that updating the time *might* cause some events to be handled.
339
319 SIGNAL WATCHERS 340 SIGNAL WATCHERS
320 You can watch for signals using a signal watcher, "signal" is the signal 341 You can watch for signals using a signal watcher, "signal" is the signal
321 *name* in uppercase and without any "SIG" prefix, "cb" is the Perl 342 *name* in uppercase and without any "SIG" prefix, "cb" is the Perl
322 callback to be invoked whenever a signal occurs. 343 callback to be invoked whenever a signal occurs.
323 344
… …
371 you "fork" the child (alternatively, you can call "AnyEvent::detect"). 392 you "fork" the child (alternatively, you can call "AnyEvent::detect").
372 393
373 Example: fork a process and wait for it 394 Example: fork a process and wait for it
374 395
375 my $done = AnyEvent->condvar; 396 my $done = AnyEvent->condvar;
376 397
377 my $pid = fork or exit 5; 398 my $pid = fork or exit 5;
378 399
379 my $w = AnyEvent->child ( 400 my $w = AnyEvent->child (
380 pid => $pid, 401 pid => $pid,
381 cb => sub { 402 cb => sub {
382 my ($pid, $status) = @_; 403 my ($pid, $status) = @_;
383 warn "pid $pid exited with status $status"; 404 warn "pid $pid exited with status $status";
384 $done->send; 405 $done->send;
385 }, 406 },
386 ); 407 );
387 408
388 # do something else, then wait for process exit 409 # do something else, then wait for process exit
389 $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 });
390 445
391 CONDITION VARIABLES 446 CONDITION VARIABLES
392 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
393 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
394 will actively watch for new events and call your callbacks. 449 will actively watch for new events and call your callbacks.
… …
828 "condvar->recv"), the Event and EV modules call "$Event/EV::DIED->()", 883 "condvar->recv"), the Event and EV modules call "$Event/EV::DIED->()",
829 Glib uses "install_exception_handler" and so on. 884 Glib uses "install_exception_handler" and so on.
830 885
831ENVIRONMENT VARIABLES 886ENVIRONMENT VARIABLES
832 The following environment variables are used by this module or its 887 The following environment variables are used by this module or its
833 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.
834 893
835 "PERL_ANYEVENT_VERBOSE" 894 "PERL_ANYEVENT_VERBOSE"
836 By default, AnyEvent will be completely silent except in fatal 895 By default, AnyEvent will be completely silent except in fatal
837 conditions. You can set this environment variable to make AnyEvent 896 conditions. You can set this environment variable to make AnyEvent
838 more talkative. 897 more talkative.
… …
1343 1402
1344 Summary 1403 Summary
1345 * 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,
1346 as the management overhead dominates. 1405 as the management overhead dominates.
1347 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
1348SIGNALS 1465SIGNALS
1349 AnyEvent currently installs handlers for these signals: 1466 AnyEvent currently installs handlers for these signals:
1350 1467
1351 SIGCHLD 1468 SIGCHLD
1352 A handler for "SIGCHLD" is installed by AnyEvent's child watcher 1469 A handler for "SIGCHLD" is installed by AnyEvent's child watcher
… …
1387 1504
1388 You can make AnyEvent completely ignore this variable by deleting it 1505 You can make AnyEvent completely ignore this variable by deleting it
1389 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:
1390 1507
1391 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } 1508 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
1392 1509
1393 use AnyEvent; 1510 use AnyEvent;
1394 1511
1395 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can 1512 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1396 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
1397 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),
1398 and $ENV{PERL_ANYEGENT_STRICT}. 1515 and $ENV{PERL_ANYEVENT_STRICT}.
1399 1516
1400BUGS 1517BUGS
1401 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
1402 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
1403 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