… | |
… | |
7 | use IO::AIO; |
7 | use IO::AIO; |
8 | |
8 | |
9 | =head1 DESCRIPTION |
9 | =head1 DESCRIPTION |
10 | |
10 | |
11 | This module implements asynchronous I/O using whatever means your |
11 | This module implements asynchronous I/O using whatever means your |
12 | operating system supports. Currently, it falls back to Linux::AIO if that |
12 | operating system supports. |
13 | module is available, or uses pthreads to emulato aio functionality. |
|
|
14 | |
13 | |
15 | Currently, in this module a number of threads are started that execute |
14 | Currently, a number of threads are started that execute your read/writes |
16 | your read/writes and signal their completion. You don't need thread |
15 | and signal their completion. You don't need thread support in your libc or |
17 | support in your libc or perl, and the threads created by this module will |
16 | perl, and the threads created by this module will not be visible to the |
18 | not be visible to the pthreads library. |
17 | pthreads library. In the future, this module might make use of the native |
|
|
18 | aio functions available on many operating systems. However, they are often |
|
|
19 | not well-supported (Linux doesn't allow them on normal files currently, |
|
|
20 | for example), and they would only support aio_read and aio_write, so the |
|
|
21 | remaining functionality would have to be implemented using threads anyway. |
19 | |
22 | |
20 | Although the module will work with in the presence of other threads, it is |
23 | Although the module will work with in the presence of other threads, it is |
21 | not reentrant, so use appropriate locking yourself. |
24 | currently not reentrant, so use appropriate locking yourself. |
22 | |
25 | |
23 | =head2 API NOTES |
26 | =head2 API NOTES |
24 | |
27 | |
25 | All the C<aio_*> calls are more or less thin wrappers around the syscall |
28 | All the C<aio_*> calls are more or less thin wrappers around the syscall |
26 | with the same name (sans C<aio_>). The arguments are similar or identical, |
29 | with the same name (sans C<aio_>). The arguments are similar or identical, |
… | |
… | |
43 | |
46 | |
44 | package IO::AIO; |
47 | package IO::AIO; |
45 | |
48 | |
46 | use base 'Exporter'; |
49 | use base 'Exporter'; |
47 | |
50 | |
|
|
51 | use Fcntl (); |
|
|
52 | |
48 | BEGIN { |
53 | BEGIN { |
49 | $VERSION = 0.1; |
54 | $VERSION = 0.2; |
50 | |
55 | |
51 | @EXPORT = qw(aio_read aio_write aio_open aio_close aio_stat aio_lstat aio_unlink |
56 | @EXPORT = qw(aio_read aio_write aio_open aio_close aio_stat aio_lstat aio_unlink |
52 | aio_fsync aio_fdatasync aio_readahead); |
57 | aio_fsync aio_fdatasync aio_readahead); |
53 | @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel nreqs); |
58 | @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel max_outstanding nreqs); |
54 | |
59 | |
55 | require XSLoader; |
60 | require XSLoader; |
56 | XSLoader::load IO::AIO, $VERSION; |
61 | XSLoader::load IO::AIO, $VERSION; |
57 | } |
62 | } |
58 | |
63 | |
… | |
… | |
60 | |
65 | |
61 | Set the minimum number of AIO threads to C<$nthreads>. The default is |
66 | Set the minimum number of AIO threads to C<$nthreads>. The default is |
62 | C<1>, which means a single asynchronous operation can be done at one time |
67 | C<1>, which means a single asynchronous operation can be done at one time |
63 | (the number of outstanding operations, however, is unlimited). |
68 | (the number of outstanding operations, however, is unlimited). |
64 | |
69 | |
65 | It is recommended to keep the number of threads low, as some linux |
70 | It is recommended to keep the number of threads low, as some Linux |
66 | kernel versions will scale negatively with the number of threads (higher |
71 | kernel versions will scale negatively with the number of threads (higher |
67 | parallelity => MUCH higher latency). |
72 | parallelity => MUCH higher latency). With current Linux 2.6 versions, 4-32 |
|
|
73 | threads should be fine. |
68 | |
74 | |
69 | Under normal circumstances you don't need to call this function, as this |
75 | Under normal circumstances you don't need to call this function, as this |
70 | module automatically starts a single async thread. |
76 | module automatically starts some threads (the exact number might change, |
|
|
77 | and is currently 4). |
71 | |
78 | |
72 | =item IO::AIO::max_parallel $nthreads |
79 | =item IO::AIO::max_parallel $nthreads |
73 | |
80 | |
74 | Sets the maximum number of AIO threads to C<$nthreads>. If more than |
81 | Sets the maximum number of AIO threads to C<$nthreads>. If more than |
75 | the specified number of threads are currently running, kill them. This |
82 | the specified number of threads are currently running, kill them. This |
76 | function blocks until the limit is reached. |
83 | function blocks until the limit is reached. |
77 | |
84 | |
78 | This module automatically runs C<max_parallel 0> at program end, to ensure |
85 | This module automatically runs C<max_parallel 0> at program end, to ensure |
79 | that all threads are killed and that there are no outstanding requests. |
86 | that all threads are killed and that there are no outstanding requests. |
|
|
87 | |
|
|
88 | Under normal circumstances you don't need to call this function. |
|
|
89 | |
|
|
90 | =item $oldnreqs = IO::AIO::max_outstanding $nreqs |
|
|
91 | |
|
|
92 | Sets the maximum number of outstanding requests to C<$nreqs>. If you |
|
|
93 | try to queue up more than this number of requests, the caller will block until |
|
|
94 | some requests have been handled. |
|
|
95 | |
|
|
96 | The default is very large, so normally there is no practical limit. If you |
|
|
97 | queue up many requests in a loop it it often improves speed if you set |
|
|
98 | this to a relatively low number, such as C<100>. |
80 | |
99 | |
81 | Under normal circumstances you don't need to call this function. |
100 | Under normal circumstances you don't need to call this function. |
82 | |
101 | |
83 | =item $fileno = IO::AIO::poll_fileno |
102 | =item $fileno = IO::AIO::poll_fileno |
84 | |
103 | |
… | |
… | |
118 | IO::AIO::poll_wait, IO::AIO::poll_cb |
137 | IO::AIO::poll_wait, IO::AIO::poll_cb |
119 | while IO::AIO::nreqs; |
138 | while IO::AIO::nreqs; |
120 | |
139 | |
121 | =item aio_open $pathname, $flags, $mode, $callback |
140 | =item aio_open $pathname, $flags, $mode, $callback |
122 | |
141 | |
123 | Asynchronously open or create a file and call the callback with the |
142 | Asynchronously open or create a file and call the callback with a newly |
124 | filedescriptor (NOT a perl filehandle, sorry for that, but watch out, this |
143 | created filehandle for the file. |
125 | might change in the future). |
|
|
126 | |
144 | |
127 | The pathname passed to C<aio_open> must be absolute. See API NOTES, above, |
145 | The pathname passed to C<aio_open> must be absolute. See API NOTES, above, |
128 | for an explanation. |
146 | for an explanation. |
129 | |
147 | |
130 | The C<$mode> argument is a bitmask. See the C<Fcntl> module for a |
148 | The C<$mode> argument is a bitmask. See the C<Fcntl> module for a |
131 | list. They are the same as used in C<sysopen>. |
149 | list. They are the same as used in C<sysopen>. |
132 | |
150 | |
133 | Example: |
151 | Example: |
134 | |
152 | |
135 | aio_open "/etc/passwd", O_RDONLY, 0, sub { |
153 | aio_open "/etc/passwd", O_RDONLY, 0, sub { |
136 | if ($_[0] >= 0) { |
154 | if ($_[0]) { |
137 | open my $fh, "<&$_[0]"; # create a copy for perl |
|
|
138 | aio_close $_[0], sub { }; # close the aio handle |
|
|
139 | print "open successful, fh is $fh\n"; |
155 | print "open successful, fh is $_[0]\n"; |
140 | ... |
156 | ... |
141 | } else { |
157 | } else { |
142 | die "open failed: $!\n"; |
158 | die "open failed: $!\n"; |
143 | } |
159 | } |
144 | }; |
160 | }; |
145 | |
161 | |
146 | =item aio_close $fh, $callback |
162 | =item aio_close $fh, $callback |
147 | |
163 | |
148 | Asynchronously close a file and call the callback with the result code. |
164 | Asynchronously close a file and call the callback with the result |
|
|
165 | code. I<WARNING:> although accepted, you should not pass in a perl |
|
|
166 | filehandle here, as perl will likely close the file descriptor itself when |
|
|
167 | the filehandle is destroyed. Normally, you can safely call perls C<close> |
|
|
168 | or just let filehandles go out of scope. |
149 | |
169 | |
150 | =item aio_read $fh,$offset,$length, $data,$dataoffset,$callback |
170 | =item aio_read $fh,$offset,$length, $data,$dataoffset,$callback |
151 | |
171 | |
152 | =item aio_write $fh,$offset,$length, $data,$dataoffset,$callback |
172 | =item aio_write $fh,$offset,$length, $data,$dataoffset,$callback |
153 | |
173 | |
… | |
… | |
216 | Asynchronously call fdatasync on the given filehandle and call the |
236 | Asynchronously call fdatasync on the given filehandle and call the |
217 | callback with the fdatasync result code. |
237 | callback with the fdatasync result code. |
218 | |
238 | |
219 | =cut |
239 | =cut |
220 | |
240 | |
|
|
241 | # support function to convert a fd into a perl filehandle |
|
|
242 | sub _fd2fh { |
|
|
243 | return undef if $_[0] < 0; |
|
|
244 | |
|
|
245 | # try to be perl5.6-compatible |
|
|
246 | local *AIO_FH; |
|
|
247 | open AIO_FH, "+<&=$_[0]" |
|
|
248 | or return undef; |
|
|
249 | |
|
|
250 | *AIO_FH |
|
|
251 | } |
|
|
252 | |
221 | min_parallel 4; |
253 | min_parallel 4; |
222 | |
254 | |
223 | END { |
255 | END { |
224 | max_parallel 0; |
256 | max_parallel 0; |
225 | } |
257 | } |
… | |
… | |
228 | |
260 | |
229 | =back |
261 | =back |
230 | |
262 | |
231 | =head1 BUGS |
263 | =head1 BUGS |
232 | |
264 | |
233 | - aio_open gives a fd, but all other functions expect a perl filehandle. |
265 | - could be optimized to use more semaphores instead of filehandles. |
234 | |
266 | |
235 | =head1 SEE ALSO |
267 | =head1 SEE ALSO |
236 | |
268 | |
237 | L<Coro>, L<Linux::AIO>. |
269 | L<Coro>, L<Linux::AIO>. |
238 | |
270 | |