view release on metacpan or  search on metacpan

lib/AnyEvent/IO.pm  view on Meta::CPAN

L<IO::AIO>).

On the other hand, requiring L<IO::AIO> for AnyEvent is clearly
impossible, as AnyEvent promises to stay pure-perl, and the overhead of
IO::AIO for small programs would be immense, especially when asynchronous
I/O isn't even needed.

Clearly, this calls for an abstraction layer, and that is what you are
looking at right now :-)

=head2 ASYNCHRONOUS VS. NON-BLOCKING

Many people are continuously confused on what the difference is between
asynchronous I/O and non-blocking I/O. In fact, those two terms are
not well defined, which often makes it hard to even talk about the
difference. Here is a short guideline that should leave you less
confused. It only talks about read operations, but the reasoning works
with other I/O operations as well.

Non-blocking I/O means that data is delivered by some external means,
automatically - that is, something I<pushes> data towards your file
handle, without you having to do anything. Non-blocking means that if
your operating system currently has no data (or EOF, or some error)
available for you, it will not wait ("block") as it would normally do,
but immediately return with an error (e.g. C<EWOULDBLOCK> - "I would have
blocked, but you forbid it").

Your program can then wait for data to arrive by other means, for example,
an I/O watcher which tells you when to re-attempt the read, after which it
can try to read again, and so on.

Often, you would expect this to work for disk files as well - if the data
isn't already in memory, one might want to wait for it and then re-attempt
the read for example. While this is sound reasoning, the POSIX API does
not support this, because disk drives and file systems do not send data
"on their own", and more so, the OS already knows that data is there, it
doesn't need to "wait" until it arrives from some external entity, it only
needs to transfer the data from disk to your memory buffer.

So basically, while the concept is sound, the existing OS APIs do not
support this. Therefore, it makes no sense to switch a disk file handle
into non-blocking mode - it will behave exactly the same as in blocking
mode, namely it will block until the data has been read from the disk.

The alternative to non-blocking I/O that actually works with disk files
is usually called I<asynchronous I/O>. Asynchronous, because the actual
I/O is done while your program does something else: there is no need to
call the read function to see if data is there, you only order the read
once, and it will notify you when the read has finished and the data is
your buffer - all the work is done in the background.

This works with disk files, and even with sockets and other sources. It
is, however, not very efficient when used with sources that could be
driven in a non-blocking way, because it usually has higher overhead
in the OS than non-blocking I/O, because it ties memory buffers for a
potentially unlimited time and often only a limited number of operations
can be done in parallel.

That's why asynchronous I/O makes most sense when confronted with disk
files, and non-blocking I/O only makes sense with sockets, pipes and
similar streaming sources.

=head1 IMPORT TAGS

By default, this module exports all C<aio_>xxx functions. In addition,
the following import tags can be used:

   :aio       all aio_* functions, same as :DEFAULT
   :flags     the fcntl open flags (O_CREAT, O_RDONLY, ...)

=head1 API NOTES

The functions in this module are not meant to be the most versatile or
the highest-performers (they are not very slow either, of course). They
are primarily meant to give users of your code the option to do the I/O
asynchronously (by installing L<IO::AIO> and L<AnyEvent::AIO>),
without adding a dependency on those modules.

=head2 NAMING

All the functions in this module implement an I/O operation, usually with
the same or similar name as the Perl built-in that they mimic, but with
an C<aio_> prefix. If you like you can think of the C<aio_>xxx functions as
"AnyEvent I/O" or "Asynchronous I/O" variants of Perl built-ins.

=head2 CALLING CONVENTIONS AND ERROR REPORTING

Each function expects a callback as their last argument. The callback is
usually called with the result data or result code. An error is usually
signalled by passing no arguments to the callback, which is then free to
look at C<$!> for the error code.

This makes all of the following forms of error checking valid:

   aio_open ...., sub {
      my $fh = shift   # scalar assignment - will assign undef on error
         or return AE::log error => "...";

      my ($fh) = @_    # list assignment - will be 0 elements on error
         or return AE::log error => "...";

      @_               # check the number of elements directly
         or return AE::log error => "...";

=head2 CAVEAT: RELATIVE PATHS

When a path is specified, this path I<must be an absolute> path, unless
you make certain that nothing in your process calls C<chdir> or an
equivalent function while the request executes.

=head2 CAVEAT: OTHER SHARED STATE

Changing the C<umask> while any requests execute that create files (or
otherwise rely on the current umask) results in undefined behaviour -
likewise changing anything else that would change the outcome, such as
your effective user or group ID.

=head2 CALLBACKS MIGHT BE CALLED BEFORE FUNCTION RETURNS TO CALLER

Unlike other functions in the AnyEvent module family, these functions
I<may> call your callback instantly, before returning. This should not be