ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/IO-AIO/AIO.pm
(Generate patch)

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.155 by root, Sun Jun 14 20:36:59 2009 UTC vs.
Revision 1.156 by root, Tue Jun 16 23:41:59 2009 UTC

… …
30 30
31 # AnyEvent integration (EV, Event, Glib, Tk, POE, urxvt, pureperl...) 31 # AnyEvent integration (EV, Event, Glib, Tk, POE, urxvt, pureperl...)
32 use AnyEvent::AIO; 32 use AnyEvent::AIO;
33 33
34 # EV integration 34 # EV integration
35 my $w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb; 35 my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
36 36
37 # Event integration 37 # Event integration
38 Event->io (fd => IO::AIO::poll_fileno, 38 Event->io (fd => IO::AIO::poll_fileno,
39 poll => 'r', 39 poll => 'r',
40 cb => \&IO::AIO::poll_cb); 40 cb => \&IO::AIO::poll_cb);
… …
52 \&IO::AIO::poll_cb); 52 \&IO::AIO::poll_cb);
53 53
54=head1 DESCRIPTION 54=head1 DESCRIPTION
55 55
56This module implements asynchronous I/O using whatever means your 56This module implements asynchronous I/O using whatever means your
57operating system supports. 57operating system supports. It is implemented as an interface to C<libeio>
58(L<http://software.schmorp.de/pkg/libeio.html>).
58 59
59Asynchronous means that operations that can normally block your program 60Asynchronous means that operations that can normally block your program
60(e.g. reading from disk) will be done asynchronously: the operation 61(e.g. reading from disk) will be done asynchronously: the operation
61will still block, but you can do something else in the meantime. This 62will still block, but you can do something else in the meantime. This
62is extremely useful for programs that need to stay interactive even 63is extremely useful for programs that need to stay interactive even
… …
66on a RAID volume or over NFS when you do a number of stat operations 67on a RAID volume or over NFS when you do a number of stat operations
67concurrently. 68concurrently.
68 69
69While most of this works on all types of file descriptors (for 70While most of this works on all types of file descriptors (for
70example sockets), using these functions on file descriptors that 71example sockets), using these functions on file descriptors that
71support nonblocking operation (again, sockets, pipes etc.) is very 72support nonblocking operation (again, sockets, pipes etc.) is
72inefficient. Use an event loop for that (such as the L<Event|Event> 73very inefficient. Use an event loop for that (such as the L<EV>
73module): IO::AIO will naturally fit into such an event loop itself. 74module): IO::AIO will naturally fit into such an event loop itself.
74 75
75In this version, a number of threads are started that execute your 76In this version, a number of threads are started that execute your
76requests and signal their completion. You don't need thread support 77requests and signal their completion. You don't need thread support
77in perl, and the threads created by this module will not be visible 78in perl, and the threads created by this module will not be visible
… …
87yourself, always call C<poll_cb> from within the same thread, or never 88yourself, always call C<poll_cb> from within the same thread, or never
88call C<poll_cb> (or other C<aio_> functions) recursively. 89call C<poll_cb> (or other C<aio_> functions) recursively.
89 90
90=head2 EXAMPLE 91=head2 EXAMPLE
91 92
92This is a simple example that uses the Event module and loads 93This is a simple example that uses the EV module and loads
93F</etc/passwd> asynchronously: 94F</etc/passwd> asynchronously:
94 95
95 use Fcntl; 96 use Fcntl;
96 use Event; 97 use EV;
97 use IO::AIO; 98 use IO::AIO;
98 99
99 # register the IO::AIO callback with Event 100 # register the IO::AIO callback with EV
100 Event->io (fd => IO::AIO::poll_fileno, 101 my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
101 poll => 'r',
102 cb => \&IO::AIO::poll_cb);
103 102
104 # queue the request to open /etc/passwd 103 # queue the request to open /etc/passwd
105 aio_open "/etc/passwd", O_RDONLY, 0, sub { 104 aio_open "/etc/passwd", O_RDONLY, 0, sub {
106 my $fh = shift 105 my $fh = shift
107 or die "error while opening: $!"; 106 or die "error while opening: $!";
… …
119 118
120 # file contents now in $contents 119 # file contents now in $contents
121 print $contents; 120 print $contents;
122 121
123 # exit event loop and program 122 # exit event loop and program
124 Event::unloop; 123 EV::unloop;
125 }; 124 };
126 }; 125 };
127 126
128 # possibly queue up other requests, or open GUI windows, 127 # possibly queue up other requests, or open GUI windows,
129 # check for sockets etc. etc. 128 # check for sockets etc. etc.
130 129
131 # process events as long as there are some: 130 # process events as long as there are some:
132 Event::loop; 131 EV::loop;
133 132
134=head1 REQUEST ANATOMY AND LIFETIME 133=head1 REQUEST ANATOMY AND LIFETIME
135 134
136Every C<aio_*> function creates a request. which is a C data structure not 135Every C<aio_*> function creates a request. which is a C data structure not
137directly visible to Perl. 136directly visible to Perl.
… …
1208=over 4 1207=over 4
1209 1208
1210=item $fileno = IO::AIO::poll_fileno 1209=item $fileno = IO::AIO::poll_fileno
1211 1210
1212Return the I<request result pipe file descriptor>. This filehandle must be 1211Return the I<request result pipe file descriptor>. This filehandle must be
1213polled for reading by some mechanism outside this module (e.g. Event or 1212polled for reading by some mechanism outside this module (e.g. EV, Glib,
1214select, see below or the SYNOPSIS). If the pipe becomes readable you have 1213select and so on, see below or the SYNOPSIS). If the pipe becomes readable
1215to call C<poll_cb> to check the results. 1214you have to call C<poll_cb> to check the results.
1216 1215
1217See C<poll_cb> for an example. 1216See C<poll_cb> for an example.
1218 1217
1219=item IO::AIO::poll_cb 1218=item IO::AIO::poll_cb
1220 1219
… …
1227If not all requests were processed for whatever reason, the filehandle 1226If not all requests were processed for whatever reason, the filehandle
1228will still be ready when C<poll_cb> returns, so normally you don't have to 1227will still be ready when C<poll_cb> returns, so normally you don't have to
1229do anything special to have it called later. 1228do anything special to have it called later.
1230 1229
1231Example: Install an Event watcher that automatically calls 1230Example: Install an Event watcher that automatically calls
1232IO::AIO::poll_cb with high priority: 1231IO::AIO::poll_cb with high priority (more examples can be found in the
1232SYNOPSIS section, at the top of this document):
1233 1233
1234 Event->io (fd => IO::AIO::poll_fileno, 1234 Event->io (fd => IO::AIO::poll_fileno,
1235 poll => 'r', async => 1, 1235 poll => 'r', async => 1,
1236 cb => \&IO::AIO::poll_cb); 1236 cb => \&IO::AIO::poll_cb);
1237 1237

Diff Legend

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