view release on metacpan or  search on metacpan

README  view on Meta::CPAN

        If an error occurs, the callback receives no arguments. The special
        "errno" value "IO::AIO::EBADR" is available to test for flag errors.

        Otherwise, the callback receives an array reference with extent
        structures. Each extent structure is an array reference itself, with
        the following members:

           [$logical, $physical, $length, $flags]

        Flags is any combination of the following flag values (typically
        either 0 or "IO::AIO::FIEMAP_EXTENT_LAST" (1)):

        "IO::AIO::FIEMAP_EXTENT_LAST", "IO::AIO::FIEMAP_EXTENT_UNKNOWN",
        "IO::AIO::FIEMAP_EXTENT_DELALLOC", "IO::AIO::FIEMAP_EXTENT_ENCODED",
        "IO::AIO::FIEMAP_EXTENT_DATA_ENCRYPTED",
        "IO::AIO::FIEMAP_EXTENT_NOT_ALIGNED",
        "IO::AIO::FIEMAP_EXTENT_DATA_INLINE",
        "IO::AIO::FIEMAP_EXTENT_DATA_TAIL",
        "IO::AIO::FIEMAP_EXTENT_UNWRITTEN", "IO::AIO::FIEMAP_EXTENT_MERGED"
        or "IO::AIO::FIEMAP_EXTENT_SHARED".

        At the time of this writing (Linux 3.2), this request is unreliable
        unless $count is "undef", as the kernel has all sorts of bugs
        preventing it to return all extents of a range for files with a
        large number of extents. The code (only) works around all these
        issues if $count is "undef".

    aio_group $callback->(...)
        This is a very special aio request: Instead of doing something, it
        is a container for other aio requests, which is useful if you want
        to bundle many requests into a single, composite, request with a
        definite callback and the ability to cancel the whole request with
        its subrequests.

        Returns an object of class IO::AIO::GRP. See its documentation below
        for more info.

        Example:

           my $grp = aio_group sub {
              print "all stats done\n";
           };

           add $grp
              (aio_stat ...),
              (aio_stat ...),
              ...;

    aio_nop $callback->()
        This is a special request - it does nothing in itself and is only
        used for side effects, such as when you want to add a dummy request
        to a group so that finishing the requests in the group depends on
        executing the given code.

        While this request does nothing, it still goes through the execution
        phase and still requires a worker thread. Thus, the callback will
        not be executed immediately but only after other requests in the
        queue have entered their execution phase. This can be used to
        measure request latency.

    IO::AIO::aio_busy $fractional_seconds, $callback->() *NOT EXPORTED*
        Mainly used for debugging and benchmarking, this aio request puts
        one of the request workers to sleep for the given time.

        While it is theoretically handy to have simple I/O scheduling
        requests like sleep and file handle readable/writable, the overhead
        this creates is immense (it blocks a thread for a long time) so do
        not use this function except to put your application under
        artificial I/O pressure.

  IO::AIO::WD - multiple working directories
    Your process only has one current working directory, which is used by
    all threads. This makes it hard to use relative paths (some other
    component could call "chdir" at any time, and it is hard to control when
    the path will be used by IO::AIO).

    One solution for this is to always use absolute paths. This usually
    works, but can be quite slow (the kernel has to walk the whole path on
    every access), and can also be a hassle to implement.

    Newer POSIX systems have a number of functions (openat, fdopendir,
    futimensat and so on) that make it possible to specify working
    directories per operation.

    For portability, and because the clowns who "designed", or shall I
    write, perpetrated this new interface were obviously half-drunk, this
    abstraction cannot be perfect, though.

    IO::AIO allows you to convert directory paths into a so-called
    IO::AIO::WD object. This object stores the canonicalised, absolute
    version of the path, and on systems that allow it, also a directory file
    descriptor.

    Everywhere where a pathname is accepted by IO::AIO (e.g. in "aio_stat"
    or "aio_unlink"), one can specify an array reference with an IO::AIO::WD
    object and a pathname instead (or the IO::AIO::WD object alone, which
    gets interpreted as "[$wd, "."]"). If the pathname is absolute, the
    IO::AIO::WD object is ignored, otherwise the pathname is resolved
    relative to that IO::AIO::WD object.

    For example, to get a wd object for /etc and then stat passwd inside,
    you would write:

       aio_wd "/etc", sub {
          my $etcdir = shift;

          # although $etcdir can be undef on error, there is generally no reason
          # to check for errors here, as aio_stat will fail with ENOENT
          # when $etcdir is undef.

          aio_stat [$etcdir, "passwd"], sub {
             # yay
          };
       };

    The fact that "aio_wd" is a request and not a normal function shows that
    creating an IO::AIO::WD object is itself a potentially blocking
    operation, which is why it is done asynchronously.

    To stat the directory obtained with "aio_wd" above, one could write
    either of the following three request calls: