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.4 by root, Sun Jul 10 20:57:00 2005 UTC vs.
Revision 1.13 by root, Mon Jul 11 01:49:14 2005 UTC

3IO::AIO - Asynchronous Input/Output 3IO::AIO - Asynchronous Input/Output
4 4
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use IO::AIO; 7 use IO::AIO;
8
9 aio_open "/etc/passwd", O_RDONLY, 0, sub {
10 my ($fh) = @_;
11 ...
12 };
13
14 aio_unlink "/tmp/file", sub { };
15
16 aio_read $fh, 30000, 1024, $buffer, 0, sub {
17 $_[0] > 0 or die "read error: $!";
18 };
19
20 # Event
21 Event->io (fd => IO::AIO::poll_fileno,
22 poll => 'r',
23 cb => \&IO::AIO::poll_cb);
24
25 # Glib/Gtk2
26 add_watch Glib::IO IO::AIO::poll_fileno,
27 \&IO::AIO::poll_cb;
28
29 # Tk
30 Tk::Event::IO->fileevent (IO::AIO::poll_fileno, "",
31 readable => \&IO::AIO::poll_cb);
32
33 # Danga::Socket
34 Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>
35 \&IO::AIO::poll_cb);
36
8 37
9=head1 DESCRIPTION 38=head1 DESCRIPTION
10 39
11This module implements asynchronous I/O using whatever means your 40This module implements asynchronous I/O using whatever means your
12operating system supports. 41operating system supports.
21remaining functionality would have to be implemented using threads anyway. 50remaining functionality would have to be implemented using threads anyway.
22 51
23Although the module will work with in the presence of other threads, it is 52Although the module will work with in the presence of other threads, it is
24currently not reentrant, so use appropriate locking yourself. 53currently not reentrant, so use appropriate locking yourself.
25 54
26=head2 API NOTES 55=cut
56
57package IO::AIO;
58
59use base 'Exporter';
60
61use Fcntl ();
62
63BEGIN {
64 $VERSION = 0.3;
65
66 @EXPORT = qw(aio_read aio_write aio_open aio_close aio_stat aio_lstat aio_unlink
67 aio_fsync aio_fdatasync aio_readahead);
68 @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel max_outstanding nreqs);
69
70 require XSLoader;
71 XSLoader::load IO::AIO, $VERSION;
72}
73
74=head1 FUNCTIONS
75
76=head2 AIO FUNCTIONS
27 77
28All the C<aio_*> calls are more or less thin wrappers around the syscall 78All the C<aio_*> calls are more or less thin wrappers around the syscall
29with the same name (sans C<aio_>). The arguments are similar or identical, 79with the same name (sans C<aio_>). The arguments are similar or identical,
30and they all accept an additional C<$callback> argument which must be 80and they all accept an additional C<$callback> argument which must be
31a code reference. This code reference will get called with the syscall 81a code reference. This code reference will get called with the syscall
39is that at the time the request is being executed, the current working 89is that at the time the request is being executed, the current working
40directory could have changed. Alternatively, you can make sure that you 90directory could have changed. Alternatively, you can make sure that you
41never change the current working directory. 91never change the current working directory.
42 92
43=over 4 93=over 4
44
45=cut
46
47package IO::AIO;
48
49use base 'Exporter';
50
51use Fcntl ();
52
53BEGIN {
54 $VERSION = 0.2;
55
56 @EXPORT = qw(aio_read aio_write aio_open aio_close aio_stat aio_lstat aio_unlink
57 aio_fsync aio_fdatasync aio_readahead);
58 @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel max_outstanding nreqs);
59
60 require XSLoader;
61 XSLoader::load IO::AIO, $VERSION;
62}
63
64=item IO::AIO::min_parallel $nthreads
65
66Set the minimum number of AIO threads to C<$nthreads>. The default is
67C<1>, which means a single asynchronous operation can be done at one time
68(the number of outstanding operations, however, is unlimited).
69
70It is recommended to keep the number of threads low, as some Linux
71kernel versions will scale negatively with the number of threads (higher
72parallelity => MUCH higher latency). With current Linux 2.6 versions, 4-32
73threads should be fine.
74
75Under normal circumstances you don't need to call this function, as this
76module automatically starts some threads (the exact number might change,
77and is currently 4).
78
79=item IO::AIO::max_parallel $nthreads
80
81Sets the maximum number of AIO threads to C<$nthreads>. If more than
82the specified number of threads are currently running, kill them. This
83function blocks until the limit is reached.
84
85This module automatically runs C<max_parallel 0> at program end, to ensure
86that all threads are killed and that there are no outstanding requests.
87
88Under normal circumstances you don't need to call this function.
89
90=item $oldnreqs = IO::AIO::max_outstanding $nreqs
91
92Sets the maximum number of outstanding requests to C<$nreqs>. If you
93try to queue up more than this number of requests, the caller will block until
94some requests have been handled.
95
96The default is very large, so normally there is no practical limit. If you
97queue up many requests in a loop it it often improves speed if you set
98this to a relatively low number, such as C<100>.
99
100Under normal circumstances you don't need to call this function.
101
102=item $fileno = IO::AIO::poll_fileno
103
104Return the I<request result pipe filehandle>. This filehandle must be
105polled for reading by some mechanism outside this module (e.g. Event
106or select, see below). If the pipe becomes readable you have to call
107C<poll_cb> to check the results.
108
109See C<poll_cb> for an example.
110
111=item IO::AIO::poll_cb
112
113Process all outstanding events on the result pipe. You have to call this
114regularly. Returns the number of events processed. Returns immediately
115when no events are outstanding.
116
117You can use Event to multiplex, e.g.:
118
119 Event->io (fd => IO::AIO::poll_fileno,
120 poll => 'r', async => 1,
121 cb => \&IO::AIO::poll_cb);
122
123=item IO::AIO::poll_wait
124
125Wait till the result filehandle becomes ready for reading (simply does a
126select on the filehandle. This is useful if you want to synchronously wait
127for some requests to finish).
128
129See C<nreqs> for an example.
130
131=item IO::AIO::nreqs
132
133Returns the number of requests currently outstanding.
134
135Example: wait till there are no outstanding requests anymore:
136
137 IO::AIO::poll_wait, IO::AIO::poll_cb
138 while IO::AIO::nreqs;
139 94
140=item aio_open $pathname, $flags, $mode, $callback 95=item aio_open $pathname, $flags, $mode, $callback
141 96
142Asynchronously open or create a file and call the callback with a newly 97Asynchronously open or create a file and call the callback with a newly
143created filehandle for the file. 98created filehandle for the file.
178 133
179Example: Read 15 bytes at offset 7 into scalar C<$buffer>, strating at 134Example: Read 15 bytes at offset 7 into scalar C<$buffer>, strating at
180offset C<0> within the scalar: 135offset C<0> within the scalar:
181 136
182 aio_read $fh, 7, 15, $buffer, 0, sub { 137 aio_read $fh, 7, 15, $buffer, 0, sub {
183 $_[0] >= 0 or die "read error: $!"; 138 $_[0] > 0 or die "read error: $!";
184 print "read <$buffer>\n"; 139 print "read $_[0] bytes: <$buffer>\n";
185 }; 140 };
186 141
187=item aio_readahead $fh,$offset,$length, $callback 142=item aio_readahead $fh,$offset,$length, $callback
188 143
189Asynchronously reads the specified byte range into the page cache, using 144Asynchronously reads the specified byte range into the page cache, using
234=item aio_fdatasync $fh, $callback 189=item aio_fdatasync $fh, $callback
235 190
236Asynchronously call fdatasync on the given filehandle and call the 191Asynchronously call fdatasync on the given filehandle and call the
237callback with the fdatasync result code. 192callback with the fdatasync result code.
238 193
194=back
195
196=head2 SUPPORT FUNCTIONS
197
198=over 4
199
200=item $fileno = IO::AIO::poll_fileno
201
202Return the I<request result pipe filehandle>. This filehandle must be
203polled for reading by some mechanism outside this module (e.g. Event
204or select, see below). If the pipe becomes readable you have to call
205C<poll_cb> to check the results.
206
207See C<poll_cb> for an example.
208
209=item IO::AIO::poll_cb
210
211Process all outstanding events on the result pipe. You have to call this
212regularly. Returns the number of events processed. Returns immediately
213when no events are outstanding.
214
215You can use Event to multiplex, e.g.:
216
217 Event->io (fd => IO::AIO::poll_fileno,
218 poll => 'r', async => 1,
219 cb => \&IO::AIO::poll_cb);
220
221=item IO::AIO::poll_wait
222
223Wait till the result filehandle becomes ready for reading (simply does a
224select on the filehandle. This is useful if you want to synchronously wait
225for some requests to finish).
226
227See C<nreqs> for an example.
228
229=item IO::AIO::nreqs
230
231Returns the number of requests currently outstanding.
232
233Example: wait till there are no outstanding requests anymore:
234
235 IO::AIO::poll_wait, IO::AIO::poll_cb
236 while IO::AIO::nreqs;
237
238=item IO::AIO::flush
239
240Wait till all outstanding AIO requests have been handled.
241
242Strictly equivalent to:
243
244 IO::AIO::poll_wait, IO::AIO::poll_cb
245 while IO::AIO::nreqs;
246
247=item IO::AIO::poll
248
249Waits until some requests have been handled.
250
251Strictly equivalent to:
252
253 IO::AIO::poll_wait, IO::AIO::poll_cb
254 if IO::AIO::nreqs;
255
256=item IO::AIO::min_parallel $nthreads
257
258Set the minimum number of AIO threads to C<$nthreads>. The default is
259C<1>, which means a single asynchronous operation can be done at one time
260(the number of outstanding operations, however, is unlimited).
261
262It is recommended to keep the number of threads low, as some Linux
263kernel versions will scale negatively with the number of threads (higher
264parallelity => MUCH higher latency). With current Linux 2.6 versions, 4-32
265threads should be fine.
266
267Under normal circumstances you don't need to call this function, as this
268module automatically starts some threads (the exact number might change,
269and is currently 4).
270
271=item IO::AIO::max_parallel $nthreads
272
273Sets the maximum number of AIO threads to C<$nthreads>. If more than
274the specified number of threads are currently running, kill them. This
275function blocks until the limit is reached.
276
277This module automatically runs C<max_parallel 0> at program end, to ensure
278that all threads are killed and that there are no outstanding requests.
279
280Under normal circumstances you don't need to call this function.
281
282=item $oldnreqs = IO::AIO::max_outstanding $nreqs
283
284Sets the maximum number of outstanding requests to C<$nreqs>. If you
285try to queue up more than this number of requests, the caller will block until
286some requests have been handled.
287
288The default is very large, so normally there is no practical limit. If you
289queue up many requests in a loop it it often improves speed if you set
290this to a relatively low number, such as C<100>.
291
292Under normal circumstances you don't need to call this function.
293
294=back
295
239=cut 296=cut
240 297
241# support function to convert a fd into a perl filehandle 298# support function to convert a fd into a perl filehandle
242sub _fd2fh { 299sub _fd2fh {
243 return undef if $_[0] < 0; 300 return undef if $_[0] < 0;
256 max_parallel 0; 313 max_parallel 0;
257} 314}
258 315
2591; 3161;
260 317
261=back
262
263=head1 BUGS
264
265 - could be optimized to use more semaphores instead of filehandles.
266
267=head1 SEE ALSO 318=head1 SEE ALSO
268 319
269L<Coro>, L<Linux::AIO>. 320L<Coro>, L<Linux::AIO>.
270 321
271=head1 AUTHOR 322=head1 AUTHOR

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines