Filewatcher File Search File Search
Catalog
Content Search
» » » » » » perl-IO-AIO-2.33-1.el4.i386.rpm » Content »
pkg://perl-IO-AIO-2.33-1.el4.i386.rpm:78052/usr/share/man/man3/  info  HEADER  downloads

perl-IO-AIO - Asynchronous Input/Output…  more info»

IO::AIO.3pm.gz

AIO(3)           User Contributed Perl Documentation          AIO(3)



NAME
       IO::AIO - Asynchronous Input/Output

SYNOPSIS
        use IO::AIO;

        aio_open "/etc/passwd", O_RDONLY, 0, sub {
           my $fh = shift
              or die "/etc/passwd: $!";
           ...
        };

        aio_unlink "/tmp/file", sub { };

        aio_read $fh, 30000, 1024, $buffer, 0, sub {
           $_[0] > 0 or die "read error: $!";
        };

        # version 2+ has request and group objects
        use IO::AIO 2;

        aioreq_pri 4; # give next request a very high priority
        my $req = aio_unlink "/tmp/file", sub { };
        $req->cancel; # cancel request if still in queue

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

        # AnyEvent integration
        open my $fh, "<&=" . IO::AIO::poll_fileno or die "$!";
        my $w = AnyEvent->io (fh => $fh, poll => 'r', cb => sub { IO::AIO::poll_cb });

        # Event integration
        Event->io (fd => IO::AIO::poll_fileno,
                   poll => 'r',
                   cb => \&IO::AIO::poll_cb);

        # Glib/Gtk2 integration
        add_watch Glib::IO IO::AIO::poll_fileno,
                  in => sub { IO::AIO::poll_cb; 1 };

        # Tk integration
        Tk::Event::IO->fileevent (IO::AIO::poll_fileno, "",
                                  readable => \&IO::AIO::poll_cb);

        # Danga::Socket integration
        Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>
                                    \&IO::AIO::poll_cb);

DESCRIPTION
       This module implements asynchronous I/O using whatever means
       your operating system supports.

       Asynchronous means that operations that can normally block
       your program (e.g. reading from disk) will be done asyn‐
       chronously: the operation will still block, but you can do
       something else in the meantime. This is extremely useful for
       programs that need to stay interactive even when doing heavy
       I/O (GUI programs, high performance network servers etc.),
       but can also be used to easily do operations in parallel that
       are normally done sequentially, e.g. stat'ing many files,
       which is much faster on a RAID volume or over NFS when you do
       a number of stat operations concurrently.

       While most of this works on all types of file descriptors
       (for example sockets), using these functions on file descrip‐
       tors that support nonblocking operation (again, sockets,
       pipes etc.) is very inefficient or might not work (aio_read
       fails on sockets/pipes/fifos). Use an event loop for that
       (such as the Event module): IO::AIO will naturally fit into
       such an event loop itself.

       In this version, a number of threads are started that execute
       your requests and signal their completion. You don't need
       thread support in perl, and the threads created by this mod‐
       ule will not be visible to perl. In the future, this module
       might make use of the native aio functions available on many
       operating systems. However, they are often not well-supported
       or restricted (GNU/Linux doesn't allow them on normal files
       currently, for example), and they would only support aio_read
       and aio_write, so the remaining functionality would have to
       be implemented using threads anyway.

       Although the module will work with in the presence of other
       (Perl-) threads, it is currently not reentrant in any way, so
       use appropriate locking yourself, always call "poll_cb" from
       within the same thread, or never call "poll_cb" (or other
       "aio_" functions) recursively.

       EXAMPLE

       This is a simple example that uses the Event module and loads
       /etc/passwd asynchronously:

          use Fcntl;
          use Event;
          use IO::AIO;

          # register the IO::AIO callback with Event
          Event->io (fd => IO::AIO::poll_fileno,
                     poll => 'r',
                     cb => \&IO::AIO::poll_cb);

          # queue the request to open /etc/passwd
          aio_open "/etc/passwd", O_RDONLY, 0, sub {
             my $fh = shift
                or die "error while opening: $!";

             # stat'ing filehandles is generally non-blocking
             my $size = -s $fh;

             # queue a request to read the file
             my $contents;
             aio_read $fh, 0, $size, $contents, 0, sub {
                $_[0] == $size
                   or die "short read: $!";

                close $fh;

                # file contents now in $contents
                print $contents;

                # exit event loop and program
                Event::unloop;
             };
          };

          # possibly queue up other requests, or open GUI windows,
          # check for sockets etc. etc.

          # process events as long as there are some:
          Event::loop;

