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