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

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.246 by root, Sat Jul 18 15:51:52 2009 UTC vs.
Revision 1.250 by root, Mon Jul 20 07:12:38 2009 UTC

1=head1 NAME 1=head1 NAME
2 2
3AnyEvent - provide framework for multiple event loops 3AnyEvent - events independent of event loop implementation
4 4
5EV, Event, Glib, Tk, Perl, Event::Lib, Qt and POE are various supported 5EV, Event, Glib, Tk, Perl, Event::Lib, Qt and POE are various supported
6event loops. 6event loops.
7 7
8=head1 SYNOPSIS 8=head1 SYNOPSIS
… …
40=head1 INTRODUCTION/TUTORIAL 40=head1 INTRODUCTION/TUTORIAL
41 41
42This manpage is mainly a reference manual. If you are interested 42This manpage is mainly a reference manual. If you are interested
43in a tutorial or some gentle introduction, have a look at the 43in a tutorial or some gentle introduction, have a look at the
44L<AnyEvent::Intro> manpage. 44L<AnyEvent::Intro> manpage.
45
46=head1 SUPPORT
47
48There is a mailinglist for discussing all things AnyEvent, and an IRC
49channel, too.
50
51See the AnyEvent project page at the B<Schmorpforge Ta-Sa Software
52Respository>, at L<http://anyevent.schmorp.de>, for more info.
45 53
46=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT) 54=head1 WHY YOU SHOULD USE THIS MODULE (OR NOT)
47 55
48Glib, POE, IO::Async, Event... CPAN offers event models by the dozen 56Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
49nowadays. So what is different about AnyEvent? 57nowadays. So what is different about AnyEvent?
… …
368 376
369This watcher might use C<%SIG> (depending on the event loop used), 377This watcher might use C<%SIG> (depending on the event loop used),
370so programs overwriting those signals directly will likely not work 378so programs overwriting those signals directly will likely not work
371correctly. 379correctly.
372 380
381Example: exit on SIGINT
382
383 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
384
385=head3 Signal Races, Delays and Workarounds
386
373Also note that many event loops (e.g. Glib, Tk, Qt, IO::Async) do not 387Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching
374support attaching callbacks to signals, which is a pity, as you cannot do 388callbacks to signals in a generic way, which is a pity, as you cannot do
375race-free signal handling in perl. AnyEvent will try to do it's best, but 389race-free signal handling in perl. AnyEvent will try to do it's best, but
376in some cases, signals will be delayed. The maximum time a signal might 390in some cases, signals will be delayed. The maximum time a signal might
377be delayed is specified in C<$AnyEvent::MAX_SIGNAL_LATENCY> (default: 10 391be delayed is specified in C<$AnyEvent::MAX_SIGNAL_LATENCY> (default: 10
378seconds). This variable can be changed only before the first signal 392seconds). This variable can be changed only before the first signal
379watcher is created, and should be left alone otherwise. Higher values 393watcher is created, and should be left alone otherwise. Higher values
380will cause fewer spurious wake-ups, which is better for power and CPU 394will cause fewer spurious wake-ups, which is better for power and CPU
381saving. All these problems can be avoided by installing the optional 395saving. All these problems can be avoided by installing the optional
382L<Async::Interrupt> module. 396L<Async::Interrupt> module. This will not work with inherently broken
383 397event loops such as L<Event> or L<Event::Lib> (and not with L<POE>
384Example: exit on SIGINT 398currently, as POE does it's own workaround with one-second latency). With
385 399those, you just have to suffer the delays.
386 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
387 400
388=head2 CHILD PROCESS WATCHERS 401=head2 CHILD PROCESS WATCHERS
389 402
390You can also watch on a child process exit and catch its exit status. 403You can also watch on a child process exit and catch its exit status.
391 404
… …
504Condition variables are similar to callbacks, except that you can 517Condition variables are similar to callbacks, except that you can
505optionally wait for them. They can also be called merge points - points 518optionally wait for them. They can also be called merge points - points
506in time where multiple outstanding events have been processed. And yet 519in time where multiple outstanding events have been processed. And yet
507another way to call them is transactions - each condition variable can be 520another way to call them is transactions - each condition variable can be
508used to represent a transaction, which finishes at some point and delivers 521used to represent a transaction, which finishes at some point and delivers
509a result. 522a result. And yet some people know them as "futures" - a promise to
523compute/deliver something that you can wait for.
510 524
511Condition variables are very useful to signal that something has finished, 525Condition variables are very useful to signal that something has finished,
512for example, if you write a module that does asynchronous http requests, 526for example, if you write a module that does asynchronous http requests,
513then a condition variable would be the ideal candidate to signal the 527then a condition variable would be the ideal candidate to signal the
514availability of results. The user can either act when the callback is 528availability of results. The user can either act when the callback is
… …
2270 2284
2271This slightly arcane module is used to implement fast signal handling: To 2285This slightly arcane module is used to implement fast signal handling: To
2272my knowledge, there is no way to do completely race-free and quick 2286my knowledge, there is no way to do completely race-free and quick
2273signal handling in pure perl. To ensure that signals still get 2287signal handling in pure perl. To ensure that signals still get
2274delivered, AnyEvent will start an interval timer to wake up perl (and 2288delivered, AnyEvent will start an interval timer to wake up perl (and
2275catch the signals) with soemd elay (default is 10 seconds, look for 2289catch the signals) with some delay (default is 10 seconds, look for
2276C<$AnyEvent::MAX_SIGNAL_LATENCY>). 2290C<$AnyEvent::MAX_SIGNAL_LATENCY>).
2277 2291
2278If this module is available, then it will be used to implement signal 2292If this module is available, then it will be used to implement signal
2279catching, which means that signals will not be delayed, and the event loop 2293catching, which means that signals will not be delayed, and the event loop
2280will not be interrupted regularly, which is more efficient (And good for 2294will not be interrupted regularly, which is more efficient (And good for
2281battery life on laptops). 2295battery life on laptops).
2282 2296
2283This affects not just the pure-perl event loop, but also other event loops 2297This affects not just the pure-perl event loop, but also other event loops
2284that have no signal handling on their own (e.g. Glib, Tk, Qt). 2298that have no signal handling on their own (e.g. Glib, Tk, Qt).
2299
2300Some event loops (POE, Event, Event::Lib) offer signal watchers natively,
2301and either employ their own workarounds (POE) or use AnyEvent's workaround
2302(using C<$AnyEvent::MAX_SIGNAL_LATENCY>). Installing L<Async::Interrupt>
2303does nothing for those backends.
2285 2304
2286=item L<EV> 2305=item L<EV>
2287 2306
2288This module isn't really "optional", as it is simply one of the backend 2307This module isn't really "optional", as it is simply one of the backend
2289event loops that AnyEvent can use. However, it is simply the best event 2308event loops that AnyEvent can use. However, it is simply the best event
… …
2303 2322
2304=item L<JSON> and L<JSON::XS> 2323=item L<JSON> and L<JSON::XS>
2305 2324
2306This module is required when you want to read or write JSON data via 2325This module is required when you want to read or write JSON data via
2307L<AnyEvent::Handle>. It is also written in pure-perl, but can take 2326L<AnyEvent::Handle>. It is also written in pure-perl, but can take
2308advantage of the ulta-high-speed L<JSON::XS> module when it is installed. 2327advantage of the ultra-high-speed L<JSON::XS> module when it is installed.
2309 2328
2310In fact, L<AnyEvent::Handle> will use L<JSON::XS> by default if it is 2329In fact, L<AnyEvent::Handle> will use L<JSON::XS> by default if it is
2311installed. 2330installed.
2312 2331
2313=item L<Net::SSLeay> 2332=item L<Net::SSLeay>

Diff Legend

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