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.297 by root, Thu Nov 29 19:53:46 2018 UTC vs.
Revision 1.319 by root, Wed Sep 27 03:09:57 2023 UTC

171use common::sense; 171use common::sense;
172 172
173use base 'Exporter'; 173use base 'Exporter';
174 174
175BEGIN { 175BEGIN {
176 our $VERSION = 4.6; 176 our $VERSION = 4.80;
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
278 IO::AIO::idle_timeout $seconds 283 IO::AIO::idle_timeout $seconds
279 IO::AIO::max_outstanding $maxreqs 284 IO::AIO::max_outstanding $maxreqs
280 IO::AIO::nreqs 285 IO::AIO::nreqs
281 IO::AIO::nready 286 IO::AIO::nready
282 IO::AIO::npending 287 IO::AIO::npending
288 IO::AIO::reinit
289
283 $nfd = IO::AIO::get_fdlimit [EXPERIMENTAL] 290 $nfd = IO::AIO::get_fdlimit
284 IO::AIO::min_fdlimit $nfd [EXPERIMENTAL] 291 IO::AIO::min_fdlimit $nfd
285 292
286 IO::AIO::sendfile $ofh, $ifh, $offset, $count 293 IO::AIO::sendfile $ofh, $ifh, $offset, $count
287 IO::AIO::fadvise $fh, $offset, $len, $advice 294 IO::AIO::fadvise $fh, $offset, $len, $advice
295 IO::AIO::fexecve $fh, $argv, $envp
296
288 IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]] 297 IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]]
289 IO::AIO::munmap $scalar 298 IO::AIO::munmap $scalar
290 IO::AIO::mremap $scalar, $new_length, $flags[, $new_address] 299 IO::AIO::mremap $scalar, $new_length, $flags[, $new_address]
291 IO::AIO::madvise $scalar, $offset, $length, $advice 300 IO::AIO::madvise $scalar, $offset, $length, $advice
292 IO::AIO::mprotect $scalar, $offset, $length, $protect 301 IO::AIO::mprotect $scalar, $offset, $length, $protect
293 IO::AIO::munlock $scalar, $offset = 0, $length = undef 302 IO::AIO::munlock $scalar, $offset = 0, $length = undef
294 IO::AIO::munlockall 303 IO::AIO::munlockall
304
305 # stat extensions
306 $counter = IO::AIO::st_gen
307 $seconds = IO::AIO::st_atime, IO::AIO::st_mtime, IO::AIO::st_ctime, IO::AIO::st_btime
308 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
309 $nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec, IO::AIO::st_ctimensec, IO::AIO::st_btimensec
310 $seconds = IO::AIO::st_btimesec
311 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec
312
313 # very much unportable syscalls
314 IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_len, $flags
315 IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
316 IO::AIO::tee $r_fh, $w_fh, $length, $flags
317
318 $actual_size = IO::AIO::pipesize $r_fh[, $new_size]
319 ($rfh, $wfh) = IO::AIO::pipe2 [$flags]
320
321 $fh = IO::AIO::eventfd [$initval, [$flags]]
322 $fh = IO::AIO::memfd_create $pathname[, $flags]
323
324 $fh = IO::AIO::timerfd_create $clockid[, $flags]
325 ($cur_interval, $cur_value) = IO::AIO::timerfd_settime $fh, $flags, $new_interval, $nbw_value
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
295 334
296=head2 API NOTES 335=head2 API NOTES
297 336
298All 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
299with 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,
374=item aio_open $pathname, $flags, $mode, $callback->($fh) 413=item aio_open $pathname, $flags, $mode, $callback->($fh)
375 414
376Asynchronously open or create a file and call the callback with a newly 415Asynchronously open or create a file and call the callback with a newly
377created filehandle for the file (or C<undef> in case of an error). 416created filehandle for the file (or C<undef> in case of an error).
378 417
379The pathname passed to C<aio_open> must be absolute. See API NOTES, above,
380for an explanation.
381
382The C<$flags> argument is a bitmask. See the C<Fcntl> module for a 418The C<$flags> argument is a bitmask. See the C<Fcntl> module for a
383list. They are the same as used by C<sysopen>. 419list. They are the same as used by C<sysopen>.
384 420
385Likewise, C<$mode> specifies the mode of the newly created file, if it 421Likewise, C<$mode> specifies the mode of the newly created file, if it
386didn't exist and C<O_CREAT> has been given, just like perl's C<sysopen>, 422didn't exist and C<O_CREAT> has been given, just like perl's C<sysopen>,
545 581
546Works almost exactly like perl's C<stat> or C<lstat> in void context. The 582Works almost exactly like perl's C<stat> or C<lstat> in void context. The
547callback will be called after the stat and the results will be available 583callback will be called after the stat and the results will be available
548using C<stat _> or C<-s _> and other tests (with the exception of C<-B> 584using C<stat _> or C<-s _> and other tests (with the exception of C<-B>
549and C<-T>). 585and C<-T>).
550
551The pathname passed to C<aio_stat> must be absolute. See API NOTES, above,
552for an explanation.
553 586
554Currently, the stats are always 64-bit-stats, i.e. instead of returning an 587Currently, the stats are always 64-bit-stats, i.e. instead of returning an
555error when stat'ing a large file, the results will be silently truncated 588error when stat'ing a large file, the results will be silently truncated
556unless perl itself is compiled with large file support. 589unless perl itself is compiled with large file support.
557 590
942 my @stat = stat $src_fh; # hmm, might block over nfs? 975 my @stat = stat $src_fh; # hmm, might block over nfs?
943 976
944 aioreq_pri $pri; 977 aioreq_pri $pri;
945 add $grp aio_open $dst, O_CREAT | O_WRONLY | O_TRUNC, 0200, sub { 978 add $grp aio_open $dst, O_CREAT | O_WRONLY | O_TRUNC, 0200, sub {
946 if (my $dst_fh = $_[0]) { 979 if (my $dst_fh = $_[0]) {
980
981 # best-effort preallocate
982 aioreq_pri $pri;
983 add $grp aio_allocate $dst_fh, IO::AIO::FALLOC_FL_KEEP_SIZE, 0, $stat[7], sub { };
984
947 aioreq_pri $pri; 985 aioreq_pri $pri;
948 add $grp aio_sendfile $dst_fh, $src_fh, 0, $stat[7], sub { 986 add $grp aio_sendfile $dst_fh, $src_fh, 0, $stat[7], sub {
949 if ($_[0] == $stat[7]) { 987 if ($_[0] == $stat[7]) {
950 $grp->result (0); 988 $grp->result (0);
951 close $src_fh; 989 close $src_fh;
1109 aioreq_pri $pri; 1147 aioreq_pri $pri;
1110 add $grp aio_stat $wd, sub { 1148 add $grp aio_stat $wd, sub {
1111 return $grp->result () if $_[0]; 1149 return $grp->result () if $_[0];
1112 my $now = time; 1150 my $now = time;
1113 my $hash1 = join ":", (stat _)[0,1,3,7,9]; 1151 my $hash1 = join ":", (stat _)[0,1,3,7,9];
1152 my $rdxflags = READDIR_DIRS_FIRST;
1153
1154 if ((stat _)[3] < 2) {
1155 # at least one non-POSIX filesystem exists
1156 # that returns useful DT_type values: btrfs,
1157 # so optimise for this here by requesting dents
1158 $rdxflags |= READDIR_DENTS;
1159 }
1114 1160
1115 # read the directory entries 1161 # read the directory entries
1116 aioreq_pri $pri; 1162 aioreq_pri $pri;
1117 add $grp aio_readdirx $wd, READDIR_DIRS_FIRST, sub { 1163 add $grp aio_readdirx $wd, $rdxflags, sub {
1118 my $entries = shift 1164 my ($entries, $flags) = @_
1119 or return $grp->result (); 1165 or return $grp->result ();
1166
1167 if ($rdxflags & READDIR_DENTS) {
1168 # if we requested type values, see if we can use them directly.
1169
1170 # if there were any DT_UNKNOWN entries then we assume we
1171 # don't know. alternatively, we could assume that if we get
1172 # one DT_DIR, then all directories are indeed marked with
1173 # DT_DIR, but this seems not required for btrfs, and this
1174 # is basically the "btrfs can't get it's act together" code
1175 # branch.
1176 unless ($flags & READDIR_FOUND_UNKNOWN) {
1177 # now we have valid DT_ information for all entries,
1178 # so use it as an optimisation without further stat's.
1179 # they must also all be at the beginning of @$entries
1180 # by now.
1181
1182 my $dirs;
1183
1184 if (@$entries) {
1185 for (0 .. $#$entries) {
1186 if ($entries->[$_][1] != DT_DIR) {
1187 # splice out directories
1188 $dirs = [splice @$entries, 0, $_];
1189 last;
1190 }
1191 }
1192
1193 # if we didn't find any non-dir, then all entries are dirs
1194 unless ($dirs) {
1195 ($dirs, $entries) = ($entries, []);
1196 }
1197 } else {
1198 # directory is empty, so there are no sbdirs
1199 $dirs = [];
1200 }
1201
1202 # either splice'd the directories out or the dir was empty.
1203 # convert dents to filenames
1204 $_ = $_->[0] for @$dirs;
1205 $_ = $_->[0] for @$entries;
1206
1207 return $grp->result ($dirs, $entries);
1208 }
1209
1210 # cannot use, so return to our old ways
1211 # by pretending we only scanned for names.
1212 $_ = $_->[0] for @$entries;
1213 }
1120 1214
1121 # stat the dir another time 1215 # stat the dir another time
1122 aioreq_pri $pri; 1216 aioreq_pri $pri;
1123 add $grp aio_stat $wd, sub { 1217 add $grp aio_stat $wd, sub {
1124 my $hash2 = join ":", (stat _)[0,1,3,7,9]; 1218 my $hash2 = join ":", (stat _)[0,1,3,7,9];
1230So in general, you should only use these calls for things that do 1324So in general, you should only use these calls for things that do
1231(filesystem) I/O, not for things that wait for other events (network, 1325(filesystem) I/O, not for things that wait for other events (network,
1232other processes), although if you are careful and know what you are doing, 1326other processes), although if you are careful and know what you are doing,
1233you still can. 1327you still can.
1234 1328
1235The following constants are available (missing ones are, as usual C<0>): 1329The following constants are available and can be used for normal C<ioctl>
1330and C<fcntl> as well (missing ones are, as usual C<0>):
1236 1331
1237C<F_DUPFD_CLOEXEC>, 1332C<F_DUPFD_CLOEXEC>,
1238 1333
1239C<F_OFD_GETLK>, C<F_OFD_SETLK>, C<F_OFD_GETLKW>, 1334C<F_OFD_GETLK>, C<F_OFD_SETLK>, C<F_OFD_GETLKW>,
1240 1335
1241C<FIFREEZE>, C<FITHAW>, C<FITRIM>, C<FICLONE>, C<FICLONERANGE>, C<FIDEDUPERANGE>. 1336C<FIFREEZE>, C<FITHAW>, C<FITRIM>, C<FICLONE>, C<FICLONERANGE>, C<FIDEDUPERANGE>.
1337
1338C<F_ADD_SEALS>, C<F_GET_SEALS>, C<F_SEAL_SEAL>, C<F_SEAL_SHRINK>, C<F_SEAL_GROW> and
1339C<F_SEAL_WRITE>.
1242 1340
1243C<FS_IOC_GETFLAGS>, C<FS_IOC_SETFLAGS>, C<FS_IOC_GETVERSION>, C<FS_IOC_SETVERSION>, 1341C<FS_IOC_GETFLAGS>, C<FS_IOC_SETFLAGS>, C<FS_IOC_GETVERSION>, C<FS_IOC_SETVERSION>,
1244C<FS_IOC_FIEMAP>. 1342C<FS_IOC_FIEMAP>.
1245 1343
1246C<FS_IOC_FSGETXATTR>, C<FS_IOC_FSSETXATTR>, C<FS_IOC_SET_ENCRYPTION_POLICY>, 1344C<FS_IOC_FSGETXATTR>, C<FS_IOC_FSSETXATTR>, C<FS_IOC_SET_ENCRYPTION_POLICY>,
1254 1352
1255C<FS_XFLAG_REALTIME>, C<FS_XFLAG_PREALLOC>, C<FS_XFLAG_IMMUTABLE>, C<FS_XFLAG_APPEND>, 1353C<FS_XFLAG_REALTIME>, C<FS_XFLAG_PREALLOC>, C<FS_XFLAG_IMMUTABLE>, C<FS_XFLAG_APPEND>,
1256C<FS_XFLAG_SYNC>, C<FS_XFLAG_NOATIME>, C<FS_XFLAG_NODUMP>, C<FS_XFLAG_RTINHERIT>, 1354C<FS_XFLAG_SYNC>, C<FS_XFLAG_NOATIME>, C<FS_XFLAG_NODUMP>, C<FS_XFLAG_RTINHERIT>,
1257C<FS_XFLAG_PROJINHERIT>, C<FS_XFLAG_NOSYMLINKS>, C<FS_XFLAG_EXTSIZE>, C<FS_XFLAG_EXTSZINHERIT>, 1355C<FS_XFLAG_PROJINHERIT>, C<FS_XFLAG_NOSYMLINKS>, C<FS_XFLAG_EXTSIZE>, C<FS_XFLAG_EXTSZINHERIT>,
1258C<FS_XFLAG_NODEFRAG>, C<FS_XFLAG_FILESTREAM>, C<FS_XFLAG_DAX>, C<FS_XFLAG_HASATTR>, 1356C<FS_XFLAG_NODEFRAG>, C<FS_XFLAG_FILESTREAM>, C<FS_XFLAG_DAX>, C<FS_XFLAG_HASATTR>,
1357
1358C<BLKROSET>, C<BLKROGET>, C<BLKRRPART>, C<BLKGETSIZE>, C<BLKFLSBUF>, C<BLKRASET>,
1359C<BLKRAGET>, C<BLKFRASET>, C<BLKFRAGET>, C<BLKSECTSET>, C<BLKSECTGET>, C<BLKSSZGET>,
1360C<BLKBSZGET>, C<BLKBSZSET>, C<BLKGETSIZE64>,
1361
1259 1362
1260=item aio_sync $callback->($status) 1363=item aio_sync $callback->($status)
1261 1364
1262Asynchronously call sync and call the callback when finished. 1365Asynchronously call sync and call the callback when finished.
1263 1366
1596C<aio_wd> callback, as future requests using the value will fail in the 1699C<aio_wd> callback, as future requests using the value will fail in the
1597expected way. 1700expected way.
1598 1701
1599=item IO::AIO::CWD 1702=item IO::AIO::CWD
1600 1703
1601This is a compiletime constant (object) that represents the process 1704This is a compile time constant (object) that represents the process
1602current working directory. 1705current working directory.
1603 1706
1604Specifying this object as working directory object for a pathname is as if 1707Specifying this object as working directory object for a pathname is as if
1605the pathname would be specified directly, without a directory object. For 1708the pathname would be specified directly, without a directory object. For
1606example, these calls are functionally identical: 1709example, these calls are functionally identical:
1978longer exceeded. 2081longer exceeded.
1979 2082
1980In other words, this setting does not enforce a queue limit, but can be 2083In other words, this setting does not enforce a queue limit, but can be
1981used to make poll functions block if the limit is exceeded. 2084used to make poll functions block if the limit is exceeded.
1982 2085
1983This is a very bad function to use in interactive programs because it 2086This is a bad function to use in interactive programs because it blocks,
1984blocks, and a bad way to reduce concurrency because it is inexact: Better 2087and a bad way to reduce concurrency because it is inexact. If you need to
2088issue many requests without being able to call a poll function on demand,
1985use an C<aio_group> together with a feed callback. 2089it is better to use an C<aio_group> together with a feed callback.
1986 2090
1987Its main use is in scripts without an event loop - when you want to stat 2091Its main use is in scripts without an event loop - when you want to stat a
1988a lot of files, you can write something like this: 2092lot of files, you can write something like this:
1989 2093
1990 IO::AIO::max_outstanding 32; 2094 IO::AIO::max_outstanding 32;
1991 2095
1992 for my $path (...) { 2096 for my $path (...) {
1993 aio_stat $path , ...; 2097 aio_stat $path , ...;
1994 IO::AIO::poll_cb; 2098 IO::AIO::poll_cb;
1995 } 2099 }
1996 2100
1997 IO::AIO::flush; 2101 IO::AIO::flush;
1998 2102
1999The call to C<poll_cb> inside the loop will normally return instantly, but 2103The call to C<poll_cb> inside the loop will normally return instantly,
2000as soon as more thna C<32> reqeusts are in-flight, it will block until 2104allowing the loop to progress, but as soon as more than C<32> requests
2001some requests have been handled. This keeps the loop from pushing a large 2105are in-flight, it will block until some requests have been handled. This
2002number of C<aio_stat> requests onto the queue. 2106keeps the loop from pushing a large number of C<aio_stat> requests onto
2107the queue (which, with many paths to stat, can use up a lot of memory).
2003 2108
2004The default value for C<max_outstanding> is very large, so there is no 2109The default value for C<max_outstanding> is very large, so there is no
2005practical limit on the number of outstanding requests. 2110practical limit on the number of outstanding requests.
2006 2111
2007=back 2112=back
2066for times around now - see the I<nsec> function family, below, for full 2171for times around now - see the I<nsec> function family, below, for full
2067accuracy. 2172accuracy.
2068 2173
2069File birth time is only available when the OS and perl support it (on 2174File birth time is only available when the OS and perl support it (on
2070FreeBSD and NetBSD at the time of this writing, although support is 2175FreeBSD and NetBSD at the time of this writing, although support is
2071adaptive, so if your OS/perl gains support, IO::AIO can take avdantage of 2176adaptive, so if your OS/perl gains support, IO::AIO can take advantage of
2072it). On systems where it isn't available, C<0> is currently returned, but 2177it). On systems where it isn't available, C<0> is currently returned, but
2073this might change to C<undef> in a future version. 2178this might change to C<undef> in a future version.
2074 2179
2075=item ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime 2180=item ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
2076 2181
2135"Asynchronous I/O" route. Many of these have an asynchronous C<aio_*> 2240"Asynchronous I/O" route. Many of these have an asynchronous C<aio_*>
2136counterpart. 2241counterpart.
2137 2242
2138=over 4 2243=over 4
2139 2244
2245=item $retval = IO::AIO::fexecve $fh, $argv, $envp
2246
2247A more-or-less direct equivalent to the POSIX C<fexecve> functions, which
2248allows you to specify the program to be executed via a file descriptor (or
2249handle). Returns C<-1> and sets errno to C<ENOSYS> if not available.
2250
2251=item $retval = IO::AIO::mount $special, $path, $fstype, $flags = 0, $data = undef
2252
2253Calls the GNU/Linux mount syscall with the given arguments. All except
2254C<$flags> are strings, and if C<$data> is C<undef>, a C<NULL> will be
2255passed.
2256
2257The following values for C<$flags> are available:
2258
2259C<IO::AIO::MS_RDONLY>, C<IO::AIO::MS_NOSUID>, C<IO::AIO::MS_NODEV>, C<IO::AIO::MS_NOEXEC>, C<IO::AIO::MS_SYNCHRONOUS>,
2260C<IO::AIO::MS_REMOUNT>, C<IO::AIO::MS_MANDLOCK>, C<IO::AIO::MS_DIRSYNC>, C<IO::AIO::MS_NOATIME>,
2261C<IO::AIO::MS_NODIRATIME>, C<IO::AIO::MS_BIND>, C<IO::AIO::MS_MOVE>, C<IO::AIO::MS_REC>, C<IO::AIO::MS_SILENT>,
2262C<IO::AIO::MS_POSIXACL>, C<IO::AIO::MS_UNBINDABLE>, C<IO::AIO::MS_PRIVATE>, C<IO::AIO::MS_SLAVE>, C<IO::AIO::MS_SHARED>,
2263C<IO::AIO::MS_RELATIME>, C<IO::AIO::MS_KERNMOUNT>, C<IO::AIO::MS_I_VERSION>, C<IO::AIO::MS_STRICTATIME>,
2264C<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
2265C<IO::AIO::MS_MGC_MSK>.
2266
2267=item $retval = IO::AIO::umount $path, $flags = 0
2268
2269Invokes the GNU/Linux C<umount> or C<umount2> syscalls. Always calls
2270C<umount> if C<$flags> is C<0>, otherwqise always tries to call
2271C<umount2>.
2272
2273The following C<$flags> are available:
2274
2275C<IO::AIO::MNT_FORCE>, C<IO::AIO::MNT_DETACH>, C<IO::AIO::MNT_EXPIRE> and C<IO::AIO::UMOUNT_NOFOLLOW>.
2276
2140=item $numfd = IO::AIO::get_fdlimit 2277=item $numfd = IO::AIO::get_fdlimit
2141
2142This function is I<EXPERIMENTAL> and subject to change.
2143 2278
2144Tries to find the current file descriptor limit and returns it, or 2279Tries to find the current file descriptor limit and returns it, or
2145C<undef> and sets C<$!> in case of an error. The limit is one larger than 2280C<undef> and sets C<$!> in case of an error. The limit is one larger than
2146the highest valid file descriptor number. 2281the highest valid file descriptor number.
2147 2282
2148=item IO::AIO::min_fdlimit [$numfd] 2283=item IO::AIO::min_fdlimit [$numfd]
2149
2150This function is I<EXPERIMENTAL> and subject to change.
2151 2284
2152Try to increase the current file descriptor limit(s) to at least C<$numfd> 2285Try to increase the current file descriptor limit(s) to at least C<$numfd>
2153by changing the soft or hard file descriptor resource limit. If C<$numfd> 2286by changing the soft or hard file descriptor resource limit. If C<$numfd>
2154is missing, it will try to set a very high limit, although this is not 2287is missing, it will try to set a very high limit, although this is not
2155recommended when you know the actual minimum that you require. 2288recommended when you know the actual minimum that you require.
2250C<IO::AIO::MAP_POPULATE>, 2383C<IO::AIO::MAP_POPULATE>,
2251C<IO::AIO::MAP_NONBLOCK>, 2384C<IO::AIO::MAP_NONBLOCK>,
2252C<IO::AIO::MAP_FIXED>, 2385C<IO::AIO::MAP_FIXED>,
2253C<IO::AIO::MAP_GROWSDOWN>, 2386C<IO::AIO::MAP_GROWSDOWN>,
2254C<IO::AIO::MAP_32BIT>, 2387C<IO::AIO::MAP_32BIT>,
2255C<IO::AIO::MAP_HUGETLB> or 2388C<IO::AIO::MAP_HUGETLB>,
2256C<IO::AIO::MAP_STACK>. 2389C<IO::AIO::MAP_STACK>,
2390C<IO::AIO::MAP_FIXED_NOREPLACE>,
2391C<IO::AIO::MAP_SHARED_VALIDATE>,
2392C<IO::AIO::MAP_SYNC> or
2393C<IO::AIO::MAP_UNINITIALIZED>.
2257 2394
2258If C<$fh> is C<undef>, then a file descriptor of C<-1> is passed. 2395If C<$fh> is C<undef>, then a file descriptor of C<-1> is passed.
2259 2396
2260C<$offset> is the offset from the start of the file - it generally must be 2397C<$offset> is the offset from the start of the file - it generally must be
2261a multiple of C<IO::AIO::PAGESIZE> and defaults to C<0>. 2398a multiple of C<IO::AIO::PAGESIZE> and defaults to C<0>.
2298implemented, but not supported and might go away in a future version. 2435implemented, but not supported and might go away in a future version.
2299 2436
2300On systems where this call is not supported or is not emulated, this call 2437On systems where this call is not supported or is not emulated, this call
2301returns falls and sets C<$!> to C<ENOSYS>. 2438returns falls and sets C<$!> to C<ENOSYS>.
2302 2439
2440=item IO::AIO::mlockall $flags
2441
2442Calls the C<eio_mlockall_sync> function, which is like C<aio_mlockall>,
2443but is blocking.
2444
2303=item IO::AIO::munlock $scalar, $offset = 0, $length = undef 2445=item IO::AIO::munlock $scalar, $offset = 0, $length = undef
2304 2446
2305Calls the C<munlock> function, undoing the effects of a previous 2447Calls the C<munlock> function, undoing the effects of a previous
2306C<aio_mlock> call (see its description for details). 2448C<aio_mlock> call (see its description for details).
2307 2449
2309 2451
2310Calls the C<munlockall> function. 2452Calls the C<munlockall> function.
2311 2453
2312On systems that do not implement C<munlockall>, this function returns 2454On systems that do not implement C<munlockall>, this function returns
2313ENOSYS, otherwise the return value of C<munlockall>. 2455ENOSYS, otherwise the return value of C<munlockall>.
2456
2457=item $fh = IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_maxlen, $flags
2458
2459Uses the GNU/Linux C<accept4(2)> syscall, if available, to accept a socket
2460and return the new file handle on success, or sets C<$!> and returns
2461C<undef> on error.
2462
2463The remote name of the new socket will be stored in C<$sockaddr>, which
2464will be extended to allow for at least C<$sockaddr_maxlen> octets. If the
2465socket name does not fit into C<$sockaddr_maxlen> octets, this is signaled
2466by returning a longer string in C<$sockaddr>, which might or might not be
2467truncated.
2468
2469To accept name-less sockets, use C<undef> for C<$sockaddr> and C<0> for
2470C<$sockaddr_maxlen>.
2471
2472The main reasons to use this syscall rather than portable C<accept(2)>
2473are that you can specify C<SOCK_NONBLOCK> and/or C<SOCK_CLOEXEC>
2474flags and you can accept name-less sockets by specifying C<0> for
2475C<$sockaddr_maxlen>, which is sadly not possible with perl's interface to
2476C<accept>.
2314 2477
2315=item IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags 2478=item IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
2316 2479
2317Calls the GNU/Linux C<splice(2)> syscall, if available. If C<$r_off> or 2480Calls the GNU/Linux C<splice(2)> syscall, if available. If C<$r_off> or
2318C<$w_off> are C<undef>, then C<NULL> is passed for these, otherwise they 2481C<$w_off> are C<undef>, then C<NULL> is passed for these, otherwise they
2362Example: create a pipe race-free w.r.t. threads and fork: 2525Example: create a pipe race-free w.r.t. threads and fork:
2363 2526
2364 my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC 2527 my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC
2365 or die "pipe2: $!\n"; 2528 or die "pipe2: $!\n";
2366 2529
2530=item $fh = IO::AIO::memfd_create $pathname[, $flags]
2531
2532This is a direct interface to the Linux L<memfd_create(2)> system
2533call. The (unhelpful) default for C<$flags> is C<0>, but your default
2534should be C<IO::AIO::MFD_CLOEXEC>.
2535
2536On success, the new memfd filehandle is returned, otherwise returns
2537C<undef>. If the memfd_create syscall is missing, fails with C<ENOSYS>.
2538
2539Please refer to L<memfd_create(2)> for more info on this call.
2540
2541The following C<$flags> values are available: C<IO::AIO::MFD_CLOEXEC>,
2542C<IO::AIO::MFD_ALLOW_SEALING>, C<IO::AIO::MFD_HUGETLB>,
2543C<IO::AIO::MFD_HUGETLB_2MB> and C<IO::AIO::MFD_HUGETLB_1GB>.
2544
2545Example: create a new memfd.
2546
2547 my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC
2548 or die "memfd_create: $!\n";
2549
2550=item $fh = IO::AIO::pidfd_open $pid[, $flags]
2551
2552This is an interface to the Linux L<pidfd_open(2)> system call. The
2553default for C<$flags> is C<0>.
2554
2555On success, a new pidfd filehandle is returned (that is already set to
2556close-on-exec), otherwise returns C<undef>. If the syscall is missing,
2557fails with C<ENOSYS>.
2558
2559Example: open pid 6341 as pidfd.
2560
2561 my $fh = IO::AIO::pidfd_open 6341
2562 or die "pidfd_open: $!\n";
2563
2564=item $status = IO::AIO::pidfd_send_signal $pidfh, $signal[, $siginfo[, $flags]]
2565
2566This is an interface to the Linux L<pidfd_send_signal> system call. The
2567default for C<$siginfo> is C<undef> and the default for C<$flags> is C<0>.
2568
2569Returns the system call status. If the syscall is missing, fails with
2570C<ENOSYS>.
2571
2572When specified, C<$siginfo> must be a reference to a hash with one or more
2573of the following members:
2574
2575=over
2576
2577=item code - the C<si_code> member
2578
2579=item pid - the C<si_pid> member
2580
2581=item uid - the C<si_uid> member
2582
2583=item value_int - the C<si_value.sival_int> member
2584
2585=item value_ptr - the C<si_value.sival_ptr> member, specified as an integer
2586
2587=back
2588
2589Example: send a SIGKILL to the specified process.
2590
2591 my $status = IO::AIO::pidfd_send_signal $pidfh, 9, undef
2592 and die "pidfd_send_signal: $!\n";
2593
2594Example: send a SIGKILL to the specified process with extra data.
2595
2596 my $status = IO::AIO::pidfd_send_signal $pidfh, 9, { code => -1, value_int => 7 }
2597 and die "pidfd_send_signal: $!\n";
2598
2599=item $fh = IO::AIO::pidfd_getfd $pidfh, $targetfd[, $flags]
2600
2601This is an interface to the Linux L<pidfd_getfd> system call. The default
2602for C<$flags> is C<0>.
2603
2604On success, returns a dup'ed copy of the target file descriptor (specified
2605as an integer) returned (that is already set to close-on-exec), otherwise
2606returns C<undef>. If the syscall is missing, fails with C<ENOSYS>.
2607
2608Example: get a copy of standard error of another process and print soemthing to it.
2609
2610 my $errfh = IO::AIO::pidfd_getfd $pidfh, 2
2611 or die "pidfd_getfd: $!\n";
2612 print $errfh "stderr\n";
2613
2367=item $fh = IO::AIO::eventfd [$initval, [$flags]] 2614=item $fh = IO::AIO::eventfd [$initval, [$flags]]
2368 2615
2369This is a direct interface to the Linux L<eventfd(2)> system call. The 2616This is a direct interface to the Linux L<eventfd(2)> system call. The
2370(unhelpful) defaults for C<$initval> and C<$flags> are C<0> for both. 2617(unhelpful) defaults for C<$initval> and C<$flags> are C<0> for both.
2371 2618
2377The following symbol flag values are available: C<IO::AIO::EFD_CLOEXEC>, 2624The following symbol flag values are available: C<IO::AIO::EFD_CLOEXEC>,
2378C<IO::AIO::EFD_NONBLOCK> and C<IO::AIO::EFD_SEMAPHORE> (Linux 2.6.30). 2625C<IO::AIO::EFD_NONBLOCK> and C<IO::AIO::EFD_SEMAPHORE> (Linux 2.6.30).
2379 2626
2380Example: create a new eventfd filehandle: 2627Example: create a new eventfd filehandle:
2381 2628
2382 $fh = IO::AIO::eventfd 0, IO::AIO::O_CLOEXEC 2629 $fh = IO::AIO::eventfd 0, IO::AIO::EFD_CLOEXEC
2383 or die "eventfd: $!\n"; 2630 or die "eventfd: $!\n";
2384 2631
2385=item $fh = IO::AIO::timerfd_create $clockid[, $flags] 2632=item $fh = IO::AIO::timerfd_create $clockid[, $flags]
2386 2633
2387This is a direct interface to the Linux L<timerfd_create(2)> system call. The 2634This is a direct interface to the Linux L<timerfd_create(2)> system
2388(unhelpful) default for C<$flags> is C<0>. 2635call. The (unhelpful) default for C<$flags> is C<0>, but your default
2636should be C<IO::AIO::TFD_CLOEXEC>.
2389 2637
2390On success, the new timerfd filehandle is returned, otherwise returns 2638On success, the new timerfd filehandle is returned, otherwise returns
2391C<undef>. If the eventfd syscall is missing, fails with C<ENOSYS>. 2639C<undef>. If the timerfd_create syscall is missing, fails with C<ENOSYS>.
2392 2640
2393Please refer to L<timerfd_create(2)> for more info on this call. 2641Please refer to L<timerfd_create(2)> for more info on this call.
2394 2642
2395The following C<$clockid> values are 2643The following C<$clockid> values are
2396available: C<IO::AIO::CLOCK_REALTIME>, C<IO::AIO::CLOCK_MONOTONIC> 2644available: C<IO::AIO::CLOCK_REALTIME>, C<IO::AIO::CLOCK_MONOTONIC>
2562known issue, rather than a bug. 2810known issue, rather than a bug.
2563 2811
2564=head1 SEE ALSO 2812=head1 SEE ALSO
2565 2813
2566L<AnyEvent::AIO> for easy integration into event loops, L<Coro::AIO> for a 2814L<AnyEvent::AIO> for easy integration into event loops, L<Coro::AIO> for a
2567more natural syntax. 2815more natural syntax and L<IO::FDPass> for file descriptor passing.
2568 2816
2569=head1 AUTHOR 2817=head1 AUTHOR
2570 2818
2571 Marc Lehmann <schmorp@schmorp.de> 2819 Marc Lehmann <schmorp@schmorp.de>
2572 http://home.schmorp.de/ 2820 http://home.schmorp.de/

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines