[ViewVC] Diff of: cvs/IO-AIO/AIO.pm

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.278 by root, Sun Oct 1 07:24:34 2017 UTC vs.
Revision 1.283 by root, Tue Feb 20 06:05:19 2018 UTC

 use common::sense;
 use base 'Exporter';
 BEGIN {
-   our $VERSION = 4.35;
+   our $VERSION = 4.4;
    our @AIO_REQ = qw(aio_sendfile aio_seek aio_read aio_write aio_open aio_close
                      aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx
                      aio_scandir aio_symlink aio_readlink aio_realpath aio_fcntl aio_ioctl
                      aio_sync aio_fsync aio_syncfs aio_fdatasync aio_sync_file_range
                      aio_rename aio_rename2 aio_link aio_move aio_copy aio_group
                      aio_nop aio_mknod aio_load aio_rmtree aio_mkdir aio_chown
                      aio_chmod aio_utime aio_truncate
                      aio_msync aio_mtouch aio_mlock aio_mlockall
                      aio_statvfs
+                     aio_slurp
                      aio_wd);
    our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice));
    our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush
                        min_parallel max_parallel max_idle idle_timeout
       namemax => 255,
       frsize  => 1024,
       fsid    => 1810
    }
-Here is a (likely partial - send me updates!) list of fsid values used by
-Linux - it is safe to hardcode these when C<$^O> is C<linux>:
-   0x0000adf5 adfs
-   0x0000adff affs
-   0x5346414f afs
-   0x09041934 anon-inode filesystem
-   0x00000187 autofs
-   0x42465331 befs
-   0x1badface bfs
-   0x42494e4d binfmt_misc
-   0x9123683e btrfs
-   0x0027e0eb cgroupfs
-   0xff534d42 cifs
-   0x73757245 coda
-   0x012ff7b7 coh
-   0x28cd3d45 cramfs
-   0x453dcd28 cramfs-wend (wrong endianness)
-   0x64626720 debugfs
-   0x00001373 devfs
-   0x00001cd1 devpts
-   0x0000f15f ecryptfs
-   0x00414a53 efs
-   0x0000137d ext
-   0x0000ef53 ext2/ext3/ext4
-   0x0000ef51 ext2
-   0xf2f52010 f2fs
-   0x00004006 fat
-   0x65735546 fuseblk
-   0x65735543 fusectl
-   0x0bad1dea futexfs
-   0x01161970 gfs2
-   0x47504653 gpfs
-   0x00004244 hfs
-   0xf995e849 hpfs
-   0x00c0ffee hostfs
-   0x958458f6 hugetlbfs
-   0x2bad1dea inotifyfs
-   0x00009660 isofs
-   0x000072b6 jffs2
-   0x3153464a jfs
-   0x6b414653 k-afs
-   0x0bd00bd0 lustre
-   0x0000137f minix
-   0x0000138f minix 30 char names
-   0x00002468 minix v2
-   0x00002478 minix v2 30 char names
-   0x00004d5a minix v3
-   0x19800202 mqueue
-   0x00004d44 msdos
-   0x0000564c novell
-   0x00006969 nfs
-   0x6e667364 nfsd
-   0x00003434 nilfs
-   0x5346544e ntfs
-   0x00009fa1 openprom
-   0x7461636F ocfs2
-   0x00009fa0 proc
-   0x6165676c pstorefs
-   0x0000002f qnx4
-   0x68191122 qnx6
-   0x858458f6 ramfs
-   0x52654973 reiserfs
-   0x00007275 romfs
-   0x67596969 rpc_pipefs
-   0x73636673 securityfs
-   0xf97cff8c selinux
-   0x0000517b smb
-   0x534f434b sockfs
-   0x73717368 squashfs
-   0x62656572 sysfs
-   0x012ff7b6 sysv2
-   0x012ff7b5 sysv4
-   0x01021994 tmpfs
-   0x15013346 udf
-   0x00011954 ufs
-   0x54190100 ufs byteswapped
-   0x00009fa2 usbdevfs
-   0x01021997 v9fs
-   0xa501fcf5 vxfs
-   0xabba1974 xenfs
-   0x012ff7b4 xenix
-   0x58465342 xfs
-   0x012fd16d xia
 =item aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
 Works like perl's C<utime> function (including the special case of $atime
 and $mtime being undef). Fractional times are supported if the underlying
 syscalls support them.
 C<$type>'s are known, which can be used to speed up some algorithms.
 =back
