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.86 by root, Sat Oct 28 23:32:29 2006 UTC vs.
Revision 1.89 by root, Sun Oct 29 11:03:18 2006 UTC

… …
176Request has reached the end of its lifetime and holds no resources anymore 176Request has reached the end of its lifetime and holds no resources anymore
177(except possibly for the Perl object, but its connection to the actual 177(except possibly for the Perl object, but its connection to the actual
178aio request is severed and calling its methods will either do nothing or 178aio request is severed and calling its methods will either do nothing or
179result in a runtime error). 179result in a runtime error).
180 180
181=back
182
181=cut 183=cut
182 184
183package IO::AIO; 185package IO::AIO;
184 186
185no warnings; 187no warnings;
… …
206 XSLoader::load ("IO::AIO", $VERSION); 208 XSLoader::load ("IO::AIO", $VERSION);
207} 209}
208 210
209=head1 FUNCTIONS 211=head1 FUNCTIONS
210 212
211=head2 AIO FUNCTIONS 213=head2 AIO REQUEST FUNCTIONS
212 214
213All the C<aio_*> calls are more or less thin wrappers around the syscall 215All the C<aio_*> calls are more or less thin wrappers around the syscall
214with the same name (sans C<aio_>). The arguments are similar or identical, 216with the same name (sans C<aio_>). The arguments are similar or identical,
215and they all accept an additional (and optional) C<$callback> argument 217and they all accept an additional (and optional) C<$callback> argument
216which must be a code reference. This code reference will get called with 218which must be a code reference. This code reference will get called with
… …
219syscall has been executed asynchronously. 221syscall has been executed asynchronously.
220 222
221All functions expecting a filehandle keep a copy of the filehandle 223All functions expecting a filehandle keep a copy of the filehandle
222internally until the request has finished. 224internally until the request has finished.
223 225
224All requests return objects of type L<IO::AIO::REQ> that allow further 226All functions return request objects of type L<IO::AIO::REQ> that allow
225manipulation of those requests while they are in-flight. 227further manipulation of those requests while they are in-flight.
226 228
227The pathnames you pass to these routines I<must> be absolute and 229The pathnames you pass to these routines I<must> be absolute and
228encoded in byte form. The reason for the former is that at the time the 230encoded as octets. The reason for the former is that at the time the
229request is being executed, the current working directory could have 231request is being executed, the current working directory could have
230changed. Alternatively, you can make sure that you never change the 232changed. Alternatively, you can make sure that you never change the
231current working directory. 233current working directory anywhere in the program and then use relative
234paths.
232 235
233To encode pathnames to byte form, either make sure you either: a) 236To encode pathnames as octets, either make sure you either: a) always pass
234always pass in filenames you got from outside (command line, readdir 237in filenames you got from outside (command line, readdir etc.) without
235etc.), b) are ASCII or ISO 8859-1, c) use the Encode module and encode 238tinkering, b) are ASCII or ISO 8859-1, c) use the Encode module and encode
236your pathnames to the locale (or other) encoding in effect in the user 239your pathnames to the locale (or other) encoding in effect in the user
237environment, d) use Glib::filename_from_unicode on unicode filenames or e) 240environment, d) use Glib::filename_from_unicode on unicode filenames or e)
238use something else. 241use something else to ensure your scalar has the correct contents.
242
243This works, btw. independent of the internal UTF-8 bit, which IO::AIO
244handles correctly wether it is set or not.
239 245
240=over 4 246=over 4
241 247
242=item $prev_pri = aioreq_pri [$pri] 248=item $prev_pri = aioreq_pri [$pri]
243 249
… …
266 }; 272 };
267 273
268=item aioreq_nice $pri_adjust 274=item aioreq_nice $pri_adjust
269 275
270Similar to C<aioreq_pri>, but subtracts the given value from the current 276Similar to C<aioreq_pri>, but subtracts the given value from the current
271priority, so effects are cumulative. 277priority, so the effect is cumulative.
272 278
273=item aio_open $pathname, $flags, $mode, $callback->($fh) 279=item aio_open $pathname, $flags, $mode, $callback->($fh)
274 280
275Asynchronously open or create a file and call the callback with a newly 281Asynchronously open or create a file and call the callback with a newly
276created filehandle for the file. 282created filehandle for the file.
… …
933that are being processed by C<IO::AIO::poll_cb> in one call, respectively 939that are being processed by C<IO::AIO::poll_cb> in one call, respectively
934the maximum amount of time (default C<0>, meaning infinity) spent in 940the maximum amount of time (default C<0>, meaning infinity) spent in
935C<IO::AIO::poll_cb> to process requests (more correctly the mininum amount 941C<IO::AIO::poll_cb> to process requests (more correctly the mininum amount
936of time C<poll_cb> is allowed to use). 942of time C<poll_cb> is allowed to use).
937 943
944Setting C<max_poll_time> to a non-zero value creates an overhead of one
945syscall per request processed, which is not normally a problem unless your
946callbacks are really really fast or your OS is really really slow (I am
947not mentioning Solaris here). Using C<max_poll_reqs> incurs no overhead.
948
938Setting these is useful if you want to ensure some level of 949Setting these is useful if you want to ensure some level of
939interactiveness when perl is not fast enough to process all requests in 950interactiveness when perl is not fast enough to process all requests in
940time. 951time.
941 952
942For interactive programs, values such as C<0.01> to C<0.1> should be fine. 953For interactive programs, values such as C<0.01> to C<0.1> should be fine.
943 954
944Example: Install an Event watcher that automatically calls 955Example: Install an Event watcher that automatically calls
945IO::AIO::poll_some with low priority, to ensure that other parts of the 956IO::AIO::poll_cb with low priority, to ensure that other parts of the
946program get the CPU sometimes even under high AIO load. 957program get the CPU sometimes even under high AIO load.
947 958
948 # try not to spend much more than 0.1s in poll_cb 959 # try not to spend much more than 0.1s in poll_cb
949 IO::AIO::max_poll_time 0.1; 960 IO::AIO::max_poll_time 0.1;
950 961

Diff Legend

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