--- AnyEvent/README 2008/06/22 12:17:47 1.27 +++ AnyEvent/README 2008/07/29 10:20:33 1.29 @@ -7,17 +7,26 @@ SYNOPSIS use AnyEvent; - my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub { - ... - }); + my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub { ... }); + + my $w = AnyEvent->timer (after => $seconds, cb => sub { ... }); + my $w = AnyEvent->timer (after => $seconds, interval => $seconds, cb => ... + + print AnyEvent->now; # prints current event loop time + print AnyEvent->time; # think Time::HiRes::time or simply CORE::time. + + my $w = AnyEvent->signal (signal => "TERM", cb => sub { ... }); - my $w = AnyEvent->timer (after => $seconds, cb => sub { + my $w = AnyEvent->child (pid => $pid, cb => sub { + my ($pid, $status) = @_; ... }); my $w = AnyEvent->condvar; # stores whether a condition was flagged $w->send; # wake up current and all future recv's $w->recv; # enters "main loop" till $condvar gets ->send + # use a condvar in callback mode: + $w->cb (sub { $_[0]->recv }); INTRODUCTION/TUTORIAL This manpage is mainly a reference manual. If you are interested in a @@ -32,11 +41,12 @@ policy* and AnyEvent is *small and efficient*. First and foremost, *AnyEvent is not an event model* itself, it only - interfaces to whatever event model the main program happens to use in a + interfaces to whatever event model the main program happens to use, in a pragmatic way. For event models and certain classes of immortals alike, the statement "there can only be one" is a bitter reality: In general, only one event loop can be active at the same time in a process. - AnyEvent helps hiding the differences between those event loops. + AnyEvent cannot change this, but it can hide the differences between + those event loops. The goal of AnyEvent is to offer module authors the ability to do event programming (waiting for I/O or timer events) without subscribing to a @@ -47,8 +57,8 @@ For modules like POE or IO::Async (which is a total misnomer as it is actually doing all I/O *synchronously*...), using them in your module is like joining a cult: After you joined, you are dependent on them and you - cannot use anything else, as it is simply incompatible to everything - that isn't itself. What's worse, all the potential users of your module + cannot use anything else, as they are simply incompatible to everything + that isn't them. What's worse, all the potential users of your module are *also* forced to use the same event loop you use. AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works @@ -56,9 +66,9 @@ with the rest: POE + IO::Async? No go. Tk + Event? No go. Again: if your module uses one of those, every user of your module has to use it, too. But if your module uses AnyEvent, it works transparently with all event - models it supports (including stuff like POE and IO::Async, as long as - those use one of the supported event loops. It is trivial to add new - event loops to AnyEvent, too, so it is future-proof). + models it supports (including stuff like IO::Async, as long as those use + one of the supported event loops. It is trivial to add new event loops + to AnyEvent, too, so it is future-proof). In addition to being free of having to use *the one and only true event model*, AnyEvent also is free of bloat and policy: with POE or similar @@ -148,7 +158,8 @@ You can create an I/O watcher by calling the "AnyEvent->io" method with the following mandatory key-value pairs as arguments: - "fh" the Perl *file handle* (*not* file descriptor) to watch for events. + "fh" the Perl *file handle* (*not* file descriptor) to watch for events + (AnyEvent might or might not keep a reference to this file handle). "poll" must be a string that is either "r" or "w", which creates a watcher waiting for "r"eadable or "w"ritable events, respectively. "cb" is the callback to invoke each time the file handle becomes ready. @@ -165,9 +176,9 @@ always use non-blocking calls when reading/writing from/to your file handles. - Example: + Example: wait for readability of STDIN, then read a line and disable the + watcher. - # wait for readability of STDIN, then read a line and disable the watcher my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub { chomp (my $input = ); warn "read: $input\n"; @@ -186,13 +197,18 @@ presence is undefined and you cannot rely on them. Portable AnyEvent callbacks cannot use arguments passed to time watcher callbacks. - The timer callback will be invoked at most once: if you want a repeating - timer you have to create a new watcher (this is a limitation by both Tk - and Glib). + The callback will normally be invoked once only. If you specify another + parameter, "interval", as a strictly positive number (> 0), then the + callback will be invoked regularly at that interval (in fractional + seconds) after the first invocation. If "interval" is specified with a + false value, then it is treated as if it were missing. + + The callback will be rescheduled before invoking the callback, but no + attempt is done to avoid timer drift in most backends, so the interval + is only approximate. - Example: + Example: fire an event after 7.7 seconds. - # fire an event after 7.7 seconds my $w = AnyEvent->timer (after => 7.7, cb => sub { warn "timeout\n"; }); @@ -200,19 +216,12 @@ # to cancel the timer: undef $w; - Example 2: + Example 2: fire an event after 0.5 seconds, then roughly every second. - # fire an event after 0.5 seconds, then roughly every second - my $w; - - my $cb = sub { - # cancel the old timer while creating a new one - $w = AnyEvent->timer (after => 1, cb => $cb); + my $w = AnyEvent->timer (after => 0.5, interval => 1, cb => sub { + warn "timeout\n"; }; - # start the "loop" by creating the first watcher - $w = AnyEvent->timer (after => 0.5, cb => $cb); - TIMING ISSUES There are two ways to handle timers: based on real time (relative, "fire in 10 seconds") and based on wallclock time (absolute, "fire at 12 @@ -297,8 +306,8 @@ SIGNAL WATCHERS You can watch for signals using a signal watcher, "signal" is the signal - *name* without any "SIG" prefix, "cb" is the Perl callback to be invoked - whenever a signal occurs. + *name* in uppercase and without any "SIG" prefix, "cb" is the Perl + callback to be invoked whenever a signal occurs. Although the callback might get passed parameters, their value and presence is undefined and you cannot rely on them. Portable AnyEvent @@ -373,8 +382,10 @@ Condition variables can be created by calling the "AnyEvent->condvar" method, usually without arguments. The only argument pair allowed is + "cb", which specifies a callback to be called when the condition - variable becomes true. + variable becomes true, with the condition variable as the first argument + (but not the results). After creation, the condition variable is "false" until it becomes "true" by calling the "send" method (or calling the condition variable @@ -440,6 +451,23 @@ my $delay = AnyEvent->timer (after => 5, cb => $done); $done->recv; + Example: Imagine an API that returns a condvar and doesn't support + callbacks. This is how you make a synchronous call, for example from the + main program: + + use AnyEvent::CouchDB; + + ... + + my @info = $couchdb->info->recv; + + And this is how you would just ste a callback to be called whenever the + results are available: + + $couchdb->info->cb (sub { + my @info = $_[0]->recv; + }); + METHODS FOR PRODUCERS These methods should only be used by the producing side, i.e. the code/module that eventually sends the signal. Note that it is also the @@ -569,7 +597,7 @@ Returns true when the condition is "true", i.e. whether "send" or "croak" have been called. - $cb = $cv->cb ([new callback]) + $cb = $cv->cb ($cb->($cv)) This is a mutator function that returns the callback set and optionally replaces it before doing so. @@ -700,16 +728,17 @@ blocking functions such as "inet_aton" by event-/callback-based versions. - AnyEvent::Handle - Provide read and write buffers and manages watchers for reads and - writes. - AnyEvent::Socket Provides various utility functions for (internet protocol) sockets, addresses and name resolution. Also functions to create non-blocking tcp connections or tcp servers, with IPv6 and SRV record support and more. + AnyEvent::Handle + Provide read and write buffers, manages watchers for reads and + writes, supports raw and formatted I/O, I/O queued and fully + transparent and non-blocking SSL/TLS. + AnyEvent::DNS Provides rich asynchronous DNS resolver capabilities. @@ -726,6 +755,23 @@ AnyEvent::DBI Executes DBI requests asynchronously in a proxy process. + AnyEvent::AIO + Truly asynchronous I/O, should be in the toolbox of every event + programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent + together. + + AnyEvent::BDB + Truly asynchronous Berkeley DB access. AnyEvent::BDB transparently + fuses BDB and AnyEvent together. + + AnyEvent::GPSD + A non-blocking interface to gpsd, a daemon delivering GPS + information. + + AnyEvent::IGS + A non-blocking interface to the Internet Go Server protocol (used by + App::IGS). + Net::IRC3 AnyEvent based IRC client module family. @@ -742,15 +788,6 @@ Coro Has special support for AnyEvent via Coro::AnyEvent. - AnyEvent::AIO, IO::AIO - Truly asynchronous I/O, should be in the toolbox of every event - programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent - together. - - AnyEvent::BDB, BDB - Truly asynchronous Berkeley DB access. AnyEvent::AIO transparently - fuses IO::AIO and AnyEvent together. - IO::Lambda The lambda approach to I/O - don't ask, look there. Can use AnyEvent. @@ -813,6 +850,18 @@ When set to 2 or higher, cause AnyEvent to report to STDERR which event model it chooses. + "PERL_ANYEVENT_STRICT" + AnyEvent does not do much argument checking by default, as thorough + argument checking is very costly. Setting this variable to a true + value will cause AnyEvent to load "AnyEvent::Strict" and then to + thoroughly check the arguments passed to most method calls. If it + finds any problems it will croak. + + In other words, enables "strict" mode. + + Unlike "use strict" it is definitely recommended ot keep it off in + production. + "PERL_ANYEVENT_MODEL" This can be used to specify the event model to be used by AnyEvent, before auto detection and -probing kicks in. It must be a string @@ -1283,7 +1332,8 @@ Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can be used to probe what backend is used and gain other information (which - is probably even less useful to an attacker than PERL_ANYEVENT_MODEL). + is probably even less useful to an attacker than PERL_ANYEVENT_MODEL), + and $ENV{PERL_ANYEGENT_STRICT}. BUGS Perl 5.8 has numerous memleaks that sometimes hit this module and are