+=item aio_slurp $pathname, $offset, $length, $data, $callback->($status)
+Opens, reads and closes the given file. The data is put into C<$data>,
+which is resized as required.
+If C<$offset> is negative, then it is counted from the end of the file.
+If C<$length> is zero, then the remaining length of the file is
+used. Also, in this case, the same limitations to modifying C<$data> apply
+as when IO::AIO::mmap is used, i.e. it must only be modified in-place
+with C<substr>. If the size of the file is known, specifying a non-zero
+C<$length> results in a performance advantage.
+This request is similar to the older C<aio_load> request, but since it is
+a single request, it might be more efficient to use.
+Example: load F</etc/passwd> into C<$passwd>.
+   my $passwd;
+   aio_slurp "/etc/passwd", 0, 0, $passwd, sub {
+      $_[0] >= 0
+         or die "/etc/passwd: $!\n";
+      printf "/etc/passwd is %d bytes long, and contains:\n", length $passwd;
+      print $passwd;
+   };
+   IO::AIO::flush;
 =item aio_load $pathname, $data, $callback->($status)
 This is a composite request that tries to fully load the given file into
 memory. Status is the same as with aio_read.
+Using C<aio_slurp> might be more efficient, as it is a single request.
 =cut
 sub aio_load($$;$) {
    my ($path, undef, $cb) = @_;
 Please refer to L<pipe2(2)> for more info on the C<$flags>, but at the
 time of this writing, C<IO::AIO::O_CLOEXEC>, C<IO::AIO::O_NONBLOCK> and
 C<IO::AIO::O_DIRECT> (Linux 3.4, for packet-based pipes) were supported.
+Example: create a pipe race-free w.r.t. threads and fork:
+   my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC
+      or die "pipe2: $!\n";
+=item $fh = IO::AIO::eventfd [$initval, [$flags]]
+This is a direct interface to the Linux L<eventfd(2)> system call. The
+(unhelpful) defaults for C<$initval> and C<$flags> are C<0> for both.
+On success, the new eventfd filehandle is returned, otherwise returns
+C<undef>. If the eventfd syscall is missing, fails with C<ENOSYS>.
+Please refer to L<eventfd(2)> for more info on this call.
+The following symbol flag values are available: C<IO::AIO::EFD_CLOEXEC>,
+C<IO::AIO::EFD_NONBLOCK> and C<IO::AIO::EFD_SEMAPHORE> (Linux 2.6.30).
+Example: create a new eventfd filehandle:
+   $fh = IO::AIO::eventfd 0, IO::AIO::O_CLOEXEC
+      or die "eventfd: $!\n";
+=item $fh = IO::AIO::timerfd_create $clockid[, $flags]
+This is a direct interface to the Linux L<timerfd_create(2)> system call. The
+(unhelpful) default for C<$flags> is C<0>.
+On success, the new timerfd filehandle is returned, otherwise returns
+C<undef>. If the eventfd syscall is missing, fails with C<ENOSYS>.
+Please refer to L<timerfd_create(2)> for more info on this call.
+The following C<$clockid> values are
+available: C<IO::AIO::CLOCK_REALTIME>, C<IO::AIO::CLOCK_MONOTONIC>
+C<IO::AIO::CLOCK_CLOCK_BOOTTIME> (Linux 3.15)
+C<IO::AIO::CLOCK_CLOCK_REALTIME_ALARM> (Linux 3.11) and
+C<IO::AIO::CLOCK_CLOCK_BOOTTIME_ALARM> (Linux 3.11).
+The following C<$flags> values are available (Linux
+2.6.27): C<IO::AIO::TFD_NONBLOCK> and C<IO::AIO::TFD_CLOEXEC>.
+Example: create a new timerfd and set it to one-second repeated alarms,
+then wait for two alarms:
+   my $fh = IO::AIO::timerfd_create IO::AIO::CLOCK_BOOTTIME, IO::AIO::TFD_CLOEXEC
+      or die "timerfd_create: $!\n";
+   defined IO::AIO::timerfd_settime $fh, 0, 1, 1
+      or die "timerfd_settime: $!\n";
+   for (1..2) {
+      8 == sysread $fh, my $buf, 8
+         or die "timerfd read failure\n";
+      printf "number of expirations (likely 1): %d\n",
+         unpack "Q", $buf;
+   }
+=item ($cur_interval, $cur_value) = IO::AIO::timerfd_settime $fh, $flags, $new_interval, $nbw_value
+This is a direct interface to the Linux L<timerfd_settime(2)> system
+call. Please refer to its manpage for more info on this call.
+The new itimerspec is specified using two (possibly fractional) second
+values, C<$new_interval> and C<$new_value>).
+On success, the current interval and value are returned (as per
+C<timerfd_gettime>). On failure, the empty list is returned.
+The following C<$flags> values are
+available: C<IO::AIO::TFD_TIMER_ABSTIME> and
+C<IO::AIO::TFD_TIMER_CANCEL_ON_SET>.
+See C<IO::AIO::timerfd_create> for a full example.
+=item ($cur_interval, $cur_value) = IO::AIO::timerfd_gettime $fh
+This is a direct interface to the Linux L<timerfd_gettime(2)> system
+call. Please refer to its manpage for more info on this call.
+On success, returns the current values of interval and value for the given
+timerfd (as potentially fractional second values). On failure, the empty
+list is returned.
 =back
 =cut
 min_parallel 8;
 the process will result in undefined behaviour. Calling it at any time
 will also result in any undefined (by POSIX) behaviour.
 =back
+=head2 LINUX-SPECIFIC CALLS
+When a call is documented as "linux-specific" then this means it
+originated on GNU/Linux. C<IO::AIO> will usually try to autodetect the
+availability and compatibility of such calls regardless of the platform
+it is compiled on, so platforms such as FreeBSD which often implement
+these calls will work. When in doubt, call them and see if they fail wth
+C<ENOSYS>.
 =head2 MEMORY USAGE
 Per-request usage:
 Each aio request uses - depending on your architecture - around 100-200
 temporary buffers, and each thread requires a stack and other data
 structures (usually around 16k-128k, depending on the OS).
 =head1 KNOWN BUGS
-Known bugs will be fixed in the next release.
+Known bugs will be fixed in the next release :)
+=head1 KNOWN ISSUES
+Calls that try to "import" foreign memory areas (such as C<IO::AIO::mmap>
+or C<IO::AIO::aio_slurp>) do not work with generic lvalues, such as
+non-created hash slots or other scalars I didn't think of. It's best to
+avoid such and either use scalar variables or making sure that the scalar
+exists (e.g. by storing C<undef>) and isn't "funny" (e.g. tied).
+I am not sure anything can be done about this, so this is considered a
+known issue, rather than a bug.
 =head1 SEE ALSO
 L<AnyEvent::AIO> for easy integration into event loops, L<Coro::AIO> for a
 more natural syntax.

Diff Legend

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

Comparing IO-AIO/AIO.pm (file contents): Revision 1.278 by root, Sun Oct 1 07:24:34 2017 UTC vs. Revision 1.283 by root, Tue Feb 20 06:05:19 2018 UTC

Diff Legend

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.278 by root, Sun Oct 1 07:24:34 2017 UTC vs.
Revision 1.283 by root, Tue Feb 20 06:05:19 2018 UTC