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

Comparing Linux-AIO/AIO.pm (file contents):
Revision 1.3 by root, Tue Aug 14 23:25:39 2001 UTC vs.
Revision 1.16 by root, Thu May 6 15:05:57 2004 UTC

… …
6 6
7 use Linux::AIO; 7 use Linux::AIO;
8 8
9=head1 DESCRIPTION 9=head1 DESCRIPTION
10 10
11This module implements asynchroneous i/o using the means available to 11This module implements asynchronous i/o using the means available to linux
12linux - clone. It does not hook into the POSIX aio_* functions because 12- clone. It does not hook into the POSIX aio_* functions because linux
13linux does not yet support these in the kernel. Instead, a number of 13does not yet support these in the kernel (and even if, it would only allow
14threads are started that execute your read/writes and signal their 14aio_read and write, not open and stat).
15completion. 15
16Instead, in this module a number of (non-posix) threads are started that
17execute your read/writes and signal their completion. You don't need
18thread support in your libc or perl, and the threads created by this
19module will not be visible to the pthreads library.
20
21Although the module will work with threads, it is not reentrant, so use
22appropriate locking yourself.
16 23
17=over 4 24=over 4
18 25
19=cut 26=cut
20 27
21package Linux::AIO; 28package Linux::AIO;
22 29
23use base 'Exporter'; 30use base 'Exporter';
24 31
25BEGIN { 32BEGIN {
26 $VERSION = 0.001; 33 $VERSION = 1.1;
27 34
28 @EXPORT = qw(aio_read aio_write); 35 @EXPORT = qw(aio_read aio_write aio_open aio_close aio_stat aio_lstat);
29 @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel nreqs); 36 @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel nreqs);
30 37
31 require XSLoader; 38 require XSLoader;
32 XSLoader::load Linux::AIO, $VERSION; 39 XSLoader::load Linux::AIO, $VERSION;
33} 40}
34 41
35=item Linux::AIO::min_parallel($nthreads) 42=item Linux::AIO::min_parallel $nthreads
36 43
37Set the minimum number of AIO threads to $nthreads. You I<have> to call 44Set the minimum number of AIO threads to C<$nthreads>. The default is
38this function with a positive number at leats once, otherwise no threads 45C<1>, which means a single asynchronous operation can be done at one time
39will be started and you aio-operations will seem to hang. 46(the number of outstanding operations, however, is unlimited).
40 47
41=cut 48It is recommended to keep the number of threads low, as many linux
42 49kernel versions will scale negatively with the number of threads (higher
43=item aio_read($fh,$offset,$length, $data,$dataoffset,$callback) 50parallelity => MUCH higher latency).
44aio_write($fh,$offset,$length, $data,$dataoffset,$callback)
45
46Reads or writes C<length> bytes from the specified C<fh> and C<offset>
47into the scalar given by C<data> and offset C<dataoffset> and calls the
48callback without the actual number of bytes read (or undef on error).
49 51
50=item $fileno = Linux::AIO::poll_fileno 52=item $fileno = Linux::AIO::poll_fileno
51 53
52Return the request result pipe filehandle. This filehandle must be polled 54Return the I<request result pipe filehandle>. This filehandle must be
53for reading. If the pipe becomes readable you have to call C<poll_cb>. 55polled for reading by some mechanism outside this module (e.g. Event
56or select, see below). If the pipe becomes readable you have to call
57C<poll_cb> to check the results.
54 58
55=item Linux::AIO::poll_cb 59=item Linux::AIO::poll_cb
56 60
57Process all outstanding events on the result pipe. You have to call this 61Process all outstanding events on the result pipe. You have to call this
58regularly. Returns the number of events processed. 62regularly. Returns the number of events processed. Returns immediately
63when no events are outstanding.
59 64
60You can use Event to multiplex, e.g.: 65You can use Event to multiplex, e.g.:
61 66
62 Event->io(fd => Linux::AIO::poll_fileno, 67 Event->io (fd => Linux::AIO::poll_fileno,
63 poll => 'r', async => 1, 68 poll => 'r', async => 1,
64 cb => \&Linux::AIO::poll_cb ); 69 cb => \&Linux::AIO::poll_cb );
65 70
66 71
67=item Linux::AIO::nreqs 72=item Linux::AIO::nreqs
68 73
69Returns the number of requests currently outstanding. 74Returns the number of requests currently outstanding.
70 75
76=item aio_open $pathname, $flags, $mode, $callback
77
78Asynchronously open or create a file and call the callback with the
79filedescriptor (NOT a perl filehandle, sorry for that, but watch out, this
80might change in the future).
81
82=item aio_close $fh, $callback
83
84Asynchronously close a file and call the callback with the result code.
85
86=item aio_read $fh,$offset,$length, $data,$dataoffset,$callback
87
88=item aio_write $fh,$offset,$length, $data,$dataoffset,$callback
89
90Reads or writes C<length> bytes from the specified C<fh> and C<offset>
91into the scalar given by C<data> and offset C<dataoffset> and calls the
92callback without the actual number of bytes read (or C<undef> on error).
93
94=item aio_stat $fh_or_path, $callback
95
96=item aio_lstat $fh, $callback
97
98Works like perl's C<stat> or C<lstat> in void context. The callback will
99be called after the stat and the results will be available using C<stat _>
100or C<-s _> etc...
101
102Currently, the stats are always 64-bit-stats, i.e. instead of returning an
103error when stat'ing a large file, the results will be silently truncated
104unless perl itself is compiled with large file support.
105
71=cut 106=cut
107
108min_parallel 1;
72 109
73END { 110END {
74 max_parallel 0; 111 max_parallel 0;
75} 112}
76 113
… …
78 115
79=back 116=back
80 117
81=head1 BUGS 118=head1 BUGS
82 119
83This module has not yet been extensively tested. Watch out! 120This module has been extensively tested in a large and very busy webserver
121for many years now.
122
123 - aio_open gives a fd, but all other functions expect a perl filehandle.
84 124
85=head1 SEE ALSO 125=head1 SEE ALSO
86 126
87L<Coro>. 127L<Coro>.
88 128

Diff Legend

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