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.228 by root, Wed Jul 8 01:11:12 2009 UTC vs.
Revision 1.231 by root, Wed Jul 8 13:46:46 2009 UTC

… …
176=head2 I/O WATCHERS 176=head2 I/O WATCHERS
177 177
178You can create an I/O watcher by calling the C<< AnyEvent->io >> method 178You can create an I/O watcher by calling the C<< AnyEvent->io >> method
179with the following mandatory key-value pairs as arguments: 179with the following mandatory key-value pairs as arguments:
180 180
181C<fh> is the Perl I<file handle> (I<not> file descriptor, see below) to 181C<fh> is the Perl I<file handle> (or a naked file descriptor) to watch
182watch for events (AnyEvent might or might not keep a reference to this 182for events (AnyEvent might or might not keep a reference to this file
183file handle). Note that only file handles pointing to things for which 183handle). Note that only file handles pointing to things for which
184non-blocking operation makes sense are allowed. This includes sockets, 184non-blocking operation makes sense are allowed. This includes sockets,
185most character devices, pipes, fifos and so on, but not for example files 185most character devices, pipes, fifos and so on, but not for example files
186or block devices. 186or block devices.
187 187
188C<poll> must be a string that is either C<r> or C<w>, which creates a 188C<poll> must be a string that is either C<r> or C<w>, which creates a
… …
208 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub { 208 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
209 chomp (my $input = <STDIN>); 209 chomp (my $input = <STDIN>);
210 warn "read: $input\n"; 210 warn "read: $input\n";
211 undef $w; 211 undef $w;
212 }); 212 });
213
214=head3 GETTING A FILE HANDLE FROM A FILE DESCRIPTOR
215
216It is not uncommon to only have a file descriptor, while AnyEvent requires
217a Perl file handle.
218
219There are basically two methods to convert a file descriptor into a file handle. If you own
220the file descriptor, you can open it with C<&=>, as in:
221
222 open my $fh, "<&=$fileno" or die "xxx: ยง!";
223
224This will "own" the file descriptor, meaning that when C<$fh> is
225destroyed, it will automatically close the C<$fileno>. Also, note that
226the open mode (read, write, read/write) must correspond with how the
227underlying file descriptor was opened.
228
229In many cases, taking over the file descriptor is now what you want, in
230which case the only alternative is to dup the file descriptor:
231
232 open my $fh, "<&$fileno" or die "xxx: $!";
233
234This has the advantage of not closing the file descriptor and the
235disadvantage of making a slow copy.
236 213
237=head2 TIME WATCHERS 214=head2 TIME WATCHERS
238 215
239You can create a time watcher by calling the C<< AnyEvent->timer >> 216You can create a time watcher by calling the C<< AnyEvent->timer >>
240method with the following mandatory arguments: 217method with the following mandatory arguments:
… …
891 868
892 869
893=head1 OTHER MODULES 870=head1 OTHER MODULES
894 871
895The following is a non-exhaustive list of additional modules that use 872The following is a non-exhaustive list of additional modules that use
896AnyEvent and can therefore be mixed easily with other AnyEvent modules 873AnyEvent as a client and can therefore be mixed easily with other AnyEvent
897in the same program. Some of the modules come with AnyEvent, some are 874modules and other event loops in the same program. Some of the modules
898available via CPAN. 875come with AnyEvent, most are available via CPAN.
899 876
900=over 4 877=over 4
901 878
902=item L<AnyEvent::Util> 879=item L<AnyEvent::Util>
903 880
… …
912 889
913=item L<AnyEvent::Handle> 890=item L<AnyEvent::Handle>
914 891
915Provide read and write buffers, manages watchers for reads and writes, 892Provide read and write buffers, manages watchers for reads and writes,
916supports raw and formatted I/O, I/O queued and fully transparent and 893supports raw and formatted I/O, I/O queued and fully transparent and
917non-blocking SSL/TLS. 894non-blocking SSL/TLS (via L<AnyEvent::TLS>.
918 895
919=item L<AnyEvent::DNS> 896=item L<AnyEvent::DNS>
920 897
921Provides rich asynchronous DNS resolver capabilities. 898Provides rich asynchronous DNS resolver capabilities.
922 899
… …
950 927
951=item L<AnyEvent::GPSD> 928=item L<AnyEvent::GPSD>
952 929
953A non-blocking interface to gpsd, a daemon delivering GPS information. 930A non-blocking interface to gpsd, a daemon delivering GPS information.
954 931
932=item L<AnyEvent::IRC>
933
934AnyEvent based IRC client module family (replacing the older Net::IRC3).
935
936=item L<AnyEvent::XMPP>
937
938AnyEvent based XMPP (Jabber protocol) module family (replacing the older
939Net::XMPP2>.
940
955=item L<AnyEvent::IGS> 941=item L<AnyEvent::IGS>
956 942
957A non-blocking interface to the Internet Go Server protocol (used by 943A non-blocking interface to the Internet Go Server protocol (used by
958L<App::IGS>). 944L<App::IGS>).
959 945
960=item L<AnyEvent::IRC>
961
962AnyEvent based IRC client module family (replacing the older Net::IRC3).
963
964=item L<Net::XMPP2>
965
966AnyEvent based XMPP (Jabber protocol) module family.
967
968=item L<Net::FCP> 946=item L<Net::FCP>
969 947
970AnyEvent-based implementation of the Freenet Client Protocol, birthplace 948AnyEvent-based implementation of the Freenet Client Protocol, birthplace
971of AnyEvent. 949of AnyEvent.
972 950
… …
976 954
977=item L<Coro> 955=item L<Coro>
978 956
979Has special support for AnyEvent via L<Coro::AnyEvent>. 957Has special support for AnyEvent via L<Coro::AnyEvent>.
980 958
981=item L<IO::Lambda>
982
983The lambda approach to I/O - don't ask, look there. Can use AnyEvent.
984
985=back 959=back
986 960
987=cut 961=cut
988 962
989package AnyEvent; 963package AnyEvent;
… …
991no warnings; 965no warnings;
992use strict qw(vars subs); 966use strict qw(vars subs);
993 967
994use Carp; 968use Carp;
995 969
996our $VERSION = 4.8; 970our $VERSION = 4.801;
997our $MODEL; 971our $MODEL;
998 972
999our $AUTOLOAD; 973our $AUTOLOAD;
1000our @ISA; 974our @ISA;
1001 975
… …
1146# allow only one watcher per fd, so we dup it to get a different one). 1120# allow only one watcher per fd, so we dup it to get a different one).
1147sub _dupfh($$;$$) { 1121sub _dupfh($$;$$) {
1148 my ($poll, $fh, $r, $w) = @_; 1122 my ($poll, $fh, $r, $w) = @_;
1149 1123
1150 # cygwin requires the fh mode to be matching, unix doesn't 1124 # cygwin requires the fh mode to be matching, unix doesn't
1151 my ($rw, $mode) = $poll eq "r" ? ($r, "<") 1125 my ($rw, $mode) = $poll eq "r" ? ($r, "<") : ($w, ">");
1152 : $poll eq "w" ? ($w, ">")
1153 : Carp::croak "AnyEvent->io requires poll set to either 'r' or 'w'";
1154 1126
1155 open my $fh2, "$mode&" . fileno $fh 1127 open my $fh2, "$mode&", $fh
1156 or die "cannot dup() filehandle: $!,"; 1128 or die "AnyEvent->io: cannot dup() filehandle in mode '$poll': $!,";
1157 1129
1158 # we assume CLOEXEC is already set by perl in all important cases 1130 # we assume CLOEXEC is already set by perl in all important cases
1159 1131
1160 ($fh2, $rw) 1132 ($fh2, $rw)
1161} 1133}
… …
2144L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>. 2116L<Glib>, L<Tk>, L<Event::Lib>, L<Qt>, L<POE>.
2145 2117
2146Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>, 2118Implementations: L<AnyEvent::Impl::EV>, L<AnyEvent::Impl::Event>,
2147L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>, 2119L<AnyEvent::Impl::Glib>, L<AnyEvent::Impl::Tk>, L<AnyEvent::Impl::Perl>,
2148L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>, 2120L<AnyEvent::Impl::EventLib>, L<AnyEvent::Impl::Qt>,
2149L<AnyEvent::Impl::POE>. 2121L<AnyEvent::Impl::POE>, L<AnyEvent::Impl::IOAsync>.
2150 2122
2151Non-blocking file handles, sockets, TCP clients and 2123Non-blocking file handles, sockets, TCP clients and
2152servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>. 2124servers: L<AnyEvent::Handle>, L<AnyEvent::Socket>, L<AnyEvent::TLS>.
2153 2125
2154Asynchronous DNS: L<AnyEvent::DNS>. 2126Asynchronous DNS: L<AnyEvent::DNS>.
2155 2127
2156Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>, L<Coro::Event>, 2128Coroutine support: L<Coro>, L<Coro::AnyEvent>, L<Coro::EV>,
2129L<Coro::Event>,
2157 2130
2158Nontrivial usage examples: L<Net::FCP>, L<Net::XMPP2>, L<AnyEvent::DNS>. 2131Nontrivial usage examples: L<AnyEvent::GPSD>, L<AnyEvent::XMPP>,
2132L<AnyEvent::HTTP>.
2159 2133
2160 2134
2161=head1 AUTHOR 2135=head1 AUTHOR
2162 2136
2163 Marc Lehmann <schmorp@schmorp.de> 2137 Marc Lehmann <schmorp@schmorp.de>

Diff Legend

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