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.311 by root, Sun Feb 7 13:13:44 2021 UTC vs.
Revision 1.317 by root, Sun Sep 25 16:30:50 2022 UTC

… …
171use common::sense; 171use common::sense;
172 172
173use base 'Exporter'; 173use base 'Exporter';
174 174
175BEGIN { 175BEGIN {
176 our $VERSION = 4.75; 176 our $VERSION = 4.79;
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 mremap munlock munlockall); 197 mmap munmap mremap munlock munlockall
198
199 accept4 tee splice pipe2 pipesize
200 fexecve mount umount memfd_create eventfd
201 timerfd_create timerfd_settime timerfd_gettime
202 pidfd_open pidfd_send_signal pidfd_getfd);
198 203
199 push @AIO_REQ, qw(aio_busy); # not exported 204 push @AIO_REQ, qw(aio_busy); # not exported
200 205
201 @IO::AIO::GRP::ISA = 'IO::AIO::REQ'; 206 @IO::AIO::GRP::ISA = 'IO::AIO::REQ';
202 207
… …
285 $nfd = IO::AIO::get_fdlimit 290 $nfd = IO::AIO::get_fdlimit
286 IO::AIO::min_fdlimit $nfd 291 IO::AIO::min_fdlimit $nfd
287 292
288 IO::AIO::sendfile $ofh, $ifh, $offset, $count 293 IO::AIO::sendfile $ofh, $ifh, $offset, $count
289 IO::AIO::fadvise $fh, $offset, $len, $advice 294 IO::AIO::fadvise $fh, $offset, $len, $advice
295 IO::AIO::fexecve $fh, $argv, $envp
290 296
291 IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]] 297 IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]]
292 IO::AIO::munmap $scalar 298 IO::AIO::munmap $scalar
293 IO::AIO::mremap $scalar, $new_length, $flags[, $new_address] 299 IO::AIO::mremap $scalar, $new_length, $flags[, $new_address]
294 IO::AIO::madvise $scalar, $offset, $length, $advice 300 IO::AIO::madvise $scalar, $offset, $length, $advice
… …
306 312
307 # very much unportable syscalls 313 # very much unportable syscalls
308 IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_len, $flags 314 IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_len, $flags
309 IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags 315 IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
310 IO::AIO::tee $r_fh, $w_fh, $length, $flags 316 IO::AIO::tee $r_fh, $w_fh, $length, $flags
317
311 $actual_size = IO::AIO::pipesize $r_fh[, $new_size] 318 $actual_size = IO::AIO::pipesize $r_fh[, $new_size]
312 ($rfh, $wfh) = IO::AIO::pipe2 [$flags] 319 ($rfh, $wfh) = IO::AIO::pipe2 [$flags]
320
321 $fh = IO::AIO::eventfd [$initval, [$flags]]
313 $fh = IO::AIO::memfd_create $pathname[, $flags] 322 $fh = IO::AIO::memfd_create $pathname[, $flags]
314 $fh = IO::AIO::eventfd [$initval, [$flags]] 323
315 $fh = IO::AIO::timerfd_create $clockid[, $flags] 324 $fh = IO::AIO::timerfd_create $clockid[, $flags]
316 ($cur_interval, $cur_value) = IO::AIO::timerfd_settime $fh, $flags, $new_interval, $nbw_value 325 ($cur_interval, $cur_value) = IO::AIO::timerfd_settime $fh, $flags, $new_interval, $nbw_value
317 ($cur_interval, $cur_value) = IO::AIO::timerfd_gettime $fh 326 ($cur_interval, $cur_value) = IO::AIO::timerfd_gettime $fh
327
328 $fh = IO::AIO::pidfd_open $pid[, $flags]
329 $status = IO::AIO::pidfd_send_signal $pidfh, $signal[, $siginfo[, $flags]]
330 $fh = IO::AIO::pidfd_getfd $pidfh, $targetfd[, $flags]
331
332 $retval = IO::AIO::mount $special, $path, $fstype, $flags = 0, $data = undef
333 $retval = IO::AIO::umount $path, $flags = 0
318 334
319=head2 API NOTES 335=head2 API NOTES
320 336
321All the C<aio_*> calls are more or less thin wrappers around the syscall 337All the C<aio_*> calls are more or less thin wrappers around the syscall
322with the same name (sans C<aio_>). The arguments are similar or identical, 338with the same name (sans C<aio_>). The arguments are similar or identical,
… …
1338C<FS_XFLAG_REALTIME>, C<FS_XFLAG_PREALLOC>, C<FS_XFLAG_IMMUTABLE>, C<FS_XFLAG_APPEND>, 1354C<FS_XFLAG_REALTIME>, C<FS_XFLAG_PREALLOC>, C<FS_XFLAG_IMMUTABLE>, C<FS_XFLAG_APPEND>,
1339C<FS_XFLAG_SYNC>, C<FS_XFLAG_NOATIME>, C<FS_XFLAG_NODUMP>, C<FS_XFLAG_RTINHERIT>, 1355C<FS_XFLAG_SYNC>, C<FS_XFLAG_NOATIME>, C<FS_XFLAG_NODUMP>, C<FS_XFLAG_RTINHERIT>,
1340C<FS_XFLAG_PROJINHERIT>, C<FS_XFLAG_NOSYMLINKS>, C<FS_XFLAG_EXTSIZE>, C<FS_XFLAG_EXTSZINHERIT>, 1356C<FS_XFLAG_PROJINHERIT>, C<FS_XFLAG_NOSYMLINKS>, C<FS_XFLAG_EXTSIZE>, C<FS_XFLAG_EXTSZINHERIT>,
1341C<FS_XFLAG_NODEFRAG>, C<FS_XFLAG_FILESTREAM>, C<FS_XFLAG_DAX>, C<FS_XFLAG_HASATTR>, 1357C<FS_XFLAG_NODEFRAG>, C<FS_XFLAG_FILESTREAM>, C<FS_XFLAG_DAX>, C<FS_XFLAG_HASATTR>,
1342 1358
1359C<BLKROSET>, C<BLKROGET>, C<BLKRRPART>, C<BLKGETSIZE>, C<BLKFLSBUF>, C<BLKRASET>,
1360C<BLKRAGET>, C<BLKFRASET>, C<BLKFRAGET>, C<BLKSECTSET>, C<BLKSECTGET>, C<BLKSSZGET>,
1361C<BLKBSZGET>, C<BLKBSZSET>, C<BLKGETSIZE64>,
1362
1363
1343=item aio_sync $callback->($status) 1364=item aio_sync $callback->($status)
1344 1365
1345Asynchronously call sync and call the callback when finished. 1366Asynchronously call sync and call the callback when finished.
1346 1367
1347=item aio_fsync $fh, $callback->($status) 1368=item aio_fsync $fh, $callback->($status)
… …
2061longer exceeded. 2082longer exceeded.
2062 2083
2063In other words, this setting does not enforce a queue limit, but can be 2084In other words, this setting does not enforce a queue limit, but can be
2064used to make poll functions block if the limit is exceeded. 2085used to make poll functions block if the limit is exceeded.
2065 2086
2066This is a very bad function to use in interactive programs because it 2087This is a bad function to use in interactive programs because it blocks,
2067blocks, and a bad way to reduce concurrency because it is inexact: Better 2088and a bad way to reduce concurrency because it is inexact. If you need to
2089issue many requests without being able to call a poll function on demand,
2068use an C<aio_group> together with a feed callback. 2090it is better to use an C<aio_group> together with a feed callback.
2069 2091
2070Its main use is in scripts without an event loop - when you want to stat 2092Its main use is in scripts without an event loop - when you want to stat a
2071a lot of files, you can write something like this: 2093lot of files, you can write something like this:
2072 2094
2073 IO::AIO::max_outstanding 32; 2095 IO::AIO::max_outstanding 32;
2074 2096
2075 for my $path (...) { 2097 for my $path (...) {
2076 aio_stat $path , ...; 2098 aio_stat $path , ...;
2077 IO::AIO::poll_cb; 2099 IO::AIO::poll_cb;
2078 } 2100 }
2079 2101
2080 IO::AIO::flush; 2102 IO::AIO::flush;
2081 2103
2082The call to C<poll_cb> inside the loop will normally return instantly, but 2104The call to C<poll_cb> inside the loop will normally return instantly,
2083as soon as more thna C<32> reqeusts are in-flight, it will block until 2105allowing the loop to progress, but as soon as more than C<32> requests
2084some requests have been handled. This keeps the loop from pushing a large 2106are in-flight, it will block until some requests have been handled. This
2085number of C<aio_stat> requests onto the queue. 2107keeps the loop from pushing a large number of C<aio_stat> requests onto
2108the queue (which, with many paths to stat, can use up a lot of memory).
2086 2109
2087The default value for C<max_outstanding> is very large, so there is no 2110The default value for C<max_outstanding> is very large, so there is no
2088practical limit on the number of outstanding requests. 2111practical limit on the number of outstanding requests.
2089 2112
2090=back 2113=back
… …
2217some "Advanced I/O" function not available to in Perl, without going the 2240some "Advanced I/O" function not available to in Perl, without going the
2218"Asynchronous I/O" route. Many of these have an asynchronous C<aio_*> 2241"Asynchronous I/O" route. Many of these have an asynchronous C<aio_*>
2219counterpart. 2242counterpart.
2220 2243
2221=over 4 2244=over 4
2245
2246=item $retval = IO::AIO::fexecve $fh, $argv, $envp
2247
2248A more-or-less direct equivalent to the POSIX C<fexecve> functions, which
2249allows you to specify the program to be executed via a file descriptor (or
2250handle). Returns C<-1> and sets errno to C<ENOSYS> if not available.
2251
2252=item $retval = IO::AIO::mount $special, $path, $fstype, $flags = 0, $data = undef
2253
2254Calls the GNU/Linux mount syscall with the given arguments. All except
2255C<$flags> are strings, and if C<$data> is C<undef>, a C<NULL> will be
2256passed.
2257
2258The following values for C<$flags> are available:
2259
2260C<IO::AIO::MS_RDONLY>, C<IO::AIO::MS_NOSUID>, C<IO::AIO::MS_NODEV>, C<IO::AIO::MS_NOEXEC>, C<IO::AIO::MS_SYNCHRONOUS>,
2261C<IO::AIO::MS_REMOUNT>, C<IO::AIO::MS_MANDLOCK>, C<IO::AIO::MS_DIRSYNC>, C<IO::AIO::MS_NOATIME>,
2262C<IO::AIO::MS_NODIRATIME>, C<IO::AIO::MS_BIND>, C<IO::AIO::MS_MOVE>, C<IO::AIO::MS_REC>, C<IO::AIO::MS_SILENT>,
2263C<IO::AIO::MS_POSIXACL>, C<IO::AIO::MS_UNBINDABLE>, C<IO::AIO::MS_PRIVATE>, C<IO::AIO::MS_SLAVE>, C<IO::AIO::MS_SHARED>,
2264C<IO::AIO::MS_RELATIME>, C<IO::AIO::MS_KERNMOUNT>, C<IO::AIO::MS_I_VERSION>, C<IO::AIO::MS_STRICTATIME>,
2265C<IO::AIO::MS_LAZYTIME>, C<IO::AIO::MS_ACTIVE>, C<IO::AIO::MS_NOUSER>, C<IO::AIO::MS_RMT_MASK>, C<IO::AIO::MS_MGC_VAL> and
2266C<IO::AIO::MS_MGC_MSK>.
2267
2268=item $retval = IO::AIO::umount $path, $flags = 0
2269
2270Invokes the GNU/Linux C<umount> or C<umount2> syscalls. Always calls
2271C<umount> if C<$flags> is C<0>, otherwqise always tries to call
2272C<umount2>.
2273
2274The following C<$flags> are available:
2275
2276C<IO::AIO::MNT_FORCE>, C<IO::AIO::MNT_DETACH>, C<IO::AIO::MNT_EXPIRE> and C<IO::AIO::UMOUNT_NOFOLLOW>.
2222 2277
2223=item $numfd = IO::AIO::get_fdlimit 2278=item $numfd = IO::AIO::get_fdlimit
2224 2279
2225Tries to find the current file descriptor limit and returns it, or 2280Tries to find the current file descriptor limit and returns it, or
2226C<undef> and sets C<$!> in case of an error. The limit is one larger than 2281C<undef> and sets C<$!> in case of an error. The limit is one larger than
… …
2483C<undef>. If the memfd_create syscall is missing, fails with C<ENOSYS>. 2538C<undef>. If the memfd_create syscall is missing, fails with C<ENOSYS>.
2484 2539
2485Please refer to L<memfd_create(2)> for more info on this call. 2540Please refer to L<memfd_create(2)> for more info on this call.
2486 2541
2487The following C<$flags> values are available: C<IO::AIO::MFD_CLOEXEC>, 2542The following C<$flags> values are available: C<IO::AIO::MFD_CLOEXEC>,
2488C<IO::AIO::MFD_ALLOW_SEALING> and C<IO::AIO::MFD_HUGETLB>. 2543C<IO::AIO::MFD_ALLOW_SEALING>, C<IO::AIO::MFD_HUGETLB>,
2544C<IO::AIO::MFD_HUGETLB_2MB> and C<IO::AIO::MFD_HUGETLB_1GB>.
2489 2545
2490Example: create a new memfd. 2546Example: create a new memfd.
2491 2547
2492 my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC 2548 my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC
2493 or die "memfd_create: $!\n"; 2549 or die "memfd_create: $!\n";

Diff Legend

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