REQUEST ANATOMY AND LIFETIME
       Every "aio_*" function creates a request. which is a C data
       structure not directly visible to Perl.

       If called in non-void context, every request function returns
       a Perl object representing the request. In void context,
       nothing is returned, which saves a bit of memory.

       The perl object is a fairly standard ref-to-hash object. The
       hash contents are not used by IO::AIO so you are free to
       store anything you like in it.

       During their existance, aio requests travel through the fol‐
       lowing states, in order:

       ready
           Immediately after a request is created it is put into the
           ready state, waiting for a thread to execute it.

       execute
           A thread has accepted the request for processing and is
           currently executing it (e.g. blocking in read).

       pending
           The request has been executed and is waiting for result
           processing.

           While request submission and execution is fully asynchro‐
           nous, result processing is not and relies on the perl
           interpreter calling "poll_cb" (or another function with
           the same effect).

       result
           The request results are processed synchronously by
           "poll_cb".

           The "poll_cb" function will process all outstanding aio
           requests by calling their callbacks, freeing memory asso‐
           ciated with them and managing any groups they are con‐
           tained in.

       done
           Request has reached the end of its lifetime and holds no
           resources anymore (except possibly for the Perl object,
           but its connection to the actual aio request is severed
           and calling its methods will either do nothing or result
           in a runtime error).

FUNCTIONS
       AIO REQUEST FUNCTIONS

       All the "aio_*" calls are more or less thin wrappers around
       the syscall with the same name (sans "aio_"). The arguments
       are similar or identical, and they all accept an additional
       (and optional) $callback argument which must be a code refer‐
       ence. This code reference will get called with the syscall
       return code (e.g. most syscalls return "-1" on error, unlike
       perl, which usually delivers "false") as it's sole argument
       when the given syscall has been executed asynchronously.

       All functions expecting a filehandle keep a copy of the file‐
       handle internally until the request has finished.

       All functions return request objects of type IO::AIO::REQ
       that allow further manipulation of those requests while they
       are in-flight.

       The pathnames you pass to these routines must be absolute and
       encoded as octets. The reason for the former is that at the
       time the request is being executed, the current working
       directory could have changed. Alternatively, you can make
       sure that you never change the current working directory any‐
       where in the program and then use relative paths.

       To encode pathnames as octets, either make sure you either:
       a) always pass in filenames you got from outside (command
       line, readdir etc.) without tinkering, b) are ASCII or ISO
       8859-1, c) use the Encode module and encode your pathnames to
       the locale (or other) encoding in effect in the user environ‐
       ment, d) use Glib::filename_from_unicode on unicode filenames
       or e) use something else to ensure your scalar has the cor‐
       rect contents.

       This works, btw. independent of the internal UTF-8 bit, which
       IO::AIO handles correctly wether it is set or not.

       $prev_pri = aioreq_pri [$pri]
           Returns the priority value that would be used for the
           next request and, if $pri is given, sets the priority for
           the next aio request.

           The default priority is 0, the minimum and maximum prior‐
           ities are "-4" and 4, respectively. Requests with higher
           priority will be serviced first.

           The priority will be reset to 0 after each call to one of
           the "aio_*" functions.

           Example: open a file with low priority, then read some‐
           thing from it with higher priority so the read request is
           serviced before other low priority open requests (poten‐
           tially spamming the cache):

              aioreq_pri -3;
              aio_open ..., sub {
                 return unless $_[0];

                 aioreq_pri -2;
                 aio_read $_[0], ..., sub {
                    ...
                 };
              };

       aioreq_nice $pri_adjust
           Similar to "aioreq_pri", but subtracts the given value
           from the current priority, so the effect is cumulative.

       aio_open $pathname, $flags, $mode, $callback->($fh)
           Asynchronously open or create a file and call the call‐
           back with a newly created filehandle for the file.

           The pathname passed to "aio_open" must be absolute. See
           API NOTES, above, for an explanation.

           The $flags argument is a bitmask. See the "Fcntl" module
           for a list. They are the same as used by "sysopen".

           Likewise, $mode specifies the mode of the newly created
           file, if it didn't exist and "O_CREAT" has been given,
           just like perl's "sysopen", except that it is mandatory
           (i.e. use 0 if you don't create new files, and 0666 or
           0777 if you do). Note that the $mode will be modified by
           the umask in effect then the request is being executed,
           so better never change the umask.

           Example:

              aio_open "/etc/passwd", O_RDONLY, 0, sub {
                 if ($_[0]) {
                    print "open successful, fh is $_[0]\n";
                    ...
                 } else {
                    die "open failed: $!\n";
                 }
              };

       aio_close $fh, $callback->($status)
           Asynchronously close a file and call the callback with
           the result code. WARNING: although accepted, you should
           not pass in a perl filehandle here, as perl will likely
           close the file descriptor another time when the filehan‐
           dle is destroyed. Normally, you can safely call perls
           "close" or just let filehandles go out of scope.

           This is supposed to be a bug in the API, so that might
           change. It's therefore best to avoid this function.

       aio_read  $fh,$offset,$length, $data,$dataoffset, $call‐
       back->($retval)
       aio_write $fh,$offset,$length, $data,$dataoffset, $call‐
       back->($retval)
           Reads or writes "length" bytes from the specified "fh"
           and "offset" into the scalar given by "data" and offset
           "dataoffset" and calls the callback without the actual
           number of bytes read (or -1 on error, just like the
           syscall).

           The $data scalar MUST NOT be modified in any way while
           the request is outstanding. Modifying it can result in
           segfaults or WW3 (if the necessary/optional hardware is
           installed).

           Example: Read 15 bytes at offset 7 into scalar $buffer,
           starting at offset 0 within the scalar:

              aio_read $fh, 7, 15, $buffer, 0, sub {
                 $_[0] > 0 or die "read error: $!";
                 print "read $_[0] bytes: <$buffer>\n";
              };

       aio_sendfile $out_fh, $in_fh, $in_offset, $length, $call‐
       back->($retval)
           Tries to copy $length bytes from $in_fh to $out_fh. It
           starts reading at byte offset $in_offset, and starts
           writing at the current file offset of $out_fh. Because of
           that, it is not safe to issue more than one "aio_send‐
           file" per $out_fh, as they will interfere with each
           other.

           This call tries to make use of a native "sendfile"
           syscall to provide zero-copy operation. For this to work,
           $out_fh should refer to a socket, and $in_fh should refer
           to mmap'able file.

           If the native sendfile call fails or is not implemented,
           it will be emulated, so you can call "aio_sendfile" on
           any type of filehandle regardless of the limitations of
           the operating system.

           Please note, however, that "aio_sendfile" can read more
           bytes from $in_fh than are written, and there is no way
           to find out how many bytes have been read from "aio_send‐
           file" alone, as "aio_sendfile" only provides the number
           of bytes written to $out_fh. Only if the result value
           equals $length one can assume that $length bytes have
           been read.

       aio_readahead $fh,$offset,$length, $callback->($retval)
           "aio_readahead" populates the page cache with data from a
           file so that subsequent reads from that file will not
           block on disk I/O. The $offset argument specifies the
           starting point from which data is to be read and $length
           specifies the number of bytes to be read. I/O is per‐
           formed in whole pages, so that offset is effectively
           rounded down to a page boundary and bytes are read up to
           the next page boundary greater than or equal to
           (off-set+length). "aio_readahead" does not read beyond
           the end of the file. The current file offset of the file
           is left unchanged.

           If that syscall doesn't exist (likely if your OS isn't
           Linux) it will be emulated by simply reading the data,
           which would have a similar effect.

       aio_stat  $fh_or_path, $callback->($status)
       aio_lstat $fh, $callback->($status)
           Works like perl's "stat" or "lstat" in void context. The
           callback will be called after the stat and the results
           will be available using "stat _" or "-s _" etc...

           The pathname passed to "aio_stat" must be absolute. See
           API NOTES, above, for an explanation.

           Currently, the stats are always 64-bit-stats, i.e.
           instead of returning an error when stat'ing a large file,
           the results will be silently truncated unless perl itself
           is compiled with large file support.

           Example: Print the length of /etc/passwd:

              aio_stat "/etc/passwd", sub {
                 $_[0] and die "stat failed: $!";
                 print "size is ", -s _, "\n";
              };

       aio_unlink $pathname, $callback->($status)
           Asynchronously unlink (delete) a file and call the call‐
           back with the result code.

       aio_mknod $path, $mode, $dev, $callback->($status)
           [EXPERIMENTAL]

           Asynchronously create a device node (or fifo). See
           mknod(2).

           The only (POSIX-) portable way of calling this function
           is:

              aio_mknod $path, IO::AIO::S_IFIFO ⎪ $mode, 0, sub { ...

       aio_link $srcpath, $dstpath, $callback->($status)
           Asynchronously create a new link to the existing object
           at $srcpath at the path $dstpath and call the callback
           with the result code.

       aio_symlink $srcpath, $dstpath, $callback->($status)
           Asynchronously create a new symbolic link to the existing
           object at $srcpath at the path $dstpath and call the
           callback with the result code.

       aio_readlink $path, $callback->($link)
           Asynchronously read the symlink specified by $path and
           pass it to the callback. If an error occurs, nothing or
           undef gets passed to the callback.

       aio_rename $srcpath, $dstpath, $callback->($status)
           Asynchronously rename the object at $srcpath to $dstpath,
           just as rename(2) and call the callback with the result
           code.

       aio_mkdir $pathname, $mode, $callback->($status)
           Asynchronously mkdir (create) a directory and call the
           callback with the result code. $mode will be modified by
           the umask at the time the request is executed, so do not
           change your umask.

       aio_rmdir $pathname, $callback->($status)
           Asynchronously rmdir (delete) a directory and call the
           callback with the result code.

       aio_readdir $pathname, $callback->($entries)
           Unlike the POSIX call of the same name, "aio_readdir"
           reads an entire directory (i.e. opendir + readdir +
           closedir). The entries will not be sorted, and will NOT
           include the "." and ".." entries.

           The callback a single argument which is either "undef" or
           an array-ref with the filenames.

       aio_load $path, $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.

       aio_copy $srcpath, $dstpath, $callback->($status)
           Try to copy the file (directories not supported as either
           source or destination) from $srcpath to $dstpath and call
           the callback with the 0 (error) or "-1" ok.

           This is a composite request that it creates the destina‐
           tion file with mode 0200 and copies the contents of the
           source file into it using "aio_sendfile", followed by
           restoring atime, mtime, access mode and uid/gid, in that
           order.

           If an error occurs, the partial destination file will be
           unlinked, if possible, except when setting atime, mtime,
           access mode and uid/gid, where errors are being ignored.

       aio_move $srcpath, $dstpath, $callback->($status)
           Try to move the file (directories not supported as either
           source or destination) from $srcpath to $dstpath and call
           the callback with the 0 (error) or "-1" ok.

           This is a composite request that tries to rename(2) the
           file first. If rename files with "EXDEV", it copies the
           file with "aio_copy" and, if that is successful, unlink‐
           ing the $srcpath.

       aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)
           Scans a directory (similar to "aio_readdir") but addi‐
           tionally tries to efficiently separate the entries of
           directory $path into two sets of names, directories you
           can recurse into (directories), and ones you cannot
           recurse into (everything else, including symlinks to
           directories).

           "aio_scandir" is a composite request that creates of many
           sub requests_ $maxreq specifies the maximum number of
           outstanding aio requests that this function generates. If
           it is "<= 0", then a suitable default will be chosen
           (currently 4).

           On error, the callback is called without arguments, oth‐
           erwise it receives two array-refs with path-relative
           entry names.

           Example:

              aio_scandir $dir, 0, sub {
                 my ($dirs, $nondirs) = @_;
                 print "real directories: @$dirs\n";
                 print "everything else: @$nondirs\n";
              };

           Implementation notes.

           The "aio_readdir" cannot be avoided, but "stat()"'ing
           every entry can.

           After reading the directory, the modification time, size
           etc. of the directory before and after the readdir is
           checked, and if they match (and isn't the current time),
           the link count will be used to decide how many entries
           are directories (if >= 2). Otherwise, no knowledge of the
           number of subdirectories will be assumed.

           Then entries will be sorted into likely directories
           (everything without a non-initial dot currently) and
           likely non-directories (everything else). Then every
           entry plus an appended "/." will be "stat"'ed, likely
           directories first. If that succeeds, it assumes that the
           entry is a directory or a symlink to directory (which
           will be checked seperately). This is often faster than
           stat'ing the entry itself because filesystems might
           detect the type of the entry without reading the inode
           data (e.g. ext2fs filetype feature).

           If the known number of directories (link count - 2) has
           been reached, the rest of the entries is assumed to be
           non-directories.

           This only works with certainty on POSIX (= UNIX) filesys‐
           tems, which fortunately are the vast majority of filesys‐
           tems around.

           It will also likely work on non-POSIX filesystems with
           reduced efficiency as those tend to return 0 or 1 as link
           counts, which disables the directory counting heuristic.

       aio_rmtree $path, $callback->($status)
           Delete a directory tree starting (and including) $path,
           return the status of the final "rmdir" only.  This is a
           composite request that uses "aio_scandir" to recurse into
           and rmdir directories, and unlink everything else.

       aio_fsync $fh, $callback->($status)
           Asynchronously call fsync on the given filehandle and
           call the callback with the fsync result code.

       aio_fdatasync $fh, $callback->($status)
           Asynchronously call fdatasync on the given filehandle and
           call the callback with the fdatasync result code.

           If this call isn't available because your OS lacks it or
           it couldn't be detected, it will be emulated by calling
           "fsync" instead.

       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 subre‐
           quests.

           Returns an object of class IO::AIO::GRP. See its documen‐
           tation 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 sched‐
           uling requests like sleep and file handle read‐
           able/writable, the overhead this creates is immense (it
           blocks a thread for a long time) so do not use this func‐
           tion except to put your application under artificial I/O
           pressure.

       IO::AIO::REQ CLASS

       All non-aggregate "aio_*" functions return an object of this
       class when called in non-void context.

       cancel $req
           Cancels the request, if possible. Has the effect of skip‐
           ping execution when entering the execute state and skip‐
           ping calling the callback when entering the the result
           state, but will leave the request otherwise untouched.
           That means that requests that currently execute will not
           be stopped and resources held by the request will not be
           freed prematurely.

       cb $req $callback->(...)
           Replace (or simply set) the callback registered to the
           request.

       IO::AIO::GRP CLASS

       This class is a subclass of IO::AIO::REQ, so all its methods
       apply to objects of this class, too.

       A IO::AIO::GRP object is a special request that can contain
       multiple other aio requests.

       You create one by calling the "aio_group" constructing func‐
       tion with a callback that will be called when all contained
       requests have entered the "done" state:

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

       You add requests by calling the "add" method with one or more
       "IO::AIO::REQ" objects:

          $grp->add (aio_unlink "...");

          add $grp aio_stat "...", sub {
             $_[0] or return $grp->result ("error");

             # add another request dynamically, if first succeeded
             add $grp aio_open "...", sub {
                $grp->result ("ok");
             };
          };

       This makes it very easy to create composite requests (see the
       source of "aio_move" for an application) that work and feel
       like simple requests.

       * The IO::AIO::GRP objects will be cleaned up during calls to
       "IO::AIO::poll_cb", just like any other request.
       * They can be canceled like any other request. Canceling will
       cancel not only the request itself, but also all requests it
       contains.
       * They can also can also be added to other IO::AIO::GRP
       objects.
       * You must not add requests to a group from within the group
       callback (or any later time).

       Their lifetime, simplified, looks like this: when they are
       empty, they will finish very quickly. If they contain only
       requests that are in the "done" state, they will also finish.
       Otherwise they will continue to exist.

       That means after creating a group you have some time to add
       requests. And in the callbacks of those requests, you can add
       further requests to the group. And only when all those
       requests have finished will the the group itself finish.

       add $grp ...
       $grp->add (...)
           Add one or more requests to the group. Any type of
           IO::AIO::REQ can be added, including other groups, as
           long as you do not create circular dependencies.

           Returns all its arguments.

       $grp->cancel_subs
           Cancel all subrequests and clears any feeder, but not the
           group request itself. Useful when you queued a lot of
           events but got a result early.

       $grp->result (...)
           Set the result value(s) that will be passed to the group
           callback when all subrequests have finished and set thre
           groups errno to the current value of errno (just like
           calling "errno" without an error number). By default, no
           argument will be passed and errno is zero.

       $grp->errno ([$errno])
           Sets the group errno value to $errno, or the current
           value of errno when the argument is missing.

           Every aio request has an associated errno value that is
           restored when the callback is invoked. This method lets
           you change this value from its default (0).

           Calling "result" will also set errno, so make sure you
           either set $!  before the call to "result", or call
           c<errno> after it.

       feed $grp $callback->($grp)
           Sets a feeder/generator on this group: every group can
           have an attached generator that generates requests if
           idle. The idea behind this is that, although you could
           just queue as many requests as you want in a group, this
           might starve other requests for a potentially long time.
           For example, "aio_scandir" might generate hundreds of
           thousands "aio_stat" requests, delaying any later
           requests for a long time.

           To avoid this, and allow incremental generation of
           requests, you can instead a group and set a feeder on it
           that generates those requests. The feed callback will be
           called whenever there are few enough (see "limit", below)
           requests active in the group itself and is expected to
           queue more requests.

           The feed callback can queue as many requests as it likes
           (i.e. "add" does not impose any limits).

           If the feed does not queue more requests when called, it
           will be automatically removed from the group.

           If the feed limit is 0, it will be set to 2 automati‐
           cally.

           Example:

              # stat all files in @files, but only ever use four aio requests concurrently:

              my $grp = aio_group sub { print "finished\n" };
              limit $grp 4;
              feed $grp sub {
                 my $file = pop @files
                    or return;

                 add $grp aio_stat $file, sub { ... };
              };

       limit $grp $num
           Sets the feeder limit for the group: The feeder will be
           called whenever the group contains less than this many
           requests.

           Setting the limit to 0 will pause the feeding process.

       SUPPORT FUNCTIONS

       EVENT PROCESSING AND EVENT LOOP INTEGRATION

       $fileno = IO::AIO::poll_fileno
           Return the request result pipe file descriptor. This
           filehandle must be polled for reading by some mechanism
           outside this module (e.g. Event or select, see below or
           the SYNOPSIS). If the pipe becomes readable you have to
           call "poll_cb" to check the results.

           See "poll_cb" for an example.

       IO::AIO::poll_cb
           Process some outstanding events on the result pipe. You
           have to call this regularly. Returns the number of events
           processed. Returns immediately when no events are out‐
           standing. The amount of events processed depends on the
           settings of "IO::AIO::max_poll_req" and
           "IO::AIO::max_poll_time".

           If not all requests were processed for whatever reason,
           the filehandle will still be ready when "poll_cb"
           returns.

           Example: Install an Event watcher that automatically
           calls IO::AIO::poll_cb with high priority:

              Event->io (fd => IO::AIO::poll_fileno,
                         poll => 'r', async => 1,
                         cb => \&IO::AIO::poll_cb);

       IO::AIO::max_poll_reqs $nreqs
       IO::AIO::max_poll_time $seconds
           These set the maximum number of requests (default 0,
           meaning infinity) that are being processed by
           "IO::AIO::poll_cb" in one call, respectively the maximum
           amount of time (default 0, meaning infinity) spent in
           "IO::AIO::poll_cb" to process requests (more correctly
           the mininum amount of time "poll_cb" is allowed to use).

           Setting "max_poll_time" to a non-zero value creates an
           overhead of one syscall per request processed, which is
           not normally a problem unless your callbacks are really
           really fast or your OS is really really slow (I am not
           mentioning Solaris here). Using "max_poll_reqs" incurs no
           overhead.

           Setting these is useful if you want to ensure some level
           of interactiveness when perl is not fast enough to
           process all requests in time.

           For interactive programs, values such as 0.01 to 0.1
           should be fine.

           Example: Install an Event watcher that automatically
           calls IO::AIO::poll_cb with low priority, to ensure that
           other parts of the program get the CPU sometimes even
           under high AIO load.

              # try not to spend much more than 0.1s in poll_cb
              IO::AIO::max_poll_time 0.1;

              # use a low priority so other tasks have priority
              Event->io (fd => IO::AIO::poll_fileno,
                         poll => 'r', nice => 1,
                         cb => &IO::AIO::poll_cb);

       IO::AIO::poll_wait
           If there are any outstanding requests and none of them in
           the result phase, wait till the result filehandle becomes
           ready for reading (simply does a "select" on the filehan‐
           dle. This is useful if you want to synchronously wait for
           some requests to finish).

           See "nreqs" for an example.

       IO::AIO::poll
           Waits until some requests have been handled.

           Returns the number of requests processed, but is other‐
           wise strictly equivalent to:

              IO::AIO::poll_wait, IO::AIO::poll_cb

       IO::AIO::flush
           Wait till all outstanding AIO requests have been handled.

           Strictly equivalent to:

              IO::AIO::poll_wait, IO::AIO::poll_cb
                 while IO::AIO::nreqs;

           CONTROLLING THE NUMBER OF THREADS

       IO::AIO::min_parallel $nthreads
           Set the minimum number of AIO threads to $nthreads. The
           current default is 8, which means eight asynchronous
           operations can execute concurrently at any one time (the
           number of outstanding requests, however, is unlimited).

           IO::AIO starts threads only on demand, when an AIO
           request is queued and no free thread exists. Please note
           that queueing up a hundred requests can create demand for
           a hundred threads, even if it turns out that everything
           is in the cache and could have been processed faster by a
           single thread.

           It is recommended to keep the number of threads rela‐
           tively low, as some Linux kernel versions will scale neg‐
           atively with the number of threads (higher parallelity =>
           MUCH higher latency). With current Linux 2.6 versions,
           4-32 threads should be fine.

           Under most circumstances you don't need to call this
           function, as the module selects a default that is suit‐
           able for low to moderate load.

       IO::AIO::max_parallel $nthreads
           Sets the maximum number of AIO threads to $nthreads. If
           more than the specified number of threads are currently
           running, this function kills them. This function blocks
           until the limit is reached.

           While $nthreads are zero, aio requests get queued but not
           executed until the number of threads has been increased
           again.

           This module automatically runs "max_parallel 0" at pro‐
           gram end, to ensure that all threads are killed and that
           there are no outstanding requests.

           Under normal circumstances you don't need to call this
           function.

       IO::AIO::max_idle $nthreads
           Limit the number of threads (default: 4) that are allowed
           to idle (i.e., threads that did not get a request to
           process within 10 seconds). That means if a thread
           becomes idle while $nthreads other threads are also idle,
           it will free its resources and exit.

           This is useful when you allow a large number of threads
           (e.g. 100 or 1000) to allow for extremely high load situ‐
           ations, but want to free resources under normal circum‐
           stances (1000 threads can easily consume 30MB of RAM).

           The default is probably ok in most situations, especially
           if thread creation is fast. If thread creation is very
           slow on your system you might want to use larger values.

       $oldmaxreqs = IO::AIO::max_outstanding $maxreqs
           This is a very bad function to use in interactive pro‐
           grams because it blocks, and a bad way to reduce concur‐
           rency because it is inexact: Better use an "aio_group"
           together with a feed callback.

           Sets the maximum number of outstanding requests to
           $nreqs. If you to queue up more than this number of
           requests, the next call to the "poll_cb" (and "poll_some"
           and other functions calling "poll_cb") function will
           block until the limit is no longer exceeded.

           The default value is very large, so there is no practical
           limit on the number of outstanding requests.

           You can still queue as many requests as you want. There‐
           fore, "max_oustsanding" is mainly useful in simple
           scripts (with low values) or as a stop gap to shield
           against fatal memory overflow (with large values).

           STATISTICAL INFORMATION

       IO::AIO::nreqs
           Returns the number of requests currently in the ready,
           execute or pending states (i.e. for which their callback
           has not been invoked yet).

           Example: wait till there are no outstanding requests any‐
           more:

              IO::AIO::poll_wait, IO::AIO::poll_cb
                 while IO::AIO::nreqs;

       IO::AIO::nready
           Returns the number of requests currently in the ready
           state (not yet executed).

       IO::AIO::npending
           Returns the number of requests currently in the pending
           state (executed, but not yet processed by poll_cb).

       FORK BEHAVIOUR

       This module should do "the right thing" when the process
       using it forks:

       Before the fork, IO::AIO enters a quiescent state where no
       requests can be added in other threads and no results will be
       processed. After the fork the parent simply leaves the quies‐
       cent state and continues request/result processing, while the
       child frees the request/result queue (so that the requests
       started before the fork will only be handled in the parent).
       Threads will be started on demand until the limit set in the
       parent process has been reached again.

       In short: the parent will, after a short pause, continue as
       if fork had not been called, while the child will act as if
       IO::AIO has not been used yet.

       MEMORY USAGE

       Per-request usage:

       Each aio request uses - depending on your architecture -
       around 100-200 bytes of memory. In addition, stat requests
       need a stat buffer (possibly a few hundred bytes), readdir
       requires a result buffer and so on. Perl scalars and other
       data passed into aio requests will also be locked and will
       consume memory till the request has entered the done state.

       This is now awfully much, so queuing lots of requests is not
       usually a problem.

       Per-thread usage:

       In the execution phase, some aio requests require more memory
       for temporary buffers, and each thread requires a stack and
       other data structures (usually around 16k-128k, depending on
       the OS).

KNOWN BUGS
       Known bugs will be fixed in the next release.

SEE ALSO
       Coro::AIO.

AUTHOR
        Marc Lehmann <schmorp@schmorp.de>
        http://home.schmorp.de/



perl v5.8.5                  2007-01-23                       AIO(3)
Results 1 - 1 of 1
Help - FTP Sites List - Software Dir.
Search over 15 billion files
© 1997-2017 FileWatcher.com