ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/IO-AIO/README
(Generate patch)

Comparing IO-AIO/README (file contents):
Revision 1.53 by root, Thu Oct 11 03:20:52 2012 UTC vs.
Revision 1.55 by root, Sat Jan 25 00:15:52 2014 UTC

… …
64 64
65 EXAMPLE 65 EXAMPLE
66 This is a simple example that uses the EV module and loads /etc/passwd 66 This is a simple example that uses the EV module and loads /etc/passwd
67 asynchronously: 67 asynchronously:
68 68
69 use Fcntl;
70 use EV; 69 use EV;
71 use IO::AIO; 70 use IO::AIO;
72 71
73 # register the IO::AIO callback with EV 72 # register the IO::AIO callback with EV
74 my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb; 73 my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
… …
530 namemax => 255, 529 namemax => 255,
531 frsize => 1024, 530 frsize => 1024,
532 fsid => 1810 531 fsid => 1810
533 } 532 }
534 533
535 Here is a (likely partial) list of fsid values used by Linux - it is 534 Here is a (likely partial - send me updates!) list of fsid values
536 safe to hardcode these when the $^O is "linux": 535 used by Linux - it is safe to hardcode these when $^O is "linux":
537 536
538 0x0000adf5 adfs 537 0x0000adf5 adfs
539 0x0000adff affs 538 0x0000adff affs
540 0x5346414f afs 539 0x5346414f afs
541 0x09041934 anon-inode filesystem 540 0x09041934 anon-inode filesystem
… …
692 the callback. If an error occurs, nothing or undef gets passed to 691 the callback. If an error occurs, nothing or undef gets passed to
693 the callback. 692 the callback.
694 693
695 aio_realpath $pathname, $callback->($path) 694 aio_realpath $pathname, $callback->($path)
696 Asynchronously make the path absolute and resolve any symlinks in 695 Asynchronously make the path absolute and resolve any symlinks in
697 $path. The resulting path only consists of directories (Same as 696 $path. The resulting path only consists of directories (same as
698 Cwd::realpath). 697 Cwd::realpath).
699 698
700 This request can be used to get the absolute path of the current 699 This request can be used to get the absolute path of the current
701 working directory by passing it a path of . (a single dot). 700 working directory by passing it a path of . (a single dot).
702 701
703 aio_rename $srcpath, $dstpath, $callback->($status) 702 aio_rename $srcpath, $dstpath, $callback->($status)
704 Asynchronously rename the object at $srcpath to $dstpath, just as 703 Asynchronously rename the object at $srcpath to $dstpath, just as
705 rename(2) and call the callback with the result code. 704 rename(2) and call the callback with the result code.
705
706 On systems that support the AIO::WD working directory abstraction
707 natively, the case "[$wd, "."]" as $srcpath is specialcased -
708 instead of failing, "rename" is called on the absolute path of $wd.
706 709
707 aio_mkdir $pathname, $mode, $callback->($status) 710 aio_mkdir $pathname, $mode, $callback->($status)
708 Asynchronously mkdir (create) a directory and call the callback with 711 Asynchronously mkdir (create) a directory and call the callback with
709 the result code. $mode will be modified by the umask at the time the 712 the result code. $mode will be modified by the umask at the time the
710 request is executed, so do not change your umask. 713 request is executed, so do not change your umask.
711 714
712 aio_rmdir $pathname, $callback->($status) 715 aio_rmdir $pathname, $callback->($status)
713 Asynchronously rmdir (delete) a directory and call the callback with 716 Asynchronously rmdir (delete) a directory and call the callback with
714 the result code. 717 the result code.
718
719 On systems that support the AIO::WD working directory abstraction
720 natively, the case "[$wd, "."]" is specialcased - instead of
721 failing, "rmdir" is called on the absolute path of $wd.
715 722
716 aio_readdir $pathname, $callback->($entries) 723 aio_readdir $pathname, $callback->($entries)
717 Unlike the POSIX call of the same name, "aio_readdir" reads an 724 Unlike the POSIX call of the same name, "aio_readdir" reads an
718 entire directory (i.e. opendir + readdir + closedir). The entries 725 entire directory (i.e. opendir + readdir + closedir). The entries
719 will not be sorted, and will NOT include the "." and ".." entries. 726 will not be sorted, and will NOT include the "." and ".." entries.
… …
942 949
943 It touches (reads or writes) all memory pages in the specified range 950 It touches (reads or writes) all memory pages in the specified range
944 inside the scalar. All caveats and parameters are the same as for 951 inside the scalar. All caveats and parameters are the same as for
945 "aio_msync", above, except for flags, which must be either 0 (which 952 "aio_msync", above, except for flags, which must be either 0 (which
946 reads all pages and ensures they are instantiated) or 953 reads all pages and ensures they are instantiated) or
947 "IO::AIO::MT_MODIFY", which modifies the memory page s(by reading 954 "IO::AIO::MT_MODIFY", which modifies the memory pages (by reading
948 and writing an octet from it, which dirties the page). 955 and writing an octet from it, which dirties the page).
949 956
950 aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status) 957 aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
951 This is a rather advanced IO::AIO call, which works best on 958 This is a rather advanced IO::AIO call, which works best on
952 mmap(2)ed scalars. 959 mmap(2)ed scalars.
… …
1153 will still point to the original directory. Most functions accepting a 1160 will still point to the original directory. Most functions accepting a
1154 pathname will use the directory fd on newer systems, and the string on 1161 pathname will use the directory fd on newer systems, and the string on
1155 older systems. Some functions (such as realpath) will always rely on the 1162 older systems. Some functions (such as realpath) will always rely on the
1156 string form of the pathname. 1163 string form of the pathname.
1157 1164
1158 So this fucntionality is mainly useful to get some protection against 1165 So this functionality is mainly useful to get some protection against
1159 "chdir", to easily get an absolute path out of a relative path for 1166 "chdir", to easily get an absolute path out of a relative path for
1160 future reference, and to speed up doing many operations in the same 1167 future reference, and to speed up doing many operations in the same
1161 directory (e.g. when stat'ing all files in a directory). 1168 directory (e.g. when stat'ing all files in a directory).
1162 1169
1163 The following functions implement this working directory abstraction: 1170 The following functions implement this working directory abstraction:
… …
1173 Since passing "undef" as working directory component of a pathname 1180 Since passing "undef" as working directory component of a pathname
1174 fails the request with "ENOENT", there is often no need for error 1181 fails the request with "ENOENT", there is often no need for error
1175 checking in the "aio_wd" callback, as future requests using the 1182 checking in the "aio_wd" callback, as future requests using the
1176 value will fail in the expected way. 1183 value will fail in the expected way.
1177 1184
1178 If this call isn't available because your OS lacks it or it couldn't
1179 be detected, it will be emulated by calling "fsync" instead.
1180
1181 IO::AIO::CWD 1185 IO::AIO::CWD
1182 This is a compiletime constant (object) that represents the process 1186 This is a compiletime constant (object) that represents the process
1183 current working directory. 1187 current working directory.
1184 1188
1185 Specifying this object as working directory object for a pathname is 1189 Specifying this object as working directory object for a pathname is
1186 as if the pathname would be specified directly, without a directory 1190 as if the pathname would be specified directly, without a directory
1187 object, e.g., these calls are functionally identical: 1191 object. For example, these calls are functionally identical:
1188 1192
1189 aio_stat "somefile", sub { ... }; 1193 aio_stat "somefile", sub { ... };
1190 aio_stat [IO::AIO::CWD, "somefile"], sub { ... }; 1194 aio_stat [IO::AIO::CWD, "somefile"], sub { ... };
1195
1196 To recover the path associated with an IO::AIO::WD object, you can use
1197 "aio_realpath":
1198
1199 aio_realpath $wd, sub {
1200 warn "path is $_[0]\n";
1201 };
1202
1203 Currently, "aio_statvfs" always, and "aio_rename" and "aio_rmdir"
1204 sometimes, fall back to using an absolue path.
1191 1205
1192 IO::AIO::REQ CLASS 1206 IO::AIO::REQ CLASS
1193 All non-aggregate "aio_*" functions return an object of this class when 1207 All non-aggregate "aio_*" functions return an object of this class when
1194 called in non-void context. 1208 called in non-void context.
1195 1209
… …
1347 results. 1361 results.
1348 1362
1349 See "poll_cb" for an example. 1363 See "poll_cb" for an example.
1350 1364
1351 IO::AIO::poll_cb 1365 IO::AIO::poll_cb
1352 Process some outstanding events on the result pipe. You have to call 1366 Process some requests that have reached the result phase (i.e. they
1367 have been executed but the results are not yet reported). You have
1368 to call this "regularly" to finish outstanding requests.
1369
1353 this regularly. Returns 0 if all events could be processed (or there 1370 Returns 0 if all events could be processed (or there were no events
1354 were no events to process), or -1 if it returned earlier for 1371 to process), or -1 if it returned earlier for whatever reason.
1355 whatever reason. Returns immediately when no events are outstanding. 1372 Returns immediately when no events are outstanding. The amount of
1356 The amount of events processed depends on the settings of 1373 events processed depends on the settings of "IO::AIO::max_poll_req",
1357 "IO::AIO::max_poll_req" and "IO::AIO::max_poll_time". 1374 "IO::AIO::max_poll_time" and "IO::AIO::max_outstanding".
1358 1375
1359 If not all requests were processed for whatever reason, the 1376 If not all requests were processed for whatever reason, the poll
1360 filehandle will still be ready when "poll_cb" returns, so normally 1377 file descriptor will still be ready when "poll_cb" returns, so
1361 you don't have to do anything special to have it called later. 1378 normally you don't have to do anything special to have it called
1379 later.
1362 1380
1363 Apart from calling "IO::AIO::poll_cb" when the event filehandle 1381 Apart from calling "IO::AIO::poll_cb" when the event filehandle
1364 becomes ready, it can be beneficial to call this function from loops 1382 becomes ready, it can be beneficial to call this function from loops
1365 which submit a lot of requests, to make sure the results get 1383 which submit a lot of requests, to make sure the results get
1366 processed when they become available and not just when the loop is 1384 processed when they become available and not just when the loop is
… …
1374 Event->io (fd => IO::AIO::poll_fileno, 1392 Event->io (fd => IO::AIO::poll_fileno,
1375 poll => 'r', async => 1, 1393 poll => 'r', async => 1,
1376 cb => \&IO::AIO::poll_cb); 1394 cb => \&IO::AIO::poll_cb);
1377 1395
1378 IO::AIO::poll_wait 1396 IO::AIO::poll_wait
1379 If there are any outstanding requests and none of them in the result 1397 Wait until either at least one request is in the result phase or no
1380 phase, wait till the result filehandle becomes ready for reading 1398 requests are outstanding anymore.
1381 (simply does a "select" on the filehandle. This is useful if you 1399
1382 want to synchronously wait for some requests to finish). 1400 This is useful if you want to synchronously wait for some requests
1401 to become ready, without actually handling them.
1383 1402
1384 See "nreqs" for an example. 1403 See "nreqs" for an example.
1385 1404
1386 IO::AIO::poll 1405 IO::AIO::poll
1387 Waits until some requests have been handled. 1406 Waits until some requests have been handled.
… …
1661 See the splice(2) manpage for details. 1680 See the splice(2) manpage for details.
1662 1681
1663 IO::AIO::tee $r_fh, $w_fh, $length, $flags 1682 IO::AIO::tee $r_fh, $w_fh, $length, $flags
1664 Calls the GNU/Linux tee(2) syscall, see it's manpage and the 1683 Calls the GNU/Linux tee(2) syscall, see it's manpage and the
1665 description for "IO::AIO::splice" above for details. 1684 description for "IO::AIO::splice" above for details.
1685
1686 $actual_size = IO::AIO::pipesize $r_fh[, $new_size]
1687 Attempts to query or change the pipe buffer size. Obviously works
1688 only on pipes, and currently works only on GNU/Linux systems, and
1689 fails with -1/"ENOSYS" everywhere else. If anybody knows how to
1690 influence pipe buffer size on other systems, drop me a note.
1666 1691
1667EVENT LOOP INTEGRATION 1692EVENT LOOP INTEGRATION
1668 It is recommended to use AnyEvent::AIO to integrate IO::AIO 1693 It is recommended to use AnyEvent::AIO to integrate IO::AIO
1669 automatically into many event loops: 1694 automatically into many event loops:
1670 1695

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines