… | |
… | |
171 | use common::sense; |
171 | use common::sense; |
172 | |
172 | |
173 | use base 'Exporter'; |
173 | use base 'Exporter'; |
174 | |
174 | |
175 | BEGIN { |
175 | BEGIN { |
176 | our $VERSION = 4.4; |
176 | our $VERSION = 4.41; |
177 | |
177 | |
178 | our @AIO_REQ = qw(aio_sendfile aio_seek aio_read aio_write aio_open aio_close |
178 | our @AIO_REQ = qw(aio_sendfile aio_seek aio_read aio_write aio_open aio_close |
179 | aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx |
179 | aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx |
180 | aio_scandir aio_symlink aio_readlink aio_realpath aio_fcntl aio_ioctl |
180 | aio_scandir aio_symlink aio_readlink aio_realpath aio_fcntl aio_ioctl |
181 | aio_sync aio_fsync aio_syncfs aio_fdatasync aio_sync_file_range |
181 | aio_sync aio_fsync aio_syncfs aio_fdatasync aio_sync_file_range |
… | |
… | |
192 | our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush |
192 | our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush |
193 | min_parallel max_parallel max_idle idle_timeout |
193 | min_parallel max_parallel max_idle idle_timeout |
194 | nreqs nready npending nthreads |
194 | nreqs nready npending nthreads |
195 | max_poll_time max_poll_reqs |
195 | max_poll_time max_poll_reqs |
196 | sendfile fadvise madvise |
196 | sendfile fadvise madvise |
197 | mmap munmap munlock munlockall); |
197 | mmap munmap mremap munlock munlockall); |
198 | |
198 | |
199 | push @AIO_REQ, qw(aio_busy); # not exported |
199 | push @AIO_REQ, qw(aio_busy); # not exported |
200 | |
200 | |
201 | @IO::AIO::GRP::ISA = 'IO::AIO::REQ'; |
201 | @IO::AIO::GRP::ISA = 'IO::AIO::REQ'; |
202 | |
202 | |
… | |
… | |
285 | |
285 | |
286 | IO::AIO::sendfile $ofh, $ifh, $offset, $count |
286 | IO::AIO::sendfile $ofh, $ifh, $offset, $count |
287 | IO::AIO::fadvise $fh, $offset, $len, $advice |
287 | IO::AIO::fadvise $fh, $offset, $len, $advice |
288 | IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]] |
288 | IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]] |
289 | IO::AIO::munmap $scalar |
289 | IO::AIO::munmap $scalar |
|
|
290 | IO::AIO::mremap $scalar, $new_length, $flags[, $new_address] |
290 | IO::AIO::madvise $scalar, $offset, $length, $advice |
291 | IO::AIO::madvise $scalar, $offset, $length, $advice |
291 | IO::AIO::mprotect $scalar, $offset, $length, $protect |
292 | IO::AIO::mprotect $scalar, $offset, $length, $protect |
292 | IO::AIO::munlock $scalar, $offset = 0, $length = undef |
293 | IO::AIO::munlock $scalar, $offset = 0, $length = undef |
293 | IO::AIO::munlockall |
294 | IO::AIO::munlockall |
294 | |
295 | |
… | |
… | |
789 | |
790 | |
790 | =over 4 |
791 | =over 4 |
791 | |
792 | |
792 | =item IO::AIO::READDIR_DENTS |
793 | =item IO::AIO::READDIR_DENTS |
793 | |
794 | |
794 | When this flag is off, then the callback gets an arrayref consisting of |
795 | Normally the callback gets an arrayref consisting of names only (as |
795 | names only (as with C<aio_readdir>), otherwise it gets an arrayref with |
796 | with C<aio_readdir>). If this flag is set, then the callback gets an |
796 | C<[$name, $type, $inode]> arrayrefs, each describing a single directory |
797 | arrayref with C<[$name, $type, $inode]> arrayrefs, each describing a |
797 | entry in more detail. |
798 | single directory entry in more detail: |
798 | |
799 | |
799 | C<$name> is the name of the entry. |
800 | C<$name> is the name of the entry. |
800 | |
801 | |
801 | C<$type> is one of the C<IO::AIO::DT_xxx> constants: |
802 | C<$type> is one of the C<IO::AIO::DT_xxx> constants: |
802 | |
803 | |
803 | C<IO::AIO::DT_UNKNOWN>, C<IO::AIO::DT_FIFO>, C<IO::AIO::DT_CHR>, C<IO::AIO::DT_DIR>, |
804 | C<IO::AIO::DT_UNKNOWN>, C<IO::AIO::DT_FIFO>, C<IO::AIO::DT_CHR>, C<IO::AIO::DT_DIR>, |
804 | C<IO::AIO::DT_BLK>, C<IO::AIO::DT_REG>, C<IO::AIO::DT_LNK>, C<IO::AIO::DT_SOCK>, |
805 | C<IO::AIO::DT_BLK>, C<IO::AIO::DT_REG>, C<IO::AIO::DT_LNK>, C<IO::AIO::DT_SOCK>, |
805 | C<IO::AIO::DT_WHT>. |
806 | C<IO::AIO::DT_WHT>. |
806 | |
807 | |
807 | C<IO::AIO::DT_UNKNOWN> means just that: readdir does not know. If you need to |
808 | C<IO::AIO::DT_UNKNOWN> means just that: readdir does not know. If you need |
808 | know, you have to run stat yourself. Also, for speed reasons, the C<$type> |
809 | to know, you have to run stat yourself. Also, for speed/memory reasons, |
809 | scalars are read-only: you can not modify them. |
810 | the C<$type> scalars are read-only: you must not modify them. |
810 | |
811 | |
811 | C<$inode> is the inode number (which might not be exact on systems with 64 |
812 | C<$inode> is the inode number (which might not be exact on systems with 64 |
812 | bit inode numbers and 32 bit perls). This field has unspecified content on |
813 | bit inode numbers and 32 bit perls). This field has unspecified content on |
813 | systems that do not deliver the inode information. |
814 | systems that do not deliver the inode information. |
814 | |
815 | |
… | |
… | |
825 | short names are tried first. |
826 | short names are tried first. |
826 | |
827 | |
827 | =item IO::AIO::READDIR_STAT_ORDER |
828 | =item IO::AIO::READDIR_STAT_ORDER |
828 | |
829 | |
829 | When this flag is set, then the names will be returned in an order |
830 | When this flag is set, then the names will be returned in an order |
830 | suitable for stat()'ing each one. That is, when you plan to stat() |
831 | suitable for stat()'ing each one. That is, when you plan to stat() most or |
831 | all files in the given directory, then the returned order will likely |
832 | all files in the given directory, then the returned order will likely be |
832 | be fastest. |
833 | faster. |
833 | |
834 | |
834 | If both this flag and C<IO::AIO::READDIR_DIRS_FIRST> are specified, then |
835 | If both this flag and C<IO::AIO::READDIR_DIRS_FIRST> are specified, |
835 | the likely dirs come first, resulting in a less optimal stat order. |
836 | then the likely dirs come first, resulting in a less optimal stat order |
|
|
837 | for stat'ing all entries, but likely a more optimal order for finding |
|
|
838 | subdirectories. |
836 | |
839 | |
837 | =item IO::AIO::READDIR_FOUND_UNKNOWN |
840 | =item IO::AIO::READDIR_FOUND_UNKNOWN |
838 | |
841 | |
839 | This flag should not be set when calling C<aio_readdirx>. Instead, it |
842 | This flag should not be set when calling C<aio_readdirx>. Instead, it |
840 | is being set by C<aio_readdirx>, when any of the C<$type>'s found were |
843 | is being set by C<aio_readdirx>, when any of the C<$type>'s found were |
… | |
… | |
2156 | |
2159 | |
2157 | =item IO::AIO::munmap $scalar |
2160 | =item IO::AIO::munmap $scalar |
2158 | |
2161 | |
2159 | Removes a previous mmap and undefines the C<$scalar>. |
2162 | Removes a previous mmap and undefines the C<$scalar>. |
2160 | |
2163 | |
|
|
2164 | =item IO::AIO::mremap $scalar, $new_length, $flags = 0[, $new_address = 0] |
|
|
2165 | |
|
|
2166 | Calls the Linux-specific mremap(2) system call. The C<$scalar> must have |
|
|
2167 | been mapped by C<IO::AIO::mmap>, and C<$flags> must currently either be |
|
|
2168 | C<0> or C<IO::AIO::MREMAP_MAYMOVE>. |
|
|
2169 | |
|
|
2170 | Returns true if successful, and false otherwise. If the underlying mmapped |
|
|
2171 | region has changed address, then the true value has the numerical value |
|
|
2172 | C<1>, otherwise it has the numerical value C<0>: |
|
|
2173 | |
|
|
2174 | my $success = IO::AIO::mremap $mmapped, 8192, IO::AIO::MREMAP_MAYMOVE |
|
|
2175 | or die "mremap: $!"; |
|
|
2176 | |
|
|
2177 | if ($success*1) { |
|
|
2178 | warn "scalar has chanegd address in memory\n"; |
|
|
2179 | } |
|
|
2180 | |
|
|
2181 | C<IO::AIO::MREMAP_FIXED> and the C<$new_address> argument are currently |
|
|
2182 | implemented, but not supported and might go away in a future version. |
|
|
2183 | |
|
|
2184 | On systems where this call is not supported or is not emulated, this call |
|
|
2185 | returns falls and sets C<$!> to C<ENOSYS>. |
|
|
2186 | |
2161 | =item IO::AIO::munlock $scalar, $offset = 0, $length = undef |
2187 | =item IO::AIO::munlock $scalar, $offset = 0, $length = undef |
2162 | |
2188 | |
2163 | Calls the C<munlock> function, undoing the effects of a previous |
2189 | Calls the C<munlock> function, undoing the effects of a previous |
2164 | C<aio_mlock> call (see its description for details). |
2190 | C<aio_mlock> call (see its description for details). |
2165 | |
2191 | |
… | |
… | |
2220 | Example: create a pipe race-free w.r.t. threads and fork: |
2246 | Example: create a pipe race-free w.r.t. threads and fork: |
2221 | |
2247 | |
2222 | my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC |
2248 | my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC |
2223 | or die "pipe2: $!\n"; |
2249 | or die "pipe2: $!\n"; |
2224 | |
2250 | |
2225 | =item $fh = IO::AIO::eventfd ([$initval, [$flags]]) |
2251 | =item $fh = IO::AIO::eventfd [$initval, [$flags]] |
2226 | |
2252 | |
2227 | This is a direct interface to the Linux L<eventfd(2)> system call. The |
2253 | This is a direct interface to the Linux L<eventfd(2)> system call. The |
2228 | (unhelpful) defaults for C<$initval> and C<$flags> are C<0> for both. |
2254 | (unhelpful) defaults for C<$initval> and C<$flags> are C<0> for both. |
2229 | |
2255 | |
2230 | On success, the new eventfd filehandle is returned, otherwise returns |
2256 | On success, the new eventfd filehandle is returned, otherwise returns |
… | |
… | |
2232 | |
2258 | |
2233 | Please refer to L<eventfd(2)> for more info on this call. |
2259 | Please refer to L<eventfd(2)> for more info on this call. |
2234 | |
2260 | |
2235 | The following symbol flag values are available: C<IO::AIO::EFD_CLOEXEC>, |
2261 | The following symbol flag values are available: C<IO::AIO::EFD_CLOEXEC>, |
2236 | C<IO::AIO::EFD_NONBLOCK> and C<IO::AIO::EFD_SEMAPHORE> (Linux 2.6.30). |
2262 | C<IO::AIO::EFD_NONBLOCK> and C<IO::AIO::EFD_SEMAPHORE> (Linux 2.6.30). |
|
|
2263 | |
|
|
2264 | Example: create a new eventfd filehandle: |
|
|
2265 | |
|
|
2266 | $fh = IO::AIO::eventfd 0, IO::AIO::O_CLOEXEC |
|
|
2267 | or die "eventfd: $!\n"; |
|
|
2268 | |
|
|
2269 | =item $fh = IO::AIO::timerfd_create $clockid[, $flags] |
|
|
2270 | |
|
|
2271 | This is a direct interface to the Linux L<timerfd_create(2)> system call. The |
|
|
2272 | (unhelpful) default for C<$flags> is C<0>. |
|
|
2273 | |
|
|
2274 | On success, the new timerfd filehandle is returned, otherwise returns |
|
|
2275 | C<undef>. If the eventfd syscall is missing, fails with C<ENOSYS>. |
|
|
2276 | |
|
|
2277 | Please refer to L<timerfd_create(2)> for more info on this call. |
|
|
2278 | |
|
|
2279 | The following C<$clockid> values are |
|
|
2280 | available: C<IO::AIO::CLOCK_REALTIME>, C<IO::AIO::CLOCK_MONOTONIC> |
|
|
2281 | C<IO::AIO::CLOCK_CLOCK_BOOTTIME> (Linux 3.15) |
|
|
2282 | C<IO::AIO::CLOCK_CLOCK_REALTIME_ALARM> (Linux 3.11) and |
|
|
2283 | C<IO::AIO::CLOCK_CLOCK_BOOTTIME_ALARM> (Linux 3.11). |
|
|
2284 | |
|
|
2285 | The following C<$flags> values are available (Linux |
|
|
2286 | 2.6.27): C<IO::AIO::TFD_NONBLOCK> and C<IO::AIO::TFD_CLOEXEC>. |
|
|
2287 | |
|
|
2288 | Example: create a new timerfd and set it to one-second repeated alarms, |
|
|
2289 | then wait for two alarms: |
|
|
2290 | |
|
|
2291 | my $fh = IO::AIO::timerfd_create IO::AIO::CLOCK_BOOTTIME, IO::AIO::TFD_CLOEXEC |
|
|
2292 | or die "timerfd_create: $!\n"; |
|
|
2293 | |
|
|
2294 | defined IO::AIO::timerfd_settime $fh, 0, 1, 1 |
|
|
2295 | or die "timerfd_settime: $!\n"; |
|
|
2296 | |
|
|
2297 | for (1..2) { |
|
|
2298 | 8 == sysread $fh, my $buf, 8 |
|
|
2299 | or die "timerfd read failure\n"; |
|
|
2300 | |
|
|
2301 | printf "number of expirations (likely 1): %d\n", |
|
|
2302 | unpack "Q", $buf; |
|
|
2303 | } |
|
|
2304 | |
|
|
2305 | =item ($cur_interval, $cur_value) = IO::AIO::timerfd_settime $fh, $flags, $new_interval, $nbw_value |
|
|
2306 | |
|
|
2307 | This is a direct interface to the Linux L<timerfd_settime(2)> system |
|
|
2308 | call. Please refer to its manpage for more info on this call. |
|
|
2309 | |
|
|
2310 | The new itimerspec is specified using two (possibly fractional) second |
|
|
2311 | values, C<$new_interval> and C<$new_value>). |
|
|
2312 | |
|
|
2313 | On success, the current interval and value are returned (as per |
|
|
2314 | C<timerfd_gettime>). On failure, the empty list is returned. |
|
|
2315 | |
|
|
2316 | The following C<$flags> values are |
|
|
2317 | available: C<IO::AIO::TFD_TIMER_ABSTIME> and |
|
|
2318 | C<IO::AIO::TFD_TIMER_CANCEL_ON_SET>. |
|
|
2319 | |
|
|
2320 | See C<IO::AIO::timerfd_create> for a full example. |
|
|
2321 | |
|
|
2322 | =item ($cur_interval, $cur_value) = IO::AIO::timerfd_gettime $fh |
|
|
2323 | |
|
|
2324 | This is a direct interface to the Linux L<timerfd_gettime(2)> system |
|
|
2325 | call. Please refer to its manpage for more info on this call. |
|
|
2326 | |
|
|
2327 | On success, returns the current values of interval and value for the given |
|
|
2328 | timerfd (as potentially fractional second values). On failure, the empty |
|
|
2329 | list is returned. |
2237 | |
2330 | |
2238 | =back |
2331 | =back |
2239 | |
2332 | |
2240 | =cut |
2333 | =cut |
2241 | |
2334 | |
… | |
… | |
2307 | the process will result in undefined behaviour. Calling it at any time |
2400 | the process will result in undefined behaviour. Calling it at any time |
2308 | will also result in any undefined (by POSIX) behaviour. |
2401 | will also result in any undefined (by POSIX) behaviour. |
2309 | |
2402 | |
2310 | =back |
2403 | =back |
2311 | |
2404 | |
|
|
2405 | =head2 LINUX-SPECIFIC CALLS |
|
|
2406 | |
|
|
2407 | When a call is documented as "linux-specific" then this means it |
|
|
2408 | originated on GNU/Linux. C<IO::AIO> will usually try to autodetect the |
|
|
2409 | availability and compatibility of such calls regardless of the platform |
|
|
2410 | it is compiled on, so platforms such as FreeBSD which often implement |
|
|
2411 | these calls will work. When in doubt, call them and see if they fail wth |
|
|
2412 | C<ENOSYS>. |
|
|
2413 | |
2312 | =head2 MEMORY USAGE |
2414 | =head2 MEMORY USAGE |
2313 | |
2415 | |
2314 | Per-request usage: |
2416 | Per-request usage: |
2315 | |
2417 | |
2316 | Each aio request uses - depending on your architecture - around 100-200 |
2418 | Each aio request uses - depending on your architecture - around 100-200 |
… | |
… | |
2328 | temporary buffers, and each thread requires a stack and other data |
2430 | temporary buffers, and each thread requires a stack and other data |
2329 | structures (usually around 16k-128k, depending on the OS). |
2431 | structures (usually around 16k-128k, depending on the OS). |
2330 | |
2432 | |
2331 | =head1 KNOWN BUGS |
2433 | =head1 KNOWN BUGS |
2332 | |
2434 | |
2333 | Known bugs will be fixed in the next release. |
2435 | Known bugs will be fixed in the next release :) |
|
|
2436 | |
|
|
2437 | =head1 KNOWN ISSUES |
|
|
2438 | |
|
|
2439 | Calls that try to "import" foreign memory areas (such as C<IO::AIO::mmap> |
|
|
2440 | or C<IO::AIO::aio_slurp>) do not work with generic lvalues, such as |
|
|
2441 | non-created hash slots or other scalars I didn't think of. It's best to |
|
|
2442 | avoid such and either use scalar variables or making sure that the scalar |
|
|
2443 | exists (e.g. by storing C<undef>) and isn't "funny" (e.g. tied). |
|
|
2444 | |
|
|
2445 | I am not sure anything can be done about this, so this is considered a |
|
|
2446 | known issue, rather than a bug. |
2334 | |
2447 | |
2335 | =head1 SEE ALSO |
2448 | =head1 SEE ALSO |
2336 | |
2449 | |
2337 | L<AnyEvent::AIO> for easy integration into event loops, L<Coro::AIO> for a |
2450 | L<AnyEvent::AIO> for easy integration into event loops, L<Coro::AIO> for a |
2338 | more natural syntax. |
2451 | more natural syntax. |