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.14 |
aio_load "/etc/passwd", sub { |
10 |
root |
1.1 |
my ($data) = @_ |
11 |
root |
1.15 |
or return AE::log error => "/etc/passwd: $!"; |
12 |
root |
1.1 |
|
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.14 |
aio_open "/etc/passwd", O_RDONLY, 0, sub { |
22 |
root |
1.1 |
my ($fh) = @_ |
23 |
root |
1.15 |
or return AE::log error => "/etc/passwd: $!"; |
24 |
root |
1.1 |
|
25 |
root |
1.14 |
aio_stat $fh, sub { |
26 |
root |
1.15 |
@_ |
27 |
|
|
or return AE::log error => "/etc/passwd: $!"; |
28 |
root |
1.1 |
|
29 |
|
|
my $size = -s _; |
30 |
|
|
|
31 |
root |
1.14 |
aio_read $fh, $size, sub { |
32 |
root |
1.1 |
my ($data) = @_ |
33 |
root |
1.15 |
or return AE::log error => "/etc/passwd: $!"; |
34 |
root |
1.1 |
|
35 |
|
|
$size == length $data |
36 |
root |
1.15 |
or return AE::log error => "/etc/passwd: short read, file changed?"; |
37 |
root |
1.1 |
|
38 |
root |
1.14 |
# mostly the same as aio_load, above - $data contains |
39 |
root |
1.1 |
# the file contents now. |
40 |
|
|
$filedata->($data); |
41 |
|
|
}; |
42 |
|
|
}; |
43 |
|
|
}; |
44 |
|
|
|
45 |
|
|
my $passwd = $filedata->recv; |
46 |
|
|
warn length $passwd, " octets.\n"; |
47 |
|
|
|
48 |
|
|
=head1 DESCRIPTION |
49 |
|
|
|
50 |
|
|
This module provides functions that do I/O in an asynchronous fashion. It |
51 |
|
|
is to to I/O the same as L<AnyEvent> is to event libraries - it only |
52 |
root |
1.5 |
I<interfaces> to other implementations or to a portable pure-perl |
53 |
|
|
implementation (that does not, however, do asynchronous I/O). |
54 |
root |
1.1 |
|
55 |
|
|
The only such implementation that is supported (or even known to the |
56 |
|
|
author) is L<IO::AIO>, which is used automatically when it can be |
57 |
|
|
loaded. If it is not available, L<AnyEvent::IO> falls back to its |
58 |
|
|
(synchronous) pure-perl implementation. |
59 |
|
|
|
60 |
|
|
Unlike L<AnyEvent>, which model to use is currently decided at module load |
61 |
|
|
time, not at first use. Future releases might change this. |
62 |
|
|
|
63 |
|
|
=head2 RATIONALE |
64 |
|
|
|
65 |
|
|
While disk I/O often seems "instant" compared to, say, socket I/O, there |
66 |
|
|
are many situations where your program can block for extended time periods |
67 |
|
|
when doing disk I/O. For example, you access a disk on an NFS server and |
68 |
|
|
it is gone - can take ages to respond again, if ever. OR your system is |
69 |
root |
1.5 |
extremely busy because it creates or restores a backup - reading data from |
70 |
root |
1.1 |
disk can then take seconds. Or you use Linux, which for so many years has |
71 |
|
|
a close-to-broken VM/IO subsystem that can often induce minutes or more of |
72 |
|
|
delay for disk I/O, even under what I would consider light I/O loads. |
73 |
|
|
|
74 |
|
|
Whatever the situation, some programs just can't afford to block for long |
75 |
|
|
times (say, half a second or more), because they need to respond as fast |
76 |
|
|
as possible. |
77 |
|
|
|
78 |
|
|
For those cases, you need asynchronous I/O. |
79 |
|
|
|
80 |
|
|
The problem is, AnyEvent itself sometimes reads disk files (for example, |
81 |
|
|
when looking at F</etc/hosts>), and under the above situations, this can |
82 |
|
|
bring your program to a complete halt even if your program otherwise |
83 |
|
|
takes care to only use asynchronous I/O for everything (e.g. by using |
84 |
|
|
L<IO::AIO>). |
85 |
|
|
|
86 |
|
|
On the other hand, requiring L<IO::AIO> for AnyEvent is clearly |
87 |
root |
1.5 |
impossible, as AnyEvent promises to stay pure-perl, and the overhead of |
88 |
root |
1.1 |
IO::AIO for small programs would be immense, especially when asynchronous |
89 |
|
|
I/O isn't even needed. |
90 |
|
|
|
91 |
|
|
Clearly, this calls for an abstraction layer, and that is what you are |
92 |
|
|
looking at right now :-) |
93 |
|
|
|
94 |
|
|
=head2 ASYNCHRONOUS VS. NON-BLOCKING |
95 |
|
|
|
96 |
root |
1.5 |
Many people are continuously confused on what the difference is between |
97 |
root |
1.1 |
asynchronous I/O and non-blocking I/O. Those two terms are not well |
98 |
|
|
defined, which often makes it hard to even talk about the difference. Here |
99 |
|
|
is a short guideline that should leave you less confused: |
100 |
|
|
|
101 |
|
|
Non-blocking I/O means that data is delivered by some external means, |
102 |
|
|
automatically - that is, something I<pushes> data towards your file |
103 |
|
|
handle without you having to do anything. Non-blocking means that if your |
104 |
|
|
operating system currently has no data available for you, it will not wait |
105 |
|
|
("block" as it would normally do), but immediately return with an error. |
106 |
|
|
|
107 |
|
|
Your program can then wait for data to arrive. |
108 |
|
|
|
109 |
|
|
Often, you would expect this to work for disk files as well - if the |
110 |
|
|
data isn't already in memory, one might wait for it. While this is sound |
111 |
|
|
reasoning, the POSIX API does not support this, because the operating |
112 |
root |
1.5 |
system does not know where and how much of data you want to read, and more |
113 |
|
|
so, the OS already knows that data is there, it doesn't need to "wait" |
114 |
root |
1.1 |
until it arrives from some external entity. |
115 |
|
|
|
116 |
|
|
So basically, while the concept is sound, the existing OS APIs do not |
117 |
|
|
support this, it makes no sense to switch a disk file handle into |
118 |
|
|
non-blocking mode - it will behave exactly the same as in blocking mode, |
119 |
root |
1.5 |
namely it will block until the data has been read from the disk. |
120 |
root |
1.1 |
|
121 |
root |
1.5 |
Th alternative that actually works is usually called I<asynchronous> |
122 |
root |
1.1 |
I/O. Asynchronous, because the actual I/O is done while your program does |
123 |
|
|
something else, and only when it is done will you get notified of it: You |
124 |
|
|
only order the operation, it will be executed in the background, and you |
125 |
|
|
will get notified of the outcome. |
126 |
|
|
|
127 |
|
|
This works with disk files, and even with sockets and other sources that |
128 |
|
|
you could use with non-blocking I/O instead. It is, however, not very |
129 |
|
|
efficient when used with sources that could be driven in a non-blocking |
130 |
root |
1.5 |
way, it makes most sense when confronted with disk files. |
131 |
root |
1.1 |
|
132 |
root |
1.7 |
=head1 IMPORT TAGS |
133 |
|
|
|
134 |
root |
1.14 |
By default, this module implements all C<aio_>xxx functions. In addition, |
135 |
root |
1.7 |
the following import tags can be used: |
136 |
|
|
|
137 |
root |
1.15 |
:aio all aio_* functions, smae as :DEFAULT |
138 |
root |
1.7 |
:flags the fcntl open flags (O_CREAT, O_RDONLY, ...) |
139 |
|
|
|
140 |
root |
1.1 |
=head1 API NOTES |
141 |
|
|
|
142 |
|
|
The functions in this module are not meant to be the most versatile or the |
143 |
|
|
highest-performers. They are meant to be easy to use for common cases. You |
144 |
|
|
are advised to use L<IO::AIO> directly when possible, which has a more |
145 |
|
|
extensive and faster API. If, however, you just want to do some I/O with |
146 |
|
|
the option of it being asynchronous when people need it, these functions |
147 |
|
|
are for you. |
148 |
|
|
|
149 |
root |
1.15 |
=head2 NAMING |
150 |
|
|
|
151 |
root |
1.7 |
All the functions in this module implement an I/O operation, usually with |
152 |
root |
1.14 |
the same or similar name as the Perl builtin that it mimics, but with an |
153 |
|
|
C<aio_> prefix. If you like you can think of the C<aio_> functions as |
154 |
|
|
"AnyEvent I/O" or "Asynchronous I/O" variants. |
155 |
root |
1.7 |
|
156 |
root |
1.15 |
=head2 CALLING CONVENTIONS AND ERROR REPORTING |
157 |
|
|
|
158 |
root |
1.7 |
Each function expects a callback as their last argument. The callback is |
159 |
|
|
usually called with the result data or result code. An error is usually |
160 |
|
|
signalled by passing no arguments to the callback, which is then free to |
161 |
|
|
look at C<$!> for the error code. |
162 |
root |
1.1 |
|
163 |
root |
1.7 |
This makes all of the following forms of error checking valid: |
164 |
root |
1.2 |
|
165 |
root |
1.14 |
aio_open ...., sub { |
166 |
root |
1.7 |
my $fh = shift # scalar assignment - will assign undef on error |
167 |
root |
1.15 |
or return AE::log error => "..."; |
168 |
root |
1.2 |
|
169 |
root |
1.7 |
my ($fh) = @_ # list assignment - will be 0 elements on error |
170 |
root |
1.15 |
or return AE::log error => "..."; |
171 |
root |
1.2 |
|
172 |
root |
1.7 |
@_ # check the number of elements directly |
173 |
root |
1.15 |
or return AE::log error => "..."; |
174 |
|
|
|
175 |
|
|
=head2 CAVEAT: RELATIVE PATHS |
176 |
root |
1.2 |
|
177 |
root |
1.1 |
When a path is specified, this path I<must be an absolute> path, unless |
178 |
root |
1.7 |
you make certain that nothing in your process calls C<chdir> or an |
179 |
root |
1.1 |
equivalent function while the request executes. |
180 |
|
|
|
181 |
root |
1.15 |
=head2 CAVEAT: OTHER SHARED STATE |
182 |
|
|
|
183 |
root |
1.7 |
Changing the C<umask> while any requests execute that create files (or |
184 |
|
|
otherwise rely on the current umask) results in undefined behaviour - |
185 |
root |
1.2 |
likewise changing anything else that would change the outcome, such as |
186 |
|
|
your effective user or group ID. |
187 |
|
|
|
188 |
root |
1.1 |
Unlike other functions in the AnyEvent module family, these functions |
189 |
|
|
I<may> call your callback instantly, before returning. This should not be |
190 |
root |
1.5 |
a real problem, as these functions never return anything useful. |
191 |
root |
1.1 |
|
192 |
root |
1.15 |
=head2 BEHAVIOUR AT PROGRAM EXIT |
193 |
|
|
|
194 |
|
|
Both L<AnyEvent::IO::Perl> and L<AnyEvent::IO::IOAIO> implementations |
195 |
|
|
make sure that operations that have started will be finished on a clean |
196 |
|
|
programs exit. That makes programs work that start some I/O operations and |
197 |
|
|
then exit. For example this complete program: |
198 |
|
|
|
199 |
|
|
use AnyEvent::IO; |
200 |
|
|
|
201 |
|
|
aio_stat "path1", sub { |
202 |
|
|
aio_stat "path2", sub { |
203 |
|
|
warn "both stats done\n"; |
204 |
|
|
}; |
205 |
|
|
}; |
206 |
|
|
|
207 |
|
|
Starts a C<stat> operation and then exits by "falling off the end" of |
208 |
|
|
the program. Nevertheless, I<both> C<stat> operations will be executed, |
209 |
|
|
as AnyEvent::IO waits for all outstanding requests to finish and you can |
210 |
|
|
start new requests from request callbacks. |
211 |
|
|
|
212 |
|
|
In fact, since L<AnyEvent::IO::Perl> is currently synchronous, the |
213 |
|
|
program will do both stats before falling off the end, but with |
214 |
|
|
L<AnyEvent::IO::IOAIO>, the program first falls of the end, then the stats |
215 |
|
|
are executed. |
216 |
|
|
|
217 |
|
|
While not guaranteed, this behaviour will be present in future versions, |
218 |
|
|
if reasonably possible (which is extreemly likely :). |
219 |
|
|
|
220 |
root |
1.1 |
=cut |
221 |
|
|
|
222 |
|
|
package AnyEvent::IO; |
223 |
|
|
|
224 |
|
|
use AnyEvent (); BEGIN { AnyEvent::common_sense } |
225 |
|
|
|
226 |
|
|
use base "Exporter"; |
227 |
|
|
|
228 |
root |
1.14 |
our @AIO_REQ = qw( |
229 |
|
|
aio_load aio_open aio_close aio_seek aio_read aio_write aio_truncate |
230 |
|
|
aio_utime aio_chown aio_chmod aio_stat aio_lstat |
231 |
|
|
aio_link aio_symlink aio_readlink aio_rename aio_unlink |
232 |
|
|
aio_mkdir aio_rmdir aio_readdir |
233 |
root |
1.2 |
); |
234 |
root |
1.14 |
*EXPORT = \@AIO_REQ; |
235 |
root |
1.1 |
our @FLAGS = qw(O_RDONLY O_WRONLY O_RDWR O_CREAT O_EXCL O_TRUNC O_APPEND); |
236 |
|
|
*EXPORT_OK = \@FLAGS; |
237 |
root |
1.14 |
our %EXPORT_TAGS = (flags => \@FLAGS, aio => \@AIO_REQ); |
238 |
root |
1.1 |
|
239 |
|
|
our $MODEL; |
240 |
|
|
|
241 |
|
|
if ($MODEL) { |
242 |
|
|
AE::log 7 => "Found preloaded IO model '$MODEL', using it."; |
243 |
|
|
} else { |
244 |
|
|
if ($ENV{PERL_ANYEVENT_IO_MODEL} =~ /^([a-zA-Z0-9:]+)$/) { |
245 |
root |
1.6 |
if (eval { require "AnyEvent/IO/$ENV{PERL_ANYEVENT_IO_MODEL}.pm" }) { |
246 |
|
|
AE::log 7 => "Loaded IO model '$MODEL' (forced by \$ENV{PERL_ANYEVENT_IO_MODEL}), using it."; |
247 |
root |
1.1 |
} else { |
248 |
|
|
undef $MODEL; |
249 |
root |
1.6 |
AE::log 4 => "Unable to load IO model '$ENV{PERL_ANYEVENT_IO_MODEL}' (from \$ENV{PERL_ANYEVENT_IO_MODEL}):\n$@"; |
250 |
root |
1.1 |
} |
251 |
|
|
} |
252 |
|
|
|
253 |
|
|
unless ($MODEL) { |
254 |
|
|
if (eval { require IO::AIO; require AnyEvent::AIO; require AnyEvent::IO::IOAIO }) { |
255 |
|
|
AE::log 7 => "Autoloaded IO model 'IOAIO', using it."; |
256 |
|
|
} else { |
257 |
|
|
require AnyEvent::IO::PP; |
258 |
|
|
AE::log 7 => "Autoloaded IO model 'Perl', using it."; |
259 |
|
|
} |
260 |
|
|
} |
261 |
|
|
} |
262 |
|
|
|
263 |
|
|
=head1 GLOBAL VARIABLES AND FUNCTIONS |
264 |
|
|
|
265 |
|
|
=over 4 |
266 |
|
|
|
267 |
|
|
=item $AnyEvent::IO::MODEL |
268 |
|
|
|
269 |
root |
1.8 |
Contains the package name of the backend I/O model in use - at the moment, |
270 |
|
|
this is usually C<AnyEvent::IO::Perl> or C<AnyEvent::IO::IOAIO>. |
271 |
root |
1.1 |
|
272 |
root |
1.14 |
=item aio_load $path, $cb->($data) |
273 |
root |
1.1 |
|
274 |
|
|
Tries to open C<$path> and read its contents into memory (obviously, |
275 |
root |
1.9 |
should only be used on files that are "small enough"), then passes them to |
276 |
|
|
the callback as a string. |
277 |
root |
1.1 |
|
278 |
|
|
Example: load F</etc/hosts>. |
279 |
|
|
|
280 |
root |
1.14 |
aio_load "/etc/hosts", sub { |
281 |
root |
1.1 |
my ($hosts) = @_ |
282 |
root |
1.15 |
or return AE::log error => "/etc/hosts: $!"; |
283 |
root |
1.1 |
|
284 |
|
|
AE::log info => "/etc/hosts contains ", ($hosts =~ y/\n/), " lines\n"; |
285 |
|
|
}; |
286 |
|
|
|
287 |
root |
1.14 |
=item aio_open $path, $flags, $mode, $cb->($fh) |
288 |
root |
1.1 |
|
289 |
|
|
Tries to open the file specified by C<$path> with the O_XXX-flags |
290 |
|
|
C<$flags> (from the Fcntl module, or see below) and the mode C<$mode> (a |
291 |
|
|
good value is 0666 for C<O_CREAT>, and C<0> otherwise). |
292 |
|
|
|
293 |
root |
1.9 |
The (normal, standard, perl) file handle associated with the opened file |
294 |
|
|
is then passed to the callback. |
295 |
|
|
|
296 |
root |
1.15 |
This works very much like Perl's C<sysopen> function. |
297 |
root |
1.1 |
|
298 |
|
|
Changing the C<umask> while this request executes results in undefined |
299 |
root |
1.2 |
behaviour - likewise changing anything else that would change the outcome, |
300 |
|
|
such as your effective user or group ID. |
301 |
root |
1.1 |
|
302 |
|
|
To avoid having to load L<Fcntl>, this module provides constants |
303 |
|
|
for C<O_RDONLY>, C<O_WRONLY>, C<O_RDWR>, C<O_CREAT>, C<O_EXCL>, |
304 |
|
|
C<O_TRUNC> and C<O_APPEND> - you can either access them directly |
305 |
|
|
(C<AnyEvent::IO::O_RDONLY>) or import them by specifying the C<:flags> |
306 |
|
|
import tag (see SYNOPSIS). |
307 |
|
|
|
308 |
root |
1.15 |
Example: securely open a file in F</var/tmp>, fail if it exists or is a symlink. |
309 |
|
|
|
310 |
|
|
use AnyEvent::IO qw(:flags); |
311 |
|
|
|
312 |
|
|
aio_open "/var/tmp/mytmp$$", O_CREAT | O_EXCL | O_RDWR, 0600, sub { |
313 |
|
|
my ($fh) = @_ |
314 |
|
|
or return AE::log error => "$! - denial of service attack?"; |
315 |
|
|
|
316 |
|
|
# now we have $fh |
317 |
|
|
}; |
318 |
|
|
|
319 |
root |
1.14 |
=item aio_close $fh, $cb->($success) |
320 |
root |
1.1 |
|
321 |
root |
1.9 |
Closes the file handle (yes, close can block your process indefinitely) |
322 |
|
|
and passes a true value to the callback on success. |
323 |
root |
1.1 |
|
324 |
root |
1.5 |
Due to idiosyncrasies in perl, instead of calling C<close>, the file |
325 |
root |
1.1 |
handle might get closed by C<dup2>'ing another file descriptor over |
326 |
|
|
it, that is, the C<$fh> might still be open, but can be closed safely |
327 |
|
|
afterwards and must not be used for anything. |
328 |
|
|
|
329 |
root |
1.15 |
Example: close a file handle, and dirty as we are, do not even bother |
330 |
|
|
to check for errors. |
331 |
|
|
|
332 |
|
|
aio_close $fh, sub { }; |
333 |
|
|
|
334 |
root |
1.14 |
=item aio_read $fh, $length, $cb->($data) |
335 |
root |
1.1 |
|
336 |
|
|
Tries to read C<$length> octets from the current position from C<$fh> and |
337 |
|
|
passes these bytes to C<$cb>. Otherwise the semantics are very much like |
338 |
root |
1.15 |
those of Perl's C<sysread>. |
339 |
root |
1.1 |
|
340 |
|
|
If less than C<$length> octets have been read, C<$data> will contain |
341 |
root |
1.5 |
only those bytes actually read. At EOF, C<$data> will be a zero-length |
342 |
root |
1.1 |
string. If an error occurs, then nothing is passed to the callback. |
343 |
|
|
|
344 |
root |
1.14 |
Obviously, multiple C<aio_read>'s or C<aio_write>'s at the same time on file |
345 |
root |
1.1 |
handles sharing the underlying open file description results in undefined |
346 |
root |
1.5 |
behaviour, due to sharing of the current file offset (and less obviously |
347 |
root |
1.1 |
so, because OS X is not thread safe and corrupts data when you try). |
348 |
|
|
|
349 |
root |
1.15 |
Example: read 128 octets from a file. |
350 |
|
|
|
351 |
|
|
aio_read $fh, 128, sub { |
352 |
|
|
my ($data) = @_ |
353 |
|
|
or return AE::log error "read from fh: $!"; |
354 |
|
|
|
355 |
|
|
if (length $data) { |
356 |
|
|
print "read ", length $data, " octets.\n"; |
357 |
|
|
} else { |
358 |
|
|
print "EOF\n"; |
359 |
|
|
} |
360 |
|
|
}; |
361 |
|
|
|
362 |
root |
1.14 |
=item aio_seek $fh, $offset, $whence, $callback->($offs) |
363 |
root |
1.11 |
|
364 |
root |
1.15 |
Seeks the filehandle to the new C<$offset>, similarly to Perl's |
365 |
root |
1.11 |
C<sysseek>. The C<$whence> are the traditional values (C<0> to count from |
366 |
root |
1.12 |
start, C<1> to count from the current position and C<2> to count from the |
367 |
|
|
end). |
368 |
root |
1.11 |
|
369 |
|
|
The resulting absolute offset will be passed to the callback on success. |
370 |
|
|
|
371 |
root |
1.15 |
Example: measure the size of the file in the old-fashioned way using seek. |
372 |
|
|
|
373 |
|
|
aio_seek $fh, 0, 2, sub { |
374 |
|
|
my ($size) = @_ |
375 |
|
|
or return AE::log error => "seek to end failed: $!"; |
376 |
|
|
|
377 |
|
|
# maybe we need to seek to the beginning again? |
378 |
|
|
aio_seek $fh, 0, 0, sub { |
379 |
|
|
# now we are hopefully at the beginning |
380 |
|
|
}; |
381 |
|
|
}; |
382 |
|
|
|
383 |
root |
1.14 |
=item aio_write $fh, $data, $cb->($length) |
384 |
root |
1.1 |
|
385 |
|
|
Tries to write the octets in C<$data> to the current position of C<$fh> |
386 |
|
|
and passes the actual number of bytes written to the C<$cb>. Otherwise the |
387 |
root |
1.15 |
semantics are very much like those of Perl's C<syswrite>. |
388 |
root |
1.1 |
|
389 |
|
|
If less than C<length $data> octets have been written, C<$length> will |
390 |
|
|
reflect that. If an error occurs, then nothing is passed to the callback. |
391 |
|
|
|
392 |
root |
1.14 |
Obviously, multiple C<aio_read>'s or C<aio_write>'s at the same time on file |
393 |
root |
1.1 |
handles sharing the underlying open file description results in undefined |
394 |
root |
1.15 |
behaviour, due to sharing of the current file offset (and less obviously |
395 |
root |
1.1 |
so, because OS X is not thread safe and corrupts data when you try). |
396 |
|
|
|
397 |
root |
1.14 |
=item aio_truncate $fh_or_path, $new_length, $cb->($success) |
398 |
root |
1.10 |
|
399 |
|
|
Calls C<truncate> on the path or perl file handle and passes a true value |
400 |
|
|
to the callback on success. |
401 |
|
|
|
402 |
root |
1.15 |
Example: truncate F</etc/passwd> to zero length - this only works on |
403 |
|
|
systems that support C<truncate>, should not be tried out for obvious |
404 |
|
|
reasons and debian will probably open yte another security bug about this |
405 |
|
|
example. |
406 |
|
|
|
407 |
|
|
aio_truncate "/etc/passwd", sub { |
408 |
|
|
@_ |
409 |
|
|
or return AE::log error => "/etc/passwd: $! - are you root enough?"; |
410 |
|
|
}; |
411 |
|
|
|
412 |
root |
1.14 |
=item aio_utime $fh_or_path, $atime, $mtime, $cb->($success) |
413 |
root |
1.10 |
|
414 |
|
|
Calls C<utime> on the path or perl file handle and passes a true value to |
415 |
|
|
the callback on success. |
416 |
|
|
|
417 |
|
|
The special case of both C<$atime> and C<$mtime> being C<undef> sets the |
418 |
|
|
times to the current time, on systems that support this. |
419 |
|
|
|
420 |
root |
1.15 |
Example: try to touch F<file>. |
421 |
|
|
|
422 |
|
|
aio_utime "file", undef, undef, sub { }; |
423 |
|
|
|
424 |
root |
1.14 |
=item aio_chown $fh_or_path, $uid, $gid, $cb->($success) |
425 |
root |
1.10 |
|
426 |
|
|
Calls C<chown> on the path or perl file handle and passes a true value to |
427 |
|
|
the callback on success. |
428 |
|
|
|
429 |
|
|
If C<$uid> or C<$gid> can be specified as C<undef>, in which case the |
430 |
root |
1.15 |
uid or gid of the file is not changed. This differs from Perl's C<chown> |
431 |
|
|
built-in, which wants C<-1> for this. |
432 |
|
|
|
433 |
|
|
Example: update the group of F<file> to 0 (root), but leave the owner alone. |
434 |
|
|
|
435 |
|
|
aio_chown "file", undef, 0, sub { |
436 |
|
|
@_ |
437 |
|
|
or return AE::log error => "chown 'file': $!"; |
438 |
|
|
}; |
439 |
root |
1.10 |
|
440 |
root |
1.14 |
=item aio_chmod $fh_or_path, $perms, $cb->($success) |
441 |
root |
1.10 |
|
442 |
|
|
Calls C<chmod> on the path or perl file handle and passes a true value to |
443 |
|
|
the callback on success. |
444 |
|
|
|
445 |
root |
1.15 |
Example: change F<file> to be user/group/world-readable, but leave the other flags |
446 |
|
|
alone. |
447 |
|
|
|
448 |
|
|
aio_stat "file", sub { |
449 |
|
|
@_ |
450 |
|
|
or return AE::log error => "file: $!"; |
451 |
|
|
|
452 |
|
|
aio_chmod "file", (stat _)[2] & 07777 | 00444, sub { }; |
453 |
|
|
}; |
454 |
|
|
|
455 |
root |
1.14 |
=item aio_stat $fh_or_path, $cb->($success) |
456 |
root |
1.1 |
|
457 |
root |
1.14 |
=item aio_lstat $path, $cb->($success) |
458 |
root |
1.1 |
|
459 |
root |
1.9 |
Calls C<stat> or C<lstat> on the path or perl file handle and passes a |
460 |
|
|
true value to the callback on success. |
461 |
root |
1.1 |
|
462 |
root |
1.15 |
The stat data will be available by C<stat>'ing the C<_> file handle |
463 |
root |
1.1 |
(e.g. C<-x _>, C<stat _> and so on). |
464 |
|
|
|
465 |
root |
1.15 |
Example: see if we can find the number of subdirectories of F</etc>. |
466 |
|
|
|
467 |
|
|
aio_stat "/etc", sub { |
468 |
|
|
@_ |
469 |
|
|
or return AE::log error => "/etc: $!"; |
470 |
|
|
|
471 |
|
|
(stat _)[3] >= 2 |
472 |
|
|
or return AE::log warn => "/etc has low link count - non-POSIX filesystem?"; |
473 |
|
|
|
474 |
|
|
print "/etc has ", (stat _)[3] - 2, " subdirectories.\n"; |
475 |
|
|
}; |
476 |
|
|
|
477 |
root |
1.14 |
=item aio_link $oldpath, $newpath, $cb->($success) |
478 |
root |
1.2 |
|
479 |
root |
1.9 |
Calls C<link> on the paths and passes a true value to the callback on |
480 |
|
|
success. |
481 |
root |
1.2 |
|
482 |
root |
1.15 |
Example: link "F<file> to F<file.bak>, then rename F<file.new> over F<file>, |
483 |
|
|
to atomically replace it. |
484 |
|
|
|
485 |
|
|
aio_link "file", "file.bak", sub { |
486 |
|
|
@_ |
487 |
|
|
or return AE::log error => "file: $!"; |
488 |
|
|
|
489 |
|
|
aio_rename "file.new", "file", sub { |
490 |
|
|
@_ |
491 |
|
|
or return AE::log error => "file.new: $!"; |
492 |
|
|
|
493 |
|
|
print "file atomically replaced by file.new, backup file.bak\n"; |
494 |
|
|
}; |
495 |
|
|
}; |
496 |
|
|
|
497 |
root |
1.14 |
=item aio_symlink $oldpath, $newpath, $cb->($success) |
498 |
root |
1.2 |
|
499 |
root |
1.9 |
Calls C<symlink> on the paths and passes a true value to the callback on |
500 |
|
|
success. |
501 |
root |
1.2 |
|
502 |
root |
1.15 |
Example: create a symlink "F<slink> containing "random data". |
503 |
|
|
|
504 |
|
|
aio_symlink "random data", "slink", sub { |
505 |
|
|
@_ |
506 |
|
|
or return AE::log error => "slink: $!"; |
507 |
|
|
}; |
508 |
|
|
|
509 |
root |
1.14 |
=item aio_readlink $path, $cb->($target) |
510 |
root |
1.3 |
|
511 |
root |
1.10 |
Calls C<readlink> on the paths and passes the link target string to the |
512 |
root |
1.9 |
callback. |
513 |
root |
1.3 |
|
514 |
root |
1.15 |
Example: read the symlink called Fyslink> and verify that it contains "random data". |
515 |
|
|
|
516 |
|
|
aio_readlink "slink", sub { |
517 |
|
|
my ($target) = @_ |
518 |
|
|
or return AE::log error => "slink: $!"; |
519 |
|
|
|
520 |
|
|
$target eq "random data" |
521 |
|
|
or AE::log critical => "omg, the world will end!"; |
522 |
|
|
}; |
523 |
|
|
|
524 |
root |
1.14 |
=item aio_rename $oldpath, $newpath, $cb->($success) |
525 |
root |
1.2 |
|
526 |
root |
1.9 |
Calls C<rename> on the paths and passes a true value to the callback on |
527 |
|
|
success. |
528 |
root |
1.2 |
|
529 |
root |
1.15 |
See C<aio_link> for an example. |
530 |
|
|
|
531 |
root |
1.14 |
=item aio_unlink $path, $cb->($success) |
532 |
root |
1.2 |
|
533 |
root |
1.9 |
Tries to unlink the object at C<$path> and passes a true value to the |
534 |
|
|
callback on success. |
535 |
root |
1.2 |
|
536 |
root |
1.15 |
Example: try to delete the file F<tmpfile.dat~>. |
537 |
|
|
|
538 |
|
|
aio_unlink "tmpfile.dat~", sub { }; |
539 |
|
|
|
540 |
root |
1.14 |
=item aio_mkdir $path, $perms, $cb->($success) |
541 |
root |
1.2 |
|
542 |
root |
1.9 |
Calls C<mkdir> on the path with the given permissions C<$perms> (when in |
543 |
|
|
doubt, C<0777> is a good value) and passes a true value to the callback on |
544 |
|
|
success. |
545 |
root |
1.2 |
|
546 |
root |
1.15 |
Example: try to create the directory F<subdir> and leave it to whoeveer |
547 |
|
|
comes after us to check whether it worked. |
548 |
|
|
|
549 |
|
|
aio_mkdir "subdir", 0777, sub { }; |
550 |
|
|
|
551 |
root |
1.14 |
=item aio_rmdir $path, $cb->($success) |
552 |
root |
1.2 |
|
553 |
root |
1.9 |
Tries to remove the directory at C<$path> and passes a true value to the |
554 |
|
|
callback on success. |
555 |
root |
1.2 |
|
556 |
root |
1.15 |
Example: try to remove the directory F<subdir> and don't give a damn if |
557 |
|
|
that fails. |
558 |
|
|
|
559 |
|
|
aio_rmdir "subdir", sub { }; |
560 |
|
|
|
561 |
root |
1.14 |
=item aio_readdir $path, $cb->(\@names) |
562 |
root |
1.4 |
|
563 |
|
|
Reads all filenames from the directory specified by C<$path> and passes |
564 |
|
|
them to the callback, as an array reference with the names (without a path |
565 |
|
|
prefix). The F<.> and F<..> names will be filtered out first. |
566 |
|
|
|
567 |
|
|
The ordering of the file names is undefined - backends that are capable |
568 |
|
|
of it (e.g. L<IO::AIO>) will return the ordering that most likely is |
569 |
|
|
fastest to C<stat> through, and furthermore put entries that likely are |
570 |
|
|
directories first in the array. |
571 |
|
|
|
572 |
|
|
If you need best performance in recursive directory traversal or when |
573 |
root |
1.5 |
looking at really big directories, you are advised to use L<IO::AIO> |
574 |
|
|
directly, specifically the C<aio_readdirx> and C<aio_scandir> functions, |
575 |
|
|
which have more options to tune performance. |
576 |
root |
1.4 |
|
577 |
root |
1.15 |
Example: recursively scan a directory hierarchy, silently skip diretcories |
578 |
|
|
we couldn't read and print all others. |
579 |
|
|
|
580 |
|
|
sub scan; |
581 |
|
|
sub scan { |
582 |
|
|
my ($path) = @_; |
583 |
|
|
|
584 |
|
|
aio_readdir $path, sub { |
585 |
|
|
my ($names) = @_ |
586 |
|
|
or return; |
587 |
|
|
|
588 |
|
|
print "$path\n"; |
589 |
|
|
|
590 |
|
|
for my $name (@$names) { |
591 |
|
|
aio_lstat "$path/$name", sub { |
592 |
|
|
scan "$path/$name" |
593 |
|
|
if -d _; |
594 |
|
|
}; |
595 |
|
|
} |
596 |
|
|
}; |
597 |
|
|
} |
598 |
|
|
|
599 |
|
|
scan "/etc"; |
600 |
|
|
|
601 |
root |
1.1 |
=back |
602 |
|
|
|
603 |
|
|
=head1 ENVIRONMENT VARIABLES |
604 |
|
|
|
605 |
|
|
See the description of C<PERL_ANYEVENT_IO_MODEL> in the L<AnyEvent> |
606 |
|
|
manpage. |
607 |
|
|
|
608 |
|
|
=head1 AUTHOR |
609 |
|
|
|
610 |
|
|
Marc Lehmann <schmorp@schmorp.de> |
611 |
|
|
http://home.schmorp.de/ |
612 |
|
|
|
613 |
|
|
=cut |
614 |
|
|
|
615 |
|
|
1 |
616 |
|
|
|