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

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.83 by root, Fri Oct 27 20:11:58 2006 UTC vs.
Revision 1.86 by root, Sat Oct 28 23:32:29 2006 UTC

… …
50 50
51=head1 DESCRIPTION 51=head1 DESCRIPTION
52 52
53This module implements asynchronous I/O using whatever means your 53This module implements asynchronous I/O using whatever means your
54operating system supports. 54operating system supports.
55
56Asynchronous means that operations that can normally block your program
57(e.g. reading from disk) will be done asynchronously: the operation
58will still block, but you can do something else in the meantime. This
59is extremely useful for programs that need to stay interactive even
60when doing heavy I/O (GUI programs, high performance network servers
61etc.), but can also be used to easily do operations in parallel that are
62normally done sequentially, e.g. stat'ing many files, which is much faster
63on a RAID volume or over NFS when you do a number of stat operations
64concurrently.
65
66While this works on all types of file descriptors (for example sockets),
67using these functions on file descriptors that support nonblocking
68operation (again, sockets, pipes etc.) is very inefficient. Use an event
69loop for that (such as the L<Event|Event> module): IO::AIO will naturally
70fit into such an event loop itself.
55 71
56In this version, a number of threads are started that execute your 72In this version, a number of threads are started that execute your
57requests and signal their completion. You don't need thread support 73requests and signal their completion. You don't need thread support
58in perl, and the threads created by this module will not be visible 74in perl, and the threads created by this module will not be visible
59to perl. In the future, this module might make use of the native aio 75to perl. In the future, this module might make use of the native aio
60functions available on many operating systems. However, they are often 76functions available on many operating systems. However, they are often
61not well-supported or restricted (Linux doesn't allow them on normal 77not well-supported or restricted (GNU/Linux doesn't allow them on normal
62files currently, for example), and they would only support aio_read and 78files currently, for example), and they would only support aio_read and
63aio_write, so the remaining functionality would have to be implemented 79aio_write, so the remaining functionality would have to be implemented
64using threads anyway. 80using threads anyway.
65 81
66Although the module will work with in the presence of other (Perl-) 82Although the module will work with in the presence of other (Perl-)
67threads, it is currently not reentrant in any way, so use appropriate 83threads, it is currently not reentrant in any way, so use appropriate
68locking yourself, always call C<poll_cb> from within the same thread, or 84locking yourself, always call C<poll_cb> from within the same thread, or
69never call C<poll_cb> (or other C<aio_> functions) recursively. 85never call C<poll_cb> (or other C<aio_> functions) recursively.
70 86
87=head2 EXAMPLE
88
89This is a simple example that uses the Event module and loads
90F</etc/passwd> asynchronously:
91
92 use Fcntl;
93 use Event;
94 use IO::AIO;
95
96 # register the IO::AIO callback with Event
97 Event->io (fd => IO::AIO::poll_fileno,
98 poll => 'r',
99 cb => \&IO::AIO::poll_cb);
100
101 # queue the request to open /etc/passwd
102 aio_open "/etc/passwd", O_RDONLY, 0, sub {
103 my $fh = $_[0]
104 or die "error while opening: $!";
105
106 # stat'ing filehandles is generally non-blocking
107 my $size = -s $fh;
108
109 # queue a request to read the file
110 my $contents;
111 aio_read $fh, 0, $size, $contents, 0, sub {
112 $_[0] == $size
113 or die "short read: $!";
114
115 close $fh;
116
117 # file contents now in $contents
118 print $contents;
119
120 # exit event loop and program
121 Event::unloop;
122 };
123 };
124
125 # possibly queue up other requests, or open GUI windows,
126 # check for sockets etc. etc.
127
128 # process events as long as there are some:
129 Event::loop;
130
71=head1 REQUEST ANATOMY AND LIFETIME 131=head1 REQUEST ANATOMY AND LIFETIME
72 132
73Every C<aio_*> function creates a request. which is a C data structure not 133Every C<aio_*> function creates a request. which is a C data structure not
74directly visible to Perl. 134directly visible to Perl.
75 135
… …
126use strict 'vars'; 186use strict 'vars';
127 187
128use base 'Exporter'; 188use base 'Exporter';
129 189
130BEGIN { 190BEGIN {
131 our $VERSION = '2.0'; 191 our $VERSION = '2.1';
132 192
133 our @AIO_REQ = qw(aio_sendfile aio_read aio_write aio_open aio_close aio_stat 193 our @AIO_REQ = qw(aio_sendfile aio_read aio_write aio_open aio_close aio_stat
134 aio_lstat aio_unlink aio_rmdir aio_readdir aio_scandir aio_symlink 194 aio_lstat aio_unlink aio_rmdir aio_readdir aio_scandir aio_symlink
135 aio_fsync aio_fdatasync aio_readahead aio_rename aio_link aio_move 195 aio_fsync aio_fdatasync aio_readahead aio_rename aio_link aio_move
136 aio_copy aio_group aio_nop aio_mknod); 196 aio_copy aio_group aio_nop aio_mknod);
137 our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice)); 197 our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice));
138 our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush 198 our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush
139 min_parallel max_parallel nreqs nready npending); 199 min_parallel max_parallel max_idle
200 nreqs nready npending nthreads
201 max_poll_time max_poll_reqs);
140 202
141 @IO::AIO::GRP::ISA = 'IO::AIO::REQ'; 203 @IO::AIO::GRP::ISA = 'IO::AIO::REQ';
142 204
143 require XSLoader; 205 require XSLoader;
144 XSLoader::load ("IO::AIO", $VERSION); 206 XSLoader::load ("IO::AIO", $VERSION);
… …
331Asynchronously unlink (delete) a file and call the callback with the 393Asynchronously unlink (delete) a file and call the callback with the
332result code. 394result code.
333 395
334=item aio_mknod $path, $mode, $dev, $callback->($status) 396=item aio_mknod $path, $mode, $dev, $callback->($status)
335 397
398[EXPERIMENTAL]
399
336Asynchronously create a device node (or fifo). See mknod(2). 400Asynchronously create a device node (or fifo). See mknod(2).
337 401
338The only portable (POSIX) way of calling this function is: 402The only (POSIX-) portable way of calling this function is:
339 403
340 aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ... 404 aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ...
341 405
342=item aio_link $srcpath, $dstpath, $callback->($status) 406=item aio_link $srcpath, $dstpath, $callback->($status)
343 407
… …
829 893
830=back 894=back
831 895
832=head2 SUPPORT FUNCTIONS 896=head2 SUPPORT FUNCTIONS
833 897
898=head3 EVENT PROCESSING AND EVENT LOOP INTEGRATION
899
834=over 4 900=over 4
835 901
836=item $fileno = IO::AIO::poll_fileno 902=item $fileno = IO::AIO::poll_fileno
837 903
838Return the I<request result pipe file descriptor>. This filehandle must be 904Return the I<request result pipe file descriptor>. This filehandle must be
… …
842 908
843See C<poll_cb> for an example. 909See C<poll_cb> for an example.
844 910
845=item IO::AIO::poll_cb 911=item IO::AIO::poll_cb
846 912
847Process all outstanding events on the result pipe. You have to call this 913Process some outstanding events on the result pipe. You have to call this
848regularly. Returns the number of events processed. Returns immediately 914regularly. Returns the number of events processed. Returns immediately
849when no events are outstanding. 915when no events are outstanding. The amount of events processed depends on
916the settings of C<IO::AIO::max_poll_req> and C<IO::AIO::max_poll_time>.
850 917
851If not all requests were processed for whatever reason, the filehandle 918If not all requests were processed for whatever reason, the filehandle
852will still be ready when C<poll_cb> returns. 919will still be ready when C<poll_cb> returns.
853 920
854Example: Install an Event watcher that automatically calls 921Example: Install an Event watcher that automatically calls
… …
856 923
857 Event->io (fd => IO::AIO::poll_fileno, 924 Event->io (fd => IO::AIO::poll_fileno,
858 poll => 'r', async => 1, 925 poll => 'r', async => 1,
859 cb => \&IO::AIO::poll_cb); 926 cb => \&IO::AIO::poll_cb);
860 927
861=item IO::AIO::poll_some $max_requests 928=item IO::AIO::max_poll_reqs $nreqs
862 929
863Similar to C<poll_cb>, but only processes up to C<$max_requests> requests 930=item IO::AIO::max_poll_time $seconds
864at a time.
865 931
866Useful if you want to ensure some level of interactiveness when perl is 932These set the maximum number of requests (default C<0>, meaning infinity)
867not fast enough to process all requests in time. 933that are being processed by C<IO::AIO::poll_cb> in one call, respectively
934the maximum amount of time (default C<0>, meaning infinity) spent in
935C<IO::AIO::poll_cb> to process requests (more correctly the mininum amount
936of time C<poll_cb> is allowed to use).
937
938Setting these is useful if you want to ensure some level of
939interactiveness when perl is not fast enough to process all requests in
940time.
941
942For interactive programs, values such as C<0.01> to C<0.1> should be fine.
868 943
869Example: Install an Event watcher that automatically calls 944Example: Install an Event watcher that automatically calls
870IO::AIO::poll_some with low priority, to ensure that other parts of the 945IO::AIO::poll_some with low priority, to ensure that other parts of the
871program get the CPU sometimes even under high AIO load. 946program get the CPU sometimes even under high AIO load.
872 947
948 # try not to spend much more than 0.1s in poll_cb
949 IO::AIO::max_poll_time 0.1;
950
951 # use a low priority so other tasks have priority
873 Event->io (fd => IO::AIO::poll_fileno, 952 Event->io (fd => IO::AIO::poll_fileno,
874 poll => 'r', nice => 1, 953 poll => 'r', nice => 1,
875 cb => sub { IO::AIO::poll_some 256 }); 954 cb => &IO::AIO::poll_cb);
876 955
877=item IO::AIO::poll_wait 956=item IO::AIO::poll_wait
878 957
879Wait till the result filehandle becomes ready for reading (simply does a 958Wait till the result filehandle becomes ready for reading (simply does a
880C<select> on the filehandle. This is useful if you want to synchronously wait 959C<select> on the filehandle. This is useful if you want to synchronously
881for some requests to finish). 960wait for some requests to finish).
882 961
883See C<nreqs> for an example. 962See C<nreqs> for an example.
884 963
964=item IO::AIO::poll
965
966Waits until some requests have been handled.
967
968Strictly equivalent to:
969
970 IO::AIO::poll_wait, IO::AIO::poll_cb
971 if IO::AIO::nreqs;
972
885=item IO::AIO::nreqs 973=item IO::AIO::flush
886 974
887Returns the number of requests currently in the ready, execute or pending 975Wait till all outstanding AIO requests have been handled.
888states (i.e. for which their callback has not been invoked yet).
889 976
890Example: wait till there are no outstanding requests anymore: 977Strictly equivalent to:
891 978
892 IO::AIO::poll_wait, IO::AIO::poll_cb 979 IO::AIO::poll_wait, IO::AIO::poll_cb
893 while IO::AIO::nreqs; 980 while IO::AIO::nreqs;
894 981
895=item IO::AIO::nready 982=head3 CONTROLLING THE NUMBER OF THREADS
896
897Returns the number of requests currently in the ready state (not yet
898executed).
899
900=item IO::AIO::npending
901
902Returns the number of requests currently in the pending state (executed,
903but not yet processed by poll_cb).
904
905=item IO::AIO::flush
906
907Wait till all outstanding AIO requests have been handled.
908
909Strictly equivalent to:
910
911 IO::AIO::poll_wait, IO::AIO::poll_cb
912 while IO::AIO::nreqs;
913
914=item IO::AIO::poll
915
916Waits until some requests have been handled.
917
918Strictly equivalent to:
919
920 IO::AIO::poll_wait, IO::AIO::poll_cb
921 if IO::AIO::nreqs;
922 983
923=item IO::AIO::min_parallel $nthreads 984=item IO::AIO::min_parallel $nthreads
924 985
925Set the minimum number of AIO threads to C<$nthreads>. The current 986Set the minimum number of AIO threads to C<$nthreads>. The current
926default is C<8>, which means eight asynchronous operations can execute 987default is C<8>, which means eight asynchronous operations can execute
927concurrently at any one time (the number of outstanding requests, 988concurrently at any one time (the number of outstanding requests,
928however, is unlimited). 989however, is unlimited).
929 990
930IO::AIO starts threads only on demand, when an AIO request is queued and 991IO::AIO starts threads only on demand, when an AIO request is queued and
931no free thread exists. 992no free thread exists. Please note that queueing up a hundred requests can
993create demand for a hundred threads, even if it turns out that everything
994is in the cache and could have been processed faster by a single thread.
932 995
933It is recommended to keep the number of threads relatively low, as some 996It is recommended to keep the number of threads relatively low, as some
934Linux kernel versions will scale negatively with the number of threads 997Linux kernel versions will scale negatively with the number of threads
935(higher parallelity => MUCH higher latency). With current Linux 2.6 998(higher parallelity => MUCH higher latency). With current Linux 2.6
936versions, 4-32 threads should be fine. 999versions, 4-32 threads should be fine.
… …
950This module automatically runs C<max_parallel 0> at program end, to ensure 1013This module automatically runs C<max_parallel 0> at program end, to ensure
951that all threads are killed and that there are no outstanding requests. 1014that all threads are killed and that there are no outstanding requests.
952 1015
953Under normal circumstances you don't need to call this function. 1016Under normal circumstances you don't need to call this function.
954 1017
1018=item IO::AIO::max_idle $nthreads
1019
1020Limit the number of threads (default: 4) that are allowed to idle (i.e.,
1021threads that did not get a request to process within 10 seconds). That
1022means if a thread becomes idle while C<$nthreads> other threads are also
1023idle, it will free its resources and exit.
1024
1025This is useful when you allow a large number of threads (e.g. 100 or 1000)
1026to allow for extremely high load situations, but want to free resources
1027under normal circumstances (1000 threads can easily consume 30MB of RAM).
1028
1029The default is probably ok in most situations, especially if thread
1030creation is fast. If thread creation is very slow on your system you might
1031want to use larger values.
1032
955=item $oldmaxreqs = IO::AIO::max_outstanding $maxreqs 1033=item $oldmaxreqs = IO::AIO::max_outstanding $maxreqs
956 1034
957This is a very bad function to use in interactive programs because it 1035This is a very bad function to use in interactive programs because it
958blocks, and a bad way to reduce concurrency because it is inexact: Better 1036blocks, and a bad way to reduce concurrency because it is inexact: Better
959use an C<aio_group> together with a feed callback. 1037use an C<aio_group> together with a feed callback.
… …
968 1046
969You can still queue as many requests as you want. Therefore, 1047You can still queue as many requests as you want. Therefore,
970C<max_oustsanding> is mainly useful in simple scripts (with low values) or 1048C<max_oustsanding> is mainly useful in simple scripts (with low values) or
971as a stop gap to shield against fatal memory overflow (with large values). 1049as a stop gap to shield against fatal memory overflow (with large values).
972 1050
1051=head3 STATISTICAL INFORMATION
1052
1053=item IO::AIO::nreqs
1054
1055Returns the number of requests currently in the ready, execute or pending
1056states (i.e. for which their callback has not been invoked yet).
1057
1058Example: wait till there are no outstanding requests anymore:
1059
1060 IO::AIO::poll_wait, IO::AIO::poll_cb
1061 while IO::AIO::nreqs;
1062
1063=item IO::AIO::nready
1064
1065Returns the number of requests currently in the ready state (not yet
1066executed).
1067
1068=item IO::AIO::npending
1069
1070Returns the number of requests currently in the pending state (executed,
1071but not yet processed by poll_cb).
1072
973=back 1073=back
974 1074
975=cut 1075=cut
976 1076
977# support function to convert a fd into a perl filehandle 1077# support function to convert a fd into a perl filehandle
… …
991} 1091}
992 1092
993min_parallel 8; 1093min_parallel 8;
994 1094
995END { 1095END {
1096 min_parallel 1;
996 flush; 1097 flush;
997}; 1098};
998 1099
9991; 11001;
1000 1101

Diff Legend

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