lib/AnyEvent/IO.pm

=head1 NAME

AnyEvent::IO - the DBI of asynchronous I/O implementations

=head1 SYNOPSIS

   use AnyEvent::IO;

   ae_load "/etc/passwd", sub {
      my ($data) = @_
         or die "/etc/passwd: $!";

      warn "/etc/passwd contains ", ($data =~ y/://) , " colons.\n";
   };

   # also import O_XXX flags
   use AnyEvent::IO qw(:DEFAULT :flags);

   my $filedata = AE::cv;

   ae_open "/etc/passwd", O_RDONLY, 0, sub {
      my ($fh) = @_
         or die "/etc/passwd: $!";

      ae_stat $fh, sub {
         @_ or die "/etc/passwd: $!";

         my $size = -s _;

         ae_read $fh, $size, sub {
            my ($data) = @_
               or die "/etc/passwd: $!";

            $size == length $data
               or die "/etc/passwd: short read, file changed?";

            # mostly the same as ae_load, above - $data contains
            # the file contents now.
            $filedata->($data);
         };
      };
   };

   my $passwd = $filedata->recv;
   warn length $passwd, " octets.\n";

=head1 DESCRIPTION

This module provides functions that do I/O in an asynchronous fashion. It
is to to I/O the same as L<AnyEvent> is to event libraries - it only
interfaces to existing ones or to a portable pure-perl implementation
(that does not, however, do asynchronous I/O).

The only such implementation that is supported (or even known to the
author) is L<IO::AIO>, which is used automatically when it can be
loaded. If it is not available, L<AnyEvent::IO> falls back to its
(synchronous) pure-perl implementation.

Unlike L<AnyEvent>, which model to use is currently decided at module load
time, not at first use. Future releases might change this.

=head2 RATIONALE

While disk I/O often seems "instant" compared to, say, socket I/O, there
are many situations where your program can block for extended time periods
when doing disk I/O. For example, you access a disk on an NFS server and
it is gone - can take ages to respond again, if ever.  OR your system is
extreemly busy because it creates or restores a backup - reading data from
disk can then take seconds. Or you use Linux, which for so many years has
a close-to-broken VM/IO subsystem that can often induce minutes or more of
delay for disk I/O, even under what I would consider light I/O loads.

Whatever the situation, some programs just can't afford to block for long
times (say, half a second or more), because they need to respond as fast
as possible.

For those cases, you need asynchronous I/O.

The problem is, AnyEvent itself sometimes reads disk files (for example,
when looking at F</etc/hosts>), and under the above situations, this can
bring your program to a complete halt even if your program otherwise
takes care to only use asynchronous I/O for everything (e.g. by using
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 continously confused on what the difference is between
asynchronous I/O and non-blocking I/O. 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:

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 available for you, it will not wait
("block" as it would normally do), but immediately return with an error.

Your program can then wait for data to arrive.

Often, you would expect this to work for disk files as well - if the
data isn't already in memory, one might wait for it. While this is sound
reasoning, the POSIX API does not support this, because the operating
system does not know where and how much of data you want to read, and
moreso, the OS already knows that data is there, it doesn't need to "wait"
until it arrives from some external entity.

So basically, while the concept is sound, the existing OS APIs do not
support this, 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 he data has been read from the disk.

Th alternative that atcually works is usually called I<asynchronous>
I/O. Asynchronous, because the actual I/O is done while your program does
something else, and only when it is done will you get notified of it: You
only order the operation, it will be executed in the background, and you
will get notified of the outcome.

This works with disk files, and even with sockets and other sources that
you could use with non-blocking I/O instead. It is, however, not very
efficient when used with sources that could be driven in a non-blocking
way, it makes mose sense when confronted with disk files.

=head1 API NOTES

The functions in this module are not meant to be the most versatile or the
highest-performers. They are meant to be easy to use for common cases. You
are advised to use L<IO::AIO> directly when possible, which has a more
extensive and faster API. If, however, you just want to do some I/O with
the option of it being asynchronous when people need it, these functions
are for you.

All the functions in this module have a callback argument as their last
argument. The callback is usually being passed the result data or result
code, with C<$!> being set on error.

Most functions signal an error by passing no arguments, which makes all of
the following forms of error checking possible:

   ae_open ...., sub {
      my $fh = shift
         or die "...";

      my ($fh) = @_
         or die "...";

      @_
         or die "...";

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

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.

Unlike other functions in the AnyEvent module family, these functions
I<may> call your callback instantly, before returning. This should not be
a real problem, as these functions never return aynthing useful.

=cut

package AnyEvent::IO;

use AnyEvent (); BEGIN { AnyEvent::common_sense }

use base "Exporter";

our @AE_REQ = qw(
   ae_load ae_open ae_close ae_read ae_write ae_stat ae_lstat
   ae_link ae_symlink ae_readlink ae_rename ae_unlink
   ae_mkdir ae_rmdir ae_readdir
);
*EXPORT = \@AE_REQ;
our @FLAGS = qw(O_RDONLY O_WRONLY O_RDWR O_CREAT O_EXCL O_TRUNC O_APPEND);
*EXPORT_OK = \@FLAGS;
our %EXPORT_TAGS = (flags => \@FLAGS, ae => \@AE_REQ);

our $MODEL;

if ($MODEL) {
   AE::log 7 => "Found preloaded IO model '$MODEL', using it.";
} else {
   if ($ENV{PERL_ANYEVENT_IO_MODEL} =~ /^([a-zA-Z0-9:]+)$/) {
      if (eval { require "AnyEvent/IO/$MODEL.pm" }) {
         AE::log 7 => "Loaded IO model '$MODEL' (forced by \$ENV{PERL_ANYEVENT_IO_MODE}), using it.";
      } else {
         undef $MODEL;
         AE::log 4 => "Unable to load IO model '$ENV{PERL_ANYEVENT_IO_MODEL}' (from \$ENV{PERL_ANYEVENT_IO_MODE}):\n$@";
      }
   }

   unless ($MODEL) {
      if (eval { require IO::AIO; require AnyEvent::AIO; require AnyEvent::IO::IOAIO }) {
         AE::log 7 => "Autoloaded IO model 'IOAIO', using it.";
      } else {
         require AnyEvent::IO::PP;
         AE::log 7 => "Autoloaded IO model 'Perl', using it.";
      }
   }
}

=head1 GLOBAL VARIABLES AND FUNCTIONS

These are exported unless documented with full package name.

=over 4

=item $AnyEvent::IO::MODEL

Contains the backend model in use - at the moment, this is usually
C<Perl> or C<IOAIO>, corresponding to L<AnyEvent::IO::Perl> and
L<AnyEvent::IO::IOAIO>, respectively.

=item ae_load $path, $cb->($data)

Tries to open C<$path> and read its contents into memory (obviously,
should only be used on files that are small enough").

If an error occurs, the callback receives I<no> arguments, otherwise, the
only argument is the file data as a string.

Example: load F</etc/hosts>.

   ae_load "/etc/hosts", sub {
      my ($hosts) = @_
         or die "/etc/hosts: $!";

      AE::log info => "/etc/hosts contains ", ($hosts =~ y/\n/), " lines\n";
   };

=item ae_open $path, $flags, $mode, $cb->($fh)

Tries to open the file specified by C<$path> with the O_XXX-flags
C<$flags> (from the Fcntl module, or see below) and the mode C<$mode> (a
good value is 0666 for C<O_CREAT>, and C<0> otherwise).

This works very much like perl's C<sysopen> function.

If an error occurs, the callback receives I<no> arguments, otherwise, the
only argument is the (normal perl) file handle.

Changing the C<umask> while this request executes results in undefined
behaviour - likewise changing anything else that would change the outcome,
such as your effective user or group ID.

To avoid having to load L<Fcntl>, this module provides constants
for C<O_RDONLY>, C<O_WRONLY>, C<O_RDWR>, C<O_CREAT>, C<O_EXCL>,
C<O_TRUNC> and C<O_APPEND> - you can either access them directly
(C<AnyEvent::IO::O_RDONLY>) or import them by specifying the C<:flags>
import tag (see SYNOPSIS).

=item ae_close $fh, $cb->($success)

Closes the file handle (yes, close can block your process
indefinitely). If an error occurs, passes I<no> arguments, otherwise
passes a true value.

Due to idiosynchrasies in perl, instead of calling C<close>, the file
handle might get closed by C<dup2>'ing another file descriptor over
it, that is, the C<$fh> might still be open, but can be closed safely
afterwards and must not be used for anything.

=item ae_read $fh, $length, $cb->($data)

Tries to read C<$length> octets from the current position from C<$fh> and
passes these bytes to C<$cb>. Otherwise the semantics are very much like
those of perl's C<sysread>.

If less than C<$length> octets have been read, C<$data> will contain
only those bytes atcually read. At EOF, C<$data> will be a zero-length
string. If an error occurs, then nothing is passed to the callback.

Obviously, multiple C<ae_read>'s or C<ae_write>'s at the same time on file
handles sharing the underlying open file description results in undefined
behaviour, due to sharing of the current file offset (and less obviouisly
so, because OS X is not thread safe and corrupts data when you try).

=item ae_write $fh, $data, $cb->($length)

Tries to write the octets in C<$data> to the current position of C<$fh>
and passes the actual number of bytes written to the C<$cb>. Otherwise the
semantics are very much like those of perl's C<syswrite>.

If less than C<length $data> octets have been written, C<$length> will
reflect that. If an error occurs, then nothing is passed to the callback.

Obviously, multiple C<ae_read>'s or C<ae_write>'s at the same time on file
handles sharing the underlying open file description results in undefined
behaviour, due to sharing of the current file offset (and less obviouisly
so, because OS X is not thread safe and corrupts data when you try).

=item ae_stat $fh_or_path, $cb->($success)

=item ae_lstat $path, $cb->($success)

Calls C<stat> or C<lstat> on the path or perl file handle. If an error
occurs, passes I<no> arguments, otherwise passes a true value.

The stat data will be available by stat'ing the C<_> file handle
(e.g. C<-x _>, C<stat _> and so on).

=item ae_link $oldpath, $newpath, $cb->($success)

Calls C<link> on the paths. If an error occurs, passes I<no> arguments,
otherwise passes a true value.

=item ae_symlink $oldpath, $newpath, $cb->($success)

Calls C<symlink> on the paths. If an error occurs, passes I<no> arguments,
otherwise passes a true value.

=item ae_readlink $path, $cb->($target)

Calls C<readlink> on the paths. If an error occurs, passes I<no> arguments,
otherwise passes the link target string.

=item ae_rename $oldpath, $newpath, $cb->($success)

Calls C<rename> on the paths. If an error occurs, passes I<no> arguments,
otherwise passes a true value.

=item ae_unlink $path, $cb->($success)

Tries to unlink the object at C<$path>. If an error occurs, passes I<no>
arguments, otherwise passes a true value.

=item ae_mkdir $path, $perms, $cb->($success)

Calls C<mkdir> on the path with the given permissions C<$perms> (when
in doubt, C<0777> is a good value). If an error occurs, passes I<no>
arguments, otherwise passes a true value.

=item ae_rmdir $path, $cb->($success)

Tries to remove the directory at C<$path>. If an error occurs, passes
I<no> arguments, otherwise passes a true value.

=back

=head1 ENVIRONMENT VARIABLES

See the description of C<PERL_ANYEVENT_IO_MODEL> in the L<AnyEvent>
manpage.

=head1 AUTHOR

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

=cut

1

Revision:	1.3
Committed:	Wed Mar 28 23:11:16 2012 UTC (12 years, 3 months ago) by root
Branch:	MAIN
Changes since 1.2:	+7 -2 lines
Log Message:	* empty log message *
#	User	Rev	Content
1	root	1.1	=head1 NAME
2
3			AnyEvent::IO - the DBI of asynchronous I/O implementations
4
5			=head1 SYNOPSIS
6
7			use AnyEvent::IO;
8
9	root	1.2	ae_load "/etc/passwd", sub {
10	root	1.1	my ($data) = @_
11			or die "/etc/passwd: $!";
12
13			warn "/etc/passwd contains ", ($data =~ y/://) , " colons.\n";
14			};
15
16			# also import O_XXX flags
17			use AnyEvent::IO qw(:DEFAULT :flags);
18
19			my $filedata = AE::cv;
20
21	root	1.2	ae_open "/etc/passwd", O_RDONLY, 0, sub {
22	root	1.1	my ($fh) = @_
23			or die "/etc/passwd: $!";
24
25	root	1.2	ae_stat $fh, sub {
26	root	1.1	@_ or die "/etc/passwd: $!";
27
28			my $size = -s _;
29
30	root	1.2	ae_read $fh, $size, sub {
31	root	1.1	my ($data) = @_
32			or die "/etc/passwd: $!";
33
34			$size == length $data
35			or die "/etc/passwd: short read, file changed?";
36
37	root	1.2	# mostly the same as ae_load, above - $data contains
38	root	1.1	# the file contents now.
39			$filedata->($data);
40			};
41			};
42			};
43
44			my $passwd = $filedata->recv;
45			warn length $passwd, " octets.\n";
46
47			=head1 DESCRIPTION
48
49			This module provides functions that do I/O in an asynchronous fashion. It
50			is to to I/O the same as L<AnyEvent> is to event libraries - it only
51			interfaces to existing ones or to a portable pure-perl implementation
52			(that does not, however, do asynchronous I/O).
53
54			The only such implementation that is supported (or even known to the
55			author) is L<IO::AIO>, which is used automatically when it can be
56			loaded. If it is not available, L<AnyEvent::IO> falls back to its
57			(synchronous) pure-perl implementation.
58
59			Unlike L<AnyEvent>, which model to use is currently decided at module load
60			time, not at first use. Future releases might change this.
61
62			=head2 RATIONALE
63
64			While disk I/O often seems "instant" compared to, say, socket I/O, there
65			are many situations where your program can block for extended time periods
66			when doing disk I/O. For example, you access a disk on an NFS server and
67			it is gone - can take ages to respond again, if ever. OR your system is
68			extreemly busy because it creates or restores a backup - reading data from
69			disk can then take seconds. Or you use Linux, which for so many years has
70			a close-to-broken VM/IO subsystem that can often induce minutes or more of
71			delay for disk I/O, even under what I would consider light I/O loads.
72
73			Whatever the situation, some programs just can't afford to block for long
74			times (say, half a second or more), because they need to respond as fast
75			as possible.
76
77			For those cases, you need asynchronous I/O.
78
79			The problem is, AnyEvent itself sometimes reads disk files (for example,
80			when looking at F</etc/hosts>), and under the above situations, this can
81			bring your program to a complete halt even if your program otherwise
82			takes care to only use asynchronous I/O for everything (e.g. by using
83			L<IO::AIO>).
84
85			On the other hand, requiring L<IO::AIO> for AnyEvent is clearly
86			impossible, as Anyevent promises to stay pure-perl, and the overhead of
87			IO::AIO for small programs would be immense, especially when asynchronous
88			I/O isn't even needed.
89
90			Clearly, this calls for an abstraction layer, and that is what you are
91			looking at right now :-)
92
93			=head2 ASYNCHRONOUS VS. NON-BLOCKING
94
95			Many people are continously confused on what the difference is between
96			asynchronous I/O and non-blocking I/O. Those two terms are not well
97			defined, which often makes it hard to even talk about the difference. Here
98			is a short guideline that should leave you less confused:
99
100			Non-blocking I/O means that data is delivered by some external means,
101			automatically - that is, something I<pushes> data towards your file
102			handle without you having to do anything. Non-blocking means that if your
103			operating system currently has no data available for you, it will not wait
104			("block" as it would normally do), but immediately return with an error.
105
106			Your program can then wait for data to arrive.
107
108			Often, you would expect this to work for disk files as well - if the
109			data isn't already in memory, one might wait for it. While this is sound
110			reasoning, the POSIX API does not support this, because the operating
111			system does not know where and how much of data you want to read, and
112			moreso, the OS already knows that data is there, it doesn't need to "wait"
113			until it arrives from some external entity.
114
115			So basically, while the concept is sound, the existing OS APIs do not
116			support this, it makes no sense to switch a disk file handle into
117			non-blocking mode - it will behave exactly the same as in blocking mode,
118			namely it will block until he data has been read from the disk.
119
120			Th alternative that atcually works is usually called I<asynchronous>
121			I/O. Asynchronous, because the actual I/O is done while your program does
122			something else, and only when it is done will you get notified of it: You
123			only order the operation, it will be executed in the background, and you
124			will get notified of the outcome.
125
126			This works with disk files, and even with sockets and other sources that
127			you could use with non-blocking I/O instead. It is, however, not very
128			efficient when used with sources that could be driven in a non-blocking
129			way, it makes mose sense when confronted with disk files.
130
131			=head1 API NOTES
132
133			The functions in this module are not meant to be the most versatile or the
134			highest-performers. They are meant to be easy to use for common cases. You
135			are advised to use L<IO::AIO> directly when possible, which has a more
136			extensive and faster API. If, however, you just want to do some I/O with
137			the option of it being asynchronous when people need it, these functions
138			are for you.
139
140			All the functions in this module have a callback argument as their last
141			argument. The callback is usually being passed the result data or result
142			code, with C<$!> being set on error.
143
144	root	1.2	Most functions signal an error by passing no arguments, which makes all of
145			the following forms of error checking possible:
146
147			ae_open ...., sub {
148			my $fh = shift
149			or die "...";
150
151			my ($fh) = @_
152			or die "...";
153
154			@_
155			or die "...";
156
157	root	1.1	When a path is specified, this path I<must be an absolute> path, unless
158			you can make sure that nothing in your process calls C<chdir> or an
159			equivalent function while the request executes.
160
161	root	1.2	Changing the C<umask> while any requests execute that create files or
162			otherwise rely on the current umask results in undefined behaviour -
163			likewise changing anything else that would change the outcome, such as
164			your effective user or group ID.
165
166	root	1.1	Unlike other functions in the AnyEvent module family, these functions
167			I<may> call your callback instantly, before returning. This should not be
168			a real problem, as these functions never return aynthing useful.
169
170			=cut
171
172			package AnyEvent::IO;
173
174			use AnyEvent (); BEGIN { AnyEvent::common_sense }
175
176			use base "Exporter";
177
178	root	1.2	our @AE_REQ = qw(
179			ae_load ae_open ae_close ae_read ae_write ae_stat ae_lstat
180	root	1.3	ae_link ae_symlink ae_readlink ae_rename ae_unlink
181			ae_mkdir ae_rmdir ae_readdir
182	root	1.2	);
183			*EXPORT = \@AE_REQ;
184	root	1.1	our @FLAGS = qw(O_RDONLY O_WRONLY O_RDWR O_CREAT O_EXCL O_TRUNC O_APPEND);
185			*EXPORT_OK = \@FLAGS;
186	root	1.2	our %EXPORT_TAGS = (flags => \@FLAGS, ae => \@AE_REQ);
187	root	1.1
188			our $MODEL;
189
190			if ($MODEL) {
191			AE::log 7 => "Found preloaded IO model '$MODEL', using it.";
192			} else {
193			if ($ENV{PERL_ANYEVENT_IO_MODEL} =~ /^([a-zA-Z0-9:]+)$/) {
194			if (eval { require "AnyEvent/IO/$MODEL.pm" }) {
195			AE::log 7 => "Loaded IO model '$MODEL' (forced by \$ENV{PERL_ANYEVENT_IO_MODE}), using it.";
196			} else {
197			undef $MODEL;
198			AE::log 4 => "Unable to load IO model '$ENV{PERL_ANYEVENT_IO_MODEL}' (from \$ENV{PERL_ANYEVENT_IO_MODE}):\n$@";
199			}
200			}
201
202			unless ($MODEL) {
203			if (eval { require IO::AIO; require AnyEvent::AIO; require AnyEvent::IO::IOAIO }) {
204			AE::log 7 => "Autoloaded IO model 'IOAIO', using it.";
205			} else {
206			require AnyEvent::IO::PP;
207			AE::log 7 => "Autoloaded IO model 'Perl', using it.";
208			}
209			}
210			}
211
212			=head1 GLOBAL VARIABLES AND FUNCTIONS
213
214			These are exported unless documented with full package name.
215
216			=over 4
217
218			=item $AnyEvent::IO::MODEL
219
220			Contains the backend model in use - at the moment, this is usually
221			C<Perl> or C<IOAIO>, corresponding to L<AnyEvent::IO::Perl> and
222			L<AnyEvent::IO::IOAIO>, respectively.
223
224	root	1.2	=item ae_load $path, $cb->($data)
225	root	1.1
226			Tries to open C<$path> and read its contents into memory (obviously,
227			should only be used on files that are small enough").
228
229			If an error occurs, the callback receives I<no> arguments, otherwise, the
230			only argument is the file data as a string.
231
232			Example: load F</etc/hosts>.
233
234	root	1.2	ae_load "/etc/hosts", sub {
235	root	1.1	my ($hosts) = @_
236			or die "/etc/hosts: $!";
237
238			AE::log info => "/etc/hosts contains ", ($hosts =~ y/\n/), " lines\n";
239			};
240
241	root	1.2	=item ae_open $path, $flags, $mode, $cb->($fh)
242	root	1.1
243			Tries to open the file specified by C<$path> with the O_XXX-flags
244			C<$flags> (from the Fcntl module, or see below) and the mode C<$mode> (a
245			good value is 0666 for C<O_CREAT>, and C<0> otherwise).
246
247			This works very much like perl's C<sysopen> function.
248
249			If an error occurs, the callback receives I<no> arguments, otherwise, the
250			only argument is the (normal perl) file handle.
251
252			Changing the C<umask> while this request executes results in undefined
253	root	1.2	behaviour - likewise changing anything else that would change the outcome,
254			such as your effective user or group ID.
255	root	1.1
256			To avoid having to load L<Fcntl>, this module provides constants
257			for C<O_RDONLY>, C<O_WRONLY>, C<O_RDWR>, C<O_CREAT>, C<O_EXCL>,
258			C<O_TRUNC> and C<O_APPEND> - you can either access them directly
259			(C<AnyEvent::IO::O_RDONLY>) or import them by specifying the C<:flags>
260			import tag (see SYNOPSIS).
261
262	root	1.2	=item ae_close $fh, $cb->($success)
263	root	1.1
264			Closes the file handle (yes, close can block your process
265			indefinitely). If an error occurs, passes I<no> arguments, otherwise
266			passes a true value.
267
268			Due to idiosynchrasies in perl, instead of calling C<close>, the file
269			handle might get closed by C<dup2>'ing another file descriptor over
270			it, that is, the C<$fh> might still be open, but can be closed safely
271			afterwards and must not be used for anything.
272
273	root	1.2	=item ae_read $fh, $length, $cb->($data)
274	root	1.1
275			Tries to read C<$length> octets from the current position from C<$fh> and
276			passes these bytes to C<$cb>. Otherwise the semantics are very much like
277			those of perl's C<sysread>.
278
279			If less than C<$length> octets have been read, C<$data> will contain
280			only those bytes atcually read. At EOF, C<$data> will be a zero-length
281			string. If an error occurs, then nothing is passed to the callback.
282
283	root	1.2	Obviously, multiple C<ae_read>'s or C<ae_write>'s at the same time on file
284	root	1.1	handles sharing the underlying open file description results in undefined
285			behaviour, due to sharing of the current file offset (and less obviouisly
286			so, because OS X is not thread safe and corrupts data when you try).
287
288	root	1.2	=item ae_write $fh, $data, $cb->($length)
289	root	1.1
290			Tries to write the octets in C<$data> to the current position of C<$fh>
291			and passes the actual number of bytes written to the C<$cb>. Otherwise the
292			semantics are very much like those of perl's C<syswrite>.
293
294			If less than C<length $data> octets have been written, C<$length> will
295			reflect that. If an error occurs, then nothing is passed to the callback.
296
297	root	1.2	Obviously, multiple C<ae_read>'s or C<ae_write>'s at the same time on file
298	root	1.1	handles sharing the underlying open file description results in undefined
299			behaviour, due to sharing of the current file offset (and less obviouisly
300			so, because OS X is not thread safe and corrupts data when you try).
301
302	root	1.2	=item ae_stat $fh_or_path, $cb->($success)
303	root	1.1
304	root	1.2	=item ae_lstat $path, $cb->($success)
305	root	1.1
306			Calls C<stat> or C<lstat> on the path or perl file handle. If an error
307			occurs, passes I<no> arguments, otherwise passes a true value.
308
309			The stat data will be available by stat'ing the C<_> file handle
310			(e.g. C<-x _>, C<stat _> and so on).
311
312	root	1.2	=item ae_link $oldpath, $newpath, $cb->($success)
313
314			Calls C<link> on the paths. If an error occurs, passes I<no> arguments,
315			otherwise passes a true value.
316
317			=item ae_symlink $oldpath, $newpath, $cb->($success)
318
319			Calls C<symlink> on the paths. If an error occurs, passes I<no> arguments,
320			otherwise passes a true value.
321
322	root	1.3	=item ae_readlink $path, $cb->($target)
323
324			Calls C<readlink> on the paths. If an error occurs, passes I<no> arguments,
325			otherwise passes the link target string.
326
327	root	1.2	=item ae_rename $oldpath, $newpath, $cb->($success)
328
329			Calls C<rename> on the paths. If an error occurs, passes I<no> arguments,
330			otherwise passes a true value.
331
332			=item ae_unlink $path, $cb->($success)
333
334			Tries to unlink the object at C<$path>. If an error occurs, passes I<no>
335			arguments, otherwise passes a true value.
336
337			=item ae_mkdir $path, $perms, $cb->($success)
338
339			Calls C<mkdir> on the path with the given permissions C<$perms> (when
340			in doubt, C<0777> is a good value). If an error occurs, passes I<no>
341			arguments, otherwise passes a true value.
342
343			=item ae_rmdir $path, $cb->($success)
344
345			Tries to remove the directory at C<$path>. If an error occurs, passes
346			I<no> arguments, otherwise passes a true value.
347
348	root	1.1	=back
349
350			=head1 ENVIRONMENT VARIABLES
351
352			See the description of C<PERL_ANYEVENT_IO_MODEL> in the L<AnyEvent>
353			manpage.
354
355			=head1 AUTHOR
356
357			Marc Lehmann <schmorp@schmorp.de>
358			http://home.schmorp.de/
359
360			=cut
361
362			1
363