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.278 by root, Sun Oct 1 07:24:34 2017 UTC vs.
Revision 1.284 by root, Fri Mar 23 01:14:08 2018 UTC

… …
171use common::sense; 171use common::sense;
172 172
173use base 'Exporter'; 173use base 'Exporter';
174 174
175BEGIN { 175BEGIN {
176 our $VERSION = 4.35; 176 our $VERSION = 4.4;
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
… …
183 aio_rename aio_rename2 aio_link aio_move aio_copy aio_group 183 aio_rename aio_rename2 aio_link aio_move aio_copy aio_group
184 aio_nop aio_mknod aio_load aio_rmtree aio_mkdir aio_chown 184 aio_nop aio_mknod aio_load aio_rmtree aio_mkdir aio_chown
185 aio_chmod aio_utime aio_truncate 185 aio_chmod aio_utime aio_truncate
186 aio_msync aio_mtouch aio_mlock aio_mlockall 186 aio_msync aio_mtouch aio_mlock aio_mlockall
187 aio_statvfs 187 aio_statvfs
188 aio_slurp
188 aio_wd); 189 aio_wd);
189 190
190 our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice)); 191 our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice));
191 our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush 192 our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush
192 min_parallel max_parallel max_idle idle_timeout 193 min_parallel max_parallel max_idle idle_timeout
… …
611 namemax => 255, 612 namemax => 255,
612 frsize => 1024, 613 frsize => 1024,
613 fsid => 1810 614 fsid => 1810
614 } 615 }
615 616
616Here is a (likely partial - send me updates!) list of fsid values used by
617Linux - it is safe to hardcode these when C<$^O> is C<linux>:
618
619 0x0000adf5 adfs
620 0x0000adff affs
621 0x5346414f afs
622 0x09041934 anon-inode filesystem
623 0x00000187 autofs
624 0x42465331 befs
625 0x1badface bfs
626 0x42494e4d binfmt_misc
627 0x9123683e btrfs
628 0x0027e0eb cgroupfs
629 0xff534d42 cifs
630 0x73757245 coda
631 0x012ff7b7 coh
632 0x28cd3d45 cramfs
633 0x453dcd28 cramfs-wend (wrong endianness)
634 0x64626720 debugfs
635 0x00001373 devfs
636 0x00001cd1 devpts
637 0x0000f15f ecryptfs
638 0x00414a53 efs
639 0x0000137d ext
640 0x0000ef53 ext2/ext3/ext4
641 0x0000ef51 ext2
642 0xf2f52010 f2fs
643 0x00004006 fat
644 0x65735546 fuseblk
645 0x65735543 fusectl
646 0x0bad1dea futexfs
647 0x01161970 gfs2
648 0x47504653 gpfs
649 0x00004244 hfs
650 0xf995e849 hpfs
651 0x00c0ffee hostfs
652 0x958458f6 hugetlbfs
653 0x2bad1dea inotifyfs
654 0x00009660 isofs
655 0x000072b6 jffs2
656 0x3153464a jfs
657 0x6b414653 k-afs
658 0x0bd00bd0 lustre
659 0x0000137f minix
660 0x0000138f minix 30 char names
661 0x00002468 minix v2
662 0x00002478 minix v2 30 char names
663 0x00004d5a minix v3
664 0x19800202 mqueue
665 0x00004d44 msdos
666 0x0000564c novell
667 0x00006969 nfs
668 0x6e667364 nfsd
669 0x00003434 nilfs
670 0x5346544e ntfs
671 0x00009fa1 openprom
672 0x7461636F ocfs2
673 0x00009fa0 proc
674 0x6165676c pstorefs
675 0x0000002f qnx4
676 0x68191122 qnx6
677 0x858458f6 ramfs
678 0x52654973 reiserfs
679 0x00007275 romfs
680 0x67596969 rpc_pipefs
681 0x73636673 securityfs
682 0xf97cff8c selinux
683 0x0000517b smb
684 0x534f434b sockfs
685 0x73717368 squashfs
686 0x62656572 sysfs
687 0x012ff7b6 sysv2
688 0x012ff7b5 sysv4
689 0x01021994 tmpfs
690 0x15013346 udf
691 0x00011954 ufs
692 0x54190100 ufs byteswapped
693 0x00009fa2 usbdevfs
694 0x01021997 v9fs
695 0xa501fcf5 vxfs
696 0xabba1974 xenfs
697 0x012ff7b4 xenix
698 0x58465342 xfs
699 0x012fd16d xia
700
701=item aio_utime $fh_or_path, $atime, $mtime, $callback->($status) 617=item aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
702 618
703Works like perl's C<utime> function (including the special case of $atime 619Works like perl's C<utime> function (including the special case of $atime
704and $mtime being undef). Fractional times are supported if the underlying 620and $mtime being undef). Fractional times are supported if the underlying
705syscalls support them. 621syscalls support them.
… …
873 789
874=over 4 790=over 4
875 791
876=item IO::AIO::READDIR_DENTS 792=item IO::AIO::READDIR_DENTS
877 793
878When this flag is off, then the callback gets an arrayref consisting of 794Normally the callback gets an arrayref consisting of names only (as
879names only (as with C<aio_readdir>), otherwise it gets an arrayref with 795with C<aio_readdir>). If this flag is set, then the callback gets an
880C<[$name, $type, $inode]> arrayrefs, each describing a single directory 796arrayref with C<[$name, $type, $inode]> arrayrefs, each describing a
881entry in more detail. 797single directory entry in more detail:
882 798
883C<$name> is the name of the entry. 799C<$name> is the name of the entry.
884 800
885C<$type> is one of the C<IO::AIO::DT_xxx> constants: 801C<$type> is one of the C<IO::AIO::DT_xxx> constants:
886 802
887C<IO::AIO::DT_UNKNOWN>, C<IO::AIO::DT_FIFO>, C<IO::AIO::DT_CHR>, C<IO::AIO::DT_DIR>, 803C<IO::AIO::DT_UNKNOWN>, C<IO::AIO::DT_FIFO>, C<IO::AIO::DT_CHR>, C<IO::AIO::DT_DIR>,
888C<IO::AIO::DT_BLK>, C<IO::AIO::DT_REG>, C<IO::AIO::DT_LNK>, C<IO::AIO::DT_SOCK>, 804C<IO::AIO::DT_BLK>, C<IO::AIO::DT_REG>, C<IO::AIO::DT_LNK>, C<IO::AIO::DT_SOCK>,
889C<IO::AIO::DT_WHT>. 805C<IO::AIO::DT_WHT>.
890 806
891C<IO::AIO::DT_UNKNOWN> means just that: readdir does not know. If you need to 807C<IO::AIO::DT_UNKNOWN> means just that: readdir does not know. If you need
892know, you have to run stat yourself. Also, for speed reasons, the C<$type> 808to know, you have to run stat yourself. Also, for speed/memory reasons,
893scalars are read-only: you can not modify them. 809the C<$type> scalars are read-only: you must not modify them.
894 810
895C<$inode> is the inode number (which might not be exact on systems with 64 811C<$inode> is the inode number (which might not be exact on systems with 64
896bit inode numbers and 32 bit perls). This field has unspecified content on 812bit inode numbers and 32 bit perls). This field has unspecified content on
897systems that do not deliver the inode information. 813systems that do not deliver the inode information.
898 814
… …
909short names are tried first. 825short names are tried first.
910 826
911=item IO::AIO::READDIR_STAT_ORDER 827=item IO::AIO::READDIR_STAT_ORDER
912 828
913When this flag is set, then the names will be returned in an order 829When this flag is set, then the names will be returned in an order
914suitable for stat()'ing each one. That is, when you plan to stat() 830suitable for stat()'ing each one. That is, when you plan to stat() most or
915all files in the given directory, then the returned order will likely 831all files in the given directory, then the returned order will likely be
916be fastest. 832faster.
917 833
918If both this flag and C<IO::AIO::READDIR_DIRS_FIRST> are specified, then 834If both this flag and C<IO::AIO::READDIR_DIRS_FIRST> are specified,
919the likely dirs come first, resulting in a less optimal stat order. 835then the likely dirs come first, resulting in a less optimal stat order
836for stat'ing all entries, but likely a more optimal order for finding
837subdirectories.
920 838
921=item IO::AIO::READDIR_FOUND_UNKNOWN 839=item IO::AIO::READDIR_FOUND_UNKNOWN
922 840
923This flag should not be set when calling C<aio_readdirx>. Instead, it 841This flag should not be set when calling C<aio_readdirx>. Instead, it
924is being set by C<aio_readdirx>, when any of the C<$type>'s found were 842is being set by C<aio_readdirx>, when any of the C<$type>'s found were
… …
926C<$type>'s are known, which can be used to speed up some algorithms. 844C<$type>'s are known, which can be used to speed up some algorithms.
927 845
928=back 846=back
929 847
930 848
849=item aio_slurp $pathname, $offset, $length, $data, $callback->($status)
850
851Opens, reads and closes the given file. The data is put into C<$data>,
852which is resized as required.
853
854If C<$offset> is negative, then it is counted from the end of the file.
855
856If C<$length> is zero, then the remaining length of the file is
857used. Also, in this case, the same limitations to modifying C<$data> apply
858as when IO::AIO::mmap is used, i.e. it must only be modified in-place
859with C<substr>. If the size of the file is known, specifying a non-zero
860C<$length> results in a performance advantage.
861
862This request is similar to the older C<aio_load> request, but since it is
863a single request, it might be more efficient to use.
864
865Example: load F</etc/passwd> into C<$passwd>.
866
867 my $passwd;
868 aio_slurp "/etc/passwd", 0, 0, $passwd, sub {
869 $_[0] >= 0
870 or die "/etc/passwd: $!\n";
871
872 printf "/etc/passwd is %d bytes long, and contains:\n", length $passwd;
873 print $passwd;
874 };
875 IO::AIO::flush;
876
877
931=item aio_load $pathname, $data, $callback->($status) 878=item aio_load $pathname, $data, $callback->($status)
932 879
933This is a composite request that tries to fully load the given file into 880This is a composite request that tries to fully load the given file into
934memory. Status is the same as with aio_read. 881memory. Status is the same as with aio_read.
882
883Using C<aio_slurp> might be more efficient, as it is a single request.
935 884
936=cut 885=cut
937 886
938sub aio_load($$;$) { 887sub aio_load($$;$) {
939 my ($path, undef, $cb) = @_; 888 my ($path, undef, $cb) = @_;
… …
2268 2217
2269Please refer to L<pipe2(2)> for more info on the C<$flags>, but at the 2218Please refer to L<pipe2(2)> for more info on the C<$flags>, but at the
2270time of this writing, C<IO::AIO::O_CLOEXEC>, C<IO::AIO::O_NONBLOCK> and 2219time of this writing, C<IO::AIO::O_CLOEXEC>, C<IO::AIO::O_NONBLOCK> and
2271C<IO::AIO::O_DIRECT> (Linux 3.4, for packet-based pipes) were supported. 2220C<IO::AIO::O_DIRECT> (Linux 3.4, for packet-based pipes) were supported.
2272 2221
2222Example: create a pipe race-free w.r.t. threads and fork:
2223
2224 my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC
2225 or die "pipe2: $!\n";
2226
2227=item $fh = IO::AIO::eventfd [$initval, [$flags]]
2228
2229This is a direct interface to the Linux L<eventfd(2)> system call. The
2230(unhelpful) defaults for C<$initval> and C<$flags> are C<0> for both.
2231
2232On success, the new eventfd filehandle is returned, otherwise returns
2233C<undef>. If the eventfd syscall is missing, fails with C<ENOSYS>.
2234
2235Please refer to L<eventfd(2)> for more info on this call.
2236
2237The following symbol flag values are available: C<IO::AIO::EFD_CLOEXEC>,
2238C<IO::AIO::EFD_NONBLOCK> and C<IO::AIO::EFD_SEMAPHORE> (Linux 2.6.30).
2239
2240Example: create a new eventfd filehandle:
2241
2242 $fh = IO::AIO::eventfd 0, IO::AIO::O_CLOEXEC
2243 or die "eventfd: $!\n";
2244
2245=item $fh = IO::AIO::timerfd_create $clockid[, $flags]
2246
2247This is a direct interface to the Linux L<timerfd_create(2)> system call. The
2248(unhelpful) default for C<$flags> is C<0>.
2249
2250On success, the new timerfd filehandle is returned, otherwise returns
2251C<undef>. If the eventfd syscall is missing, fails with C<ENOSYS>.
2252
2253Please refer to L<timerfd_create(2)> for more info on this call.
2254
2255The following C<$clockid> values are
2256available: C<IO::AIO::CLOCK_REALTIME>, C<IO::AIO::CLOCK_MONOTONIC>
2257C<IO::AIO::CLOCK_CLOCK_BOOTTIME> (Linux 3.15)
2258C<IO::AIO::CLOCK_CLOCK_REALTIME_ALARM> (Linux 3.11) and
2259C<IO::AIO::CLOCK_CLOCK_BOOTTIME_ALARM> (Linux 3.11).
2260
2261The following C<$flags> values are available (Linux
22622.6.27): C<IO::AIO::TFD_NONBLOCK> and C<IO::AIO::TFD_CLOEXEC>.
2263
2264Example: create a new timerfd and set it to one-second repeated alarms,
2265then wait for two alarms:
2266
2267 my $fh = IO::AIO::timerfd_create IO::AIO::CLOCK_BOOTTIME, IO::AIO::TFD_CLOEXEC
2268 or die "timerfd_create: $!\n";
2269
2270 defined IO::AIO::timerfd_settime $fh, 0, 1, 1
2271 or die "timerfd_settime: $!\n";
2272
2273 for (1..2) {
2274 8 == sysread $fh, my $buf, 8
2275 or die "timerfd read failure\n";
2276
2277 printf "number of expirations (likely 1): %d\n",
2278 unpack "Q", $buf;
2279 }
2280
2281=item ($cur_interval, $cur_value) = IO::AIO::timerfd_settime $fh, $flags, $new_interval, $nbw_value
2282
2283This is a direct interface to the Linux L<timerfd_settime(2)> system
2284call. Please refer to its manpage for more info on this call.
2285
2286The new itimerspec is specified using two (possibly fractional) second
2287values, C<$new_interval> and C<$new_value>).
2288
2289On success, the current interval and value are returned (as per
2290C<timerfd_gettime>). On failure, the empty list is returned.
2291
2292The following C<$flags> values are
2293available: C<IO::AIO::TFD_TIMER_ABSTIME> and
2294C<IO::AIO::TFD_TIMER_CANCEL_ON_SET>.
2295
2296See C<IO::AIO::timerfd_create> for a full example.
2297
2298=item ($cur_interval, $cur_value) = IO::AIO::timerfd_gettime $fh
2299
2300This is a direct interface to the Linux L<timerfd_gettime(2)> system
2301call. Please refer to its manpage for more info on this call.
2302
2303On success, returns the current values of interval and value for the given
2304timerfd (as potentially fractional second values). On failure, the empty
2305list is returned.
2306
2273=back 2307=back
2274 2308
2275=cut 2309=cut
2276 2310
2277min_parallel 8; 2311min_parallel 8;
… …
2342the process will result in undefined behaviour. Calling it at any time 2376the process will result in undefined behaviour. Calling it at any time
2343will also result in any undefined (by POSIX) behaviour. 2377will also result in any undefined (by POSIX) behaviour.
2344 2378
2345=back 2379=back
2346 2380
2381=head2 LINUX-SPECIFIC CALLS
2382
2383When a call is documented as "linux-specific" then this means it
2384originated on GNU/Linux. C<IO::AIO> will usually try to autodetect the
2385availability and compatibility of such calls regardless of the platform
2386it is compiled on, so platforms such as FreeBSD which often implement
2387these calls will work. When in doubt, call them and see if they fail wth
2388C<ENOSYS>.
2389
2347=head2 MEMORY USAGE 2390=head2 MEMORY USAGE
2348 2391
2349Per-request usage: 2392Per-request usage:
2350 2393
2351Each aio request uses - depending on your architecture - around 100-200 2394Each aio request uses - depending on your architecture - around 100-200
… …
2363temporary buffers, and each thread requires a stack and other data 2406temporary buffers, and each thread requires a stack and other data
2364structures (usually around 16k-128k, depending on the OS). 2407structures (usually around 16k-128k, depending on the OS).
2365 2408
2366=head1 KNOWN BUGS 2409=head1 KNOWN BUGS
2367 2410
2368Known bugs will be fixed in the next release. 2411Known bugs will be fixed in the next release :)
2412
2413=head1 KNOWN ISSUES
2414
2415Calls that try to "import" foreign memory areas (such as C<IO::AIO::mmap>
2416or C<IO::AIO::aio_slurp>) do not work with generic lvalues, such as
2417non-created hash slots or other scalars I didn't think of. It's best to
2418avoid such and either use scalar variables or making sure that the scalar
2419exists (e.g. by storing C<undef>) and isn't "funny" (e.g. tied).
2420
2421I am not sure anything can be done about this, so this is considered a
2422known issue, rather than a bug.
2369 2423
2370=head1 SEE ALSO 2424=head1 SEE ALSO
2371 2425
2372L<AnyEvent::AIO> for easy integration into event loops, L<Coro::AIO> for a 2426L<AnyEvent::AIO> for easy integration into event loops, L<Coro::AIO> for a
2373more natural syntax. 2427more natural syntax.

Diff Legend

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