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.2 by root, Sun Jul 10 18:16:49 2005 UTC vs.
Revision 1.5 by root, Sun Jul 10 21:04:24 2005 UTC

… …
21remaining functionality would have to be implemented using threads anyway. 21remaining functionality would have to be implemented using threads anyway.
22 22
23Although the module will work with in the presence of other threads, it is 23Although the module will work with in the presence of other threads, it is
24currently not reentrant, so use appropriate locking yourself. 24currently not reentrant, so use appropriate locking yourself.
25 25
26=head2 API NOTES 26=cut
27
28package IO::AIO;
29
30use base 'Exporter';
31
32use Fcntl ();
33
34BEGIN {
35 $VERSION = 0.2;
36
37 @EXPORT = qw(aio_read aio_write aio_open aio_close aio_stat aio_lstat aio_unlink
38 aio_fsync aio_fdatasync aio_readahead);
39 @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel max_outstanding nreqs);
40
41 require XSLoader;
42 XSLoader::load IO::AIO, $VERSION;
43}
44
45=head1 FUNCTIONS
46
47=head2 AIO FUNCTIONS
27 48
28All the C<aio_*> calls are more or less thin wrappers around the syscall 49All 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, 50with the same name (sans C<aio_>). The arguments are similar or identical,
30and they all accept an additional C<$callback> argument which must be 51and they all accept an additional C<$callback> argument which must be
31a code reference. This code reference will get called with the syscall 52a code reference. This code reference will get called with the syscall
… …
39is that at the time the request is being executed, the current working 60is that at the time the request is being executed, the current working
40directory could have changed. Alternatively, you can make sure that you 61directory could have changed. Alternatively, you can make sure that you
41never change the current working directory. 62never change the current working directory.
42 63
43=over 4 64=over 4
44
45=cut
46
47package IO::AIO;
48
49use base 'Exporter';
50
51use Fcntl ();
52
53BEGIN {
54 $VERSION = 0.1;
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 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).
73
74Under normal circumstances you don't need to call this function, as this
75module automatically starts a single async thread.
76
77=item IO::AIO::max_parallel $nthreads
78
79Sets the maximum number of AIO threads to C<$nthreads>. If more than
80the specified number of threads are currently running, kill them. This
81function blocks until the limit is reached.
82
83This module automatically runs C<max_parallel 0> at program end, to ensure
84that all threads are killed and that there are no outstanding requests.
85
86Under normal circumstances you don't need to call this function.
87
88=item $fileno = IO::AIO::poll_fileno
89
90Return the I<request result pipe filehandle>. This filehandle must be
91polled for reading by some mechanism outside this module (e.g. Event
92or select, see below). If the pipe becomes readable you have to call
93C<poll_cb> to check the results.
94
95See C<poll_cb> for an example.
96
97=item IO::AIO::poll_cb
98
99Process all outstanding events on the result pipe. You have to call this
100regularly. Returns the number of events processed. Returns immediately
101when no events are outstanding.
102
103You can use Event to multiplex, e.g.:
104
105 Event->io (fd => IO::AIO::poll_fileno,
106 poll => 'r', async => 1,
107 cb => \&IO::AIO::poll_cb);
108
109=item IO::AIO::poll_wait
110
111Wait till the result filehandle becomes ready for reading (simply does a
112select on the filehandle. This is useful if you want to synchronously wait
113for some requests to finish).
114
115See C<nreqs> for an example.
116
117=item IO::AIO::nreqs
118
119Returns the number of requests currently outstanding.
120
121Example: wait till there are no outstanding requests anymore:
122
123 IO::AIO::poll_wait, IO::AIO::poll_cb
124 while IO::AIO::nreqs;
125 65
126=item aio_open $pathname, $flags, $mode, $callback 66=item aio_open $pathname, $flags, $mode, $callback
127 67
128Asynchronously open or create a file and call the callback with a newly 68Asynchronously open or create a file and call the callback with a newly
129created filehandle for the file. 69created filehandle for the file.
… …
220=item aio_fdatasync $fh, $callback 160=item aio_fdatasync $fh, $callback
221 161
222Asynchronously call fdatasync on the given filehandle and call the 162Asynchronously call fdatasync on the given filehandle and call the
223callback with the fdatasync result code. 163callback with the fdatasync result code.
224 164
165=back
166
167=head2 SUPPORT FUNCTIONS
168
169=over 4
170
171=item $fileno = IO::AIO::poll_fileno
172
173Return the I<request result pipe filehandle>. This filehandle must be
174polled for reading by some mechanism outside this module (e.g. Event
175or select, see below). If the pipe becomes readable you have to call
176C<poll_cb> to check the results.
177
178See C<poll_cb> for an example.
179
180=item IO::AIO::poll_cb
181
182Process all outstanding events on the result pipe. You have to call this
183regularly. Returns the number of events processed. Returns immediately
184when no events are outstanding.
185
186You can use Event to multiplex, e.g.:
187
188 Event->io (fd => IO::AIO::poll_fileno,
189 poll => 'r', async => 1,
190 cb => \&IO::AIO::poll_cb);
191
192=item IO::AIO::poll_wait
193
194Wait till the result filehandle becomes ready for reading (simply does a
195select on the filehandle. This is useful if you want to synchronously wait
196for some requests to finish).
197
198See C<nreqs> for an example.
199
200=item IO::AIO::nreqs
201
202Returns the number of requests currently outstanding.
203
204Example: wait till there are no outstanding requests anymore:
205
206 IO::AIO::poll_wait, IO::AIO::poll_cb
207 while IO::AIO::nreqs;
208
209=item IO::AIO::min_parallel $nthreads
210
211Set the minimum number of AIO threads to C<$nthreads>. The default is
212C<1>, which means a single asynchronous operation can be done at one time
213(the number of outstanding operations, however, is unlimited).
214
215It is recommended to keep the number of threads low, as some Linux
216kernel versions will scale negatively with the number of threads (higher
217parallelity => MUCH higher latency). With current Linux 2.6 versions, 4-32
218threads should be fine.
219
220Under normal circumstances you don't need to call this function, as this
221module automatically starts some threads (the exact number might change,
222and is currently 4).
223
224=item IO::AIO::max_parallel $nthreads
225
226Sets the maximum number of AIO threads to C<$nthreads>. If more than
227the specified number of threads are currently running, kill them. This
228function blocks until the limit is reached.
229
230This module automatically runs C<max_parallel 0> at program end, to ensure
231that all threads are killed and that there are no outstanding requests.
232
233Under normal circumstances you don't need to call this function.
234
235=item $oldnreqs = IO::AIO::max_outstanding $nreqs
236
237Sets the maximum number of outstanding requests to C<$nreqs>. If you
238try to queue up more than this number of requests, the caller will block until
239some requests have been handled.
240
241The default is very large, so normally there is no practical limit. If you
242queue up many requests in a loop it it often improves speed if you set
243this to a relatively low number, such as C<100>.
244
245Under normal circumstances you don't need to call this function.
246
247=back
248
225=cut 249=cut
226 250
227# support function to convert a fd into a perl filehandle 251# support function to convert a fd into a perl filehandle
228sub _fd2fh { 252sub _fd2fh {
229 return undef if $_[0] < 0; 253 return undef if $_[0] < 0;
… …
242 max_parallel 0; 266 max_parallel 0;
243} 267}
244 268
2451; 2691;
246 270
247=back
248
249=head1 BUGS
250
251 - could be optimized to use more semaphores instead of filehandles.
252
253=head1 SEE ALSO 271=head1 SEE ALSO
254 272
255L<Coro>, L<Linux::AIO>. 273L<Coro>, L<Linux::AIO>.
256 274
257=head1 AUTHOR 275=head1 AUTHOR

Diff Legend

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