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

Comparing IO-AIO/README (file contents):
Revision 1.18 by root, Thu Oct 26 16:28:33 2006 UTC vs.
Revision 1.19 by root, Sun Oct 29 01:03:13 2006 UTC

… …
47 \&IO::AIO::poll_cb); 47 \&IO::AIO::poll_cb);
48 48
49DESCRIPTION 49DESCRIPTION
50 This module implements asynchronous I/O using whatever means your 50 This module implements asynchronous I/O using whatever means your
51 operating system supports. 51 operating system supports.
52
53 Asynchronous means that operations that can normally block your program
54 (e.g. reading from disk) will be done asynchronously: the operation will
55 still block, but you can do something else in the meantime. This is
56 extremely useful for programs that need to stay interactive even when
57 doing heavy I/O (GUI programs, high performance network servers etc.),
58 but can also be used to easily do operations in parallel that are
59 normally done sequentially, e.g. stat'ing many files, which is much
60 faster on a RAID volume or over NFS when you do a number of stat
61 operations concurrently.
62
63 While this works on all types of file descriptors (for example sockets),
64 using these functions on file descriptors that support nonblocking
65 operation (again, sockets, pipes etc.) is very inefficient. Use an event
66 loop for that (such as the Event module): IO::AIO will naturally fit
67 into such an event loop itself.
52 68
53 In this version, a number of threads are started that execute your 69 In this version, a number of threads are started that execute your
54 requests and signal their completion. You don't need thread support in 70 requests and signal their completion. You don't need thread support in
55 perl, and the threads created by this module will not be visible to 71 perl, and the threads created by this module will not be visible to
56 perl. In the future, this module might make use of the native aio 72 perl. In the future, this module might make use of the native aio
57 functions available on many operating systems. However, they are often 73 functions available on many operating systems. However, they are often
58 not well-supported or restricted (Linux doesn't allow them on normal 74 not well-supported or restricted (GNU/Linux doesn't allow them on normal
59 files currently, for example), and they would only support aio_read and 75 files currently, for example), and they would only support aio_read and
60 aio_write, so the remaining functionality would have to be implemented 76 aio_write, so the remaining functionality would have to be implemented
61 using threads anyway. 77 using threads anyway.
62 78
63 Although the module will work with in the presence of other (Perl-) 79 Although the module will work with in the presence of other (Perl-)
64 threads, it is currently not reentrant in any way, so use appropriate 80 threads, it is currently not reentrant in any way, so use appropriate
65 locking yourself, always call "poll_cb" from within the same thread, or 81 locking yourself, always call "poll_cb" from within the same thread, or
66 never call "poll_cb" (or other "aio_" functions) recursively. 82 never call "poll_cb" (or other "aio_" functions) recursively.
83
84 EXAMPLE
85 This is a simple example that uses the Event module and loads
86 /etc/passwd asynchronously:
87
88 use Fcntl;
89 use Event;
90 use IO::AIO;
91
92 # register the IO::AIO callback with Event
93 Event->io (fd => IO::AIO::poll_fileno,
94 poll => 'r',
95 cb => \&IO::AIO::poll_cb);
96
97 # queue the request to open /etc/passwd
98 aio_open "/etc/passwd", O_RDONLY, 0, sub {
99 my $fh = $_[0]
100 or die "error while opening: $!";
101
102 # stat'ing filehandles is generally non-blocking
103 my $size = -s $fh;
104
105 # queue a request to read the file
106 my $contents;
107 aio_read $fh, 0, $size, $contents, 0, sub {
108 $_[0] == $size
109 or die "short read: $!";
110
111 close $fh;
112
113 # file contents now in $contents
114 print $contents;
115
116 # exit event loop and program
117 Event::unloop;
118 };
119 };
120
121 # possibly queue up other requests, or open GUI windows,
122 # check for sockets etc. etc.
123
124 # process events as long as there are some:
125 Event::loop;
67 126
68REQUEST ANATOMY AND LIFETIME 127REQUEST ANATOMY AND LIFETIME
69 Every "aio_*" function creates a request. which is a C data structure 128 Every "aio_*" function creates a request. which is a C data structure
70 not directly visible to Perl. 129 not directly visible to Perl.
71 130
… …
107 anymore (except possibly for the Perl object, but its connection to 166 anymore (except possibly for the Perl object, but its connection to
108 the actual aio request is severed and calling its methods will 167 the actual aio request is severed and calling its methods will
109 either do nothing or result in a runtime error). 168 either do nothing or result in a runtime error).
110 169
111FUNCTIONS 170FUNCTIONS
112 AIO FUNCTIONS 171 AIO REQUEST FUNCTIONS
113 All the "aio_*" calls are more or less thin wrappers around the 172 All the "aio_*" calls are more or less thin wrappers around the
114 syscall with the same name (sans "aio_"). The arguments are similar 173 syscall with the same name (sans "aio_"). The arguments are similar
115 or identical, and they all accept an additional (and optional) 174 or identical, and they all accept an additional (and optional)
116 $callback argument which must be a code reference. This code 175 $callback argument which must be a code reference. This code
117 reference will get called with the syscall return code (e.g. most 176 reference will get called with the syscall return code (e.g. most
… …
120 executed asynchronously. 179 executed asynchronously.
121 180
122 All functions expecting a filehandle keep a copy of the filehandle 181 All functions expecting a filehandle keep a copy of the filehandle
123 internally until the request has finished. 182 internally until the request has finished.
124 183
125 All requests return objects of type IO::AIO::REQ that allow further 184 All functions return request objects of type IO::AIO::REQ that allow
126 manipulation of those requests while they are in-flight. 185 further manipulation of those requests while they are in-flight.
127 186
128 The pathnames you pass to these routines *must* be absolute and 187 The pathnames you pass to these routines *must* be absolute and
129 encoded in byte form. The reason for the former is that at the time 188 encoded as octets. The reason for the former is that at the time the
130 the request is being executed, the current working directory could 189 request is being executed, the current working directory could have
131 have changed. Alternatively, you can make sure that you never change 190 changed. Alternatively, you can make sure that you never change the
132 the current working directory. 191 current working directory anywhere in the program and then use
192 relative paths.
133 193
134 To encode pathnames to byte form, either make sure you either: a) 194 To encode pathnames as octets, either make sure you either: a)
135 always pass in filenames you got from outside (command line, readdir 195 always pass in filenames you got from outside (command line, readdir
136 etc.), b) are ASCII or ISO 8859-1, c) use the Encode module and 196 etc.) without tinkering, b) are ASCII or ISO 8859-1, c) use the
137 encode your pathnames to the locale (or other) encoding in effect in 197 Encode module and encode your pathnames to the locale (or other)
138 the user environment, d) use Glib::filename_from_unicode on unicode 198 encoding in effect in the user environment, d) use
139 filenames or e) use something else. 199 Glib::filename_from_unicode on unicode filenames or e) use something
200 else to ensure your scalar has the correct contents.
201
202 This works, btw. independent of the internal UTF-8 bit, which
203 IO::AIO handles correctly wether it is set or not.
140 204
141 $prev_pri = aioreq_pri [$pri] 205 $prev_pri = aioreq_pri [$pri]
142 Returns the priority value that would be used for the next 206 Returns the priority value that would be used for the next
143 request and, if $pri is given, sets the priority for the next 207 request and, if $pri is given, sets the priority for the next
144 aio request. 208 aio request.
… …
165 }; 229 };
166 }; 230 };
167 231
168 aioreq_nice $pri_adjust 232 aioreq_nice $pri_adjust
169 Similar to "aioreq_pri", but subtracts the given value from the 233 Similar to "aioreq_pri", but subtracts the given value from the
170 current priority, so effects are cumulative. 234 current priority, so the effect is cumulative.
171 235
172 aio_open $pathname, $flags, $mode, $callback->($fh) 236 aio_open $pathname, $flags, $mode, $callback->($fh)
173 Asynchronously open or create a file and call the callback with 237 Asynchronously open or create a file and call the callback with
174 a newly created filehandle for the file. 238 a newly created filehandle for the file.
175 239
… …
224 288
225 aio_read $fh, 7, 15, $buffer, 0, sub { 289 aio_read $fh, 7, 15, $buffer, 0, sub {
226 $_[0] > 0 or die "read error: $!"; 290 $_[0] > 0 or die "read error: $!";
227 print "read $_[0] bytes: <$buffer>\n"; 291 print "read $_[0] bytes: <$buffer>\n";
228 }; 292 };
229
230 aio_move $srcpath, $dstpath, $callback->($status)
231 Try to move the *file* (directories not supported as either
232 source or destination) from $srcpath to $dstpath and call the
233 callback with the 0 (error) or -1 ok.
234
235 This is a composite request that tries to rename(2) the file
236 first. If rename files with "EXDEV", it creates the destination
237 file with mode 0200 and copies the contents of the source file
238 into it using "aio_sendfile", followed by restoring atime,
239 mtime, access mode and uid/gid, in that order, and unlinking the
240 $srcpath.
241
242 If an error occurs, the partial destination file will be
243 unlinked, if possible, except when setting atime, mtime, access
244 mode and uid/gid, where errors are being ignored.
245 293
246 aio_sendfile $out_fh, $in_fh, $in_offset, $length, 294 aio_sendfile $out_fh, $in_fh, $in_offset, $length,
247 $callback->($retval) 295 $callback->($retval)
248 Tries to copy $length bytes from $in_fh to $out_fh. It starts 296 Tries to copy $length bytes from $in_fh to $out_fh. It starts
249 reading at byte offset $in_offset, and starts writing at the 297 reading at byte offset $in_offset, and starts writing at the
… …
306 354
307 aio_unlink $pathname, $callback->($status) 355 aio_unlink $pathname, $callback->($status)
308 Asynchronously unlink (delete) a file and call the callback with 356 Asynchronously unlink (delete) a file and call the callback with
309 the result code. 357 the result code.
310 358
359 aio_mknod $path, $mode, $dev, $callback->($status)
360 [EXPERIMENTAL]
361
362 Asynchronously create a device node (or fifo). See mknod(2).
363
364 The only (POSIX-) portable way of calling this function is:
365
366 aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ...
367
311 aio_link $srcpath, $dstpath, $callback->($status) 368 aio_link $srcpath, $dstpath, $callback->($status)
312 Asynchronously create a new link to the existing object at 369 Asynchronously create a new link to the existing object at
313 $srcpath at the path $dstpath and call the callback with the 370 $srcpath at the path $dstpath and call the callback with the
314 result code. 371 result code.
315 372
… …
332 entries will not be sorted, and will NOT include the "." and 389 entries will not be sorted, and will NOT include the "." and
333 ".." entries. 390 ".." entries.
334 391
335 The callback a single argument which is either "undef" or an 392 The callback a single argument which is either "undef" or an
336 array-ref with the filenames. 393 array-ref with the filenames.
394
395 aio_copy $srcpath, $dstpath, $callback->($status)
396 Try to copy the *file* (directories not supported as either
397 source or destination) from $srcpath to $dstpath and call the
398 callback with the 0 (error) or -1 ok.
399
400 This is a composite request that it creates the destination file
401 with mode 0200 and copies the contents of the source file into
402 it using "aio_sendfile", followed by restoring atime, mtime,
403 access mode and uid/gid, in that order.
404
405 If an error occurs, the partial destination file will be
406 unlinked, if possible, except when setting atime, mtime, access
407 mode and uid/gid, where errors are being ignored.
408
409 aio_move $srcpath, $dstpath, $callback->($status)
410 Try to move the *file* (directories not supported as either
411 source or destination) from $srcpath to $dstpath and call the
412 callback with the 0 (error) or -1 ok.
413
414 This is a composite request that tries to rename(2) the file
415 first. If rename files with "EXDEV", it copies the file with
416 "aio_copy" and, if that is successful, unlinking the $srcpath.
337 417
338 aio_scandir $path, $maxreq, $callback->($dirs, $nondirs) 418 aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)
339 Scans a directory (similar to "aio_readdir") but additionally 419 Scans a directory (similar to "aio_readdir") but additionally
340 tries to efficiently separate the entries of directory $path 420 tries to efficiently separate the entries of directory $path
341 into two sets of names, directories you can recurse into 421 into two sets of names, directories you can recurse into
… …
343 else, including symlinks to directories). 423 else, including symlinks to directories).
344 424
345 "aio_scandir" is a composite request that creates of many sub 425 "aio_scandir" is a composite request that creates of many sub
346 requests_ $maxreq specifies the maximum number of outstanding 426 requests_ $maxreq specifies the maximum number of outstanding
347 aio requests that this function generates. If it is "<= 0", then 427 aio requests that this function generates. If it is "<= 0", then
348 a suitable default will be chosen (currently 6). 428 a suitable default will be chosen (currently 4).
349 429
350 On error, the callback is called without arguments, otherwise it 430 On error, the callback is called without arguments, otherwise it
351 receives two array-refs with path-relative entry names. 431 receives two array-refs with path-relative entry names.
352 432
353 Example: 433 Example:
… …
584 whenever the group contains less than this many requests. 664 whenever the group contains less than this many requests.
585 665
586 Setting the limit to 0 will pause the feeding process. 666 Setting the limit to 0 will pause the feeding process.
587 667
588 SUPPORT FUNCTIONS 668 SUPPORT FUNCTIONS
669 EVENT PROCESSING AND EVENT LOOP INTEGRATION
589 $fileno = IO::AIO::poll_fileno 670 $fileno = IO::AIO::poll_fileno
590 Return the *request result pipe file descriptor*. This 671 Return the *request result pipe file descriptor*. This
591 filehandle must be polled for reading by some mechanism outside 672 filehandle must be polled for reading by some mechanism outside
592 this module (e.g. Event or select, see below or the SYNOPSIS). 673 this module (e.g. Event or select, see below or the SYNOPSIS).
593 If the pipe becomes readable you have to call "poll_cb" to check 674 If the pipe becomes readable you have to call "poll_cb" to check
594 the results. 675 the results.
595 676
596 See "poll_cb" for an example. 677 See "poll_cb" for an example.
597 678
598 IO::AIO::poll_cb 679 IO::AIO::poll_cb
599 Process all outstanding events on the result pipe. You have to 680 Process some outstanding events on the result pipe. You have to
600 call this regularly. Returns the number of events processed. 681 call this regularly. Returns the number of events processed.
601 Returns immediately when no events are outstanding. 682 Returns immediately when no events are outstanding. The amount
683 of events processed depends on the settings of
684 "IO::AIO::max_poll_req" and "IO::AIO::max_poll_time".
602 685
603 If not all requests were processed for whatever reason, the 686 If not all requests were processed for whatever reason, the
604 filehandle will still be ready when "poll_cb" returns. 687 filehandle will still be ready when "poll_cb" returns.
605 688
606 Example: Install an Event watcher that automatically calls 689 Example: Install an Event watcher that automatically calls
… …
608 691
609 Event->io (fd => IO::AIO::poll_fileno, 692 Event->io (fd => IO::AIO::poll_fileno,
610 poll => 'r', async => 1, 693 poll => 'r', async => 1,
611 cb => \&IO::AIO::poll_cb); 694 cb => \&IO::AIO::poll_cb);
612 695
613 IO::AIO::poll_some $max_requests 696 IO::AIO::max_poll_reqs $nreqs
614 Similar to "poll_cb", but only processes up to $max_requests 697 IO::AIO::max_poll_time $seconds
698 These set the maximum number of requests (default 0, meaning
699 infinity) that are being processed by "IO::AIO::poll_cb" in one
700 call, respectively the maximum amount of time (default 0,
701 meaning infinity) spent in "IO::AIO::poll_cb" to process
702 requests (more correctly the mininum amount of time "poll_cb" is
703 allowed to use).
704
705 Setting these is useful if you want to ensure some level of
706 interactiveness when perl is not fast enough to process all
615 requests at a time. 707 requests in time.
616 708
617 Useful if you want to ensure some level of interactiveness when 709 For interactive programs, values such as 0.01 to 0.1 should be
618 perl is not fast enough to process all requests in time. 710 fine.
619 711
620 Example: Install an Event watcher that automatically calls 712 Example: Install an Event watcher that automatically calls
621 IO::AIO::poll_some with low priority, to ensure that other parts 713 IO::AIO::poll_some with low priority, to ensure that other parts
622 of the program get the CPU sometimes even under high AIO load. 714 of the program get the CPU sometimes even under high AIO load.
623 715
716 # try not to spend much more than 0.1s in poll_cb
717 IO::AIO::max_poll_time 0.1;
718
719 # use a low priority so other tasks have priority
624 Event->io (fd => IO::AIO::poll_fileno, 720 Event->io (fd => IO::AIO::poll_fileno,
625 poll => 'r', nice => 1, 721 poll => 'r', nice => 1,
626 cb => sub { IO::AIO::poll_some 256 }); 722 cb => &IO::AIO::poll_cb);
627 723
628 IO::AIO::poll_wait 724 IO::AIO::poll_wait
629 Wait till the result filehandle becomes ready for reading 725 Wait till the result filehandle becomes ready for reading
630 (simply does a "select" on the filehandle. This is useful if you 726 (simply does a "select" on the filehandle. This is useful if you
631 want to synchronously wait for some requests to finish). 727 want to synchronously wait for some requests to finish).
632 728
633 See "nreqs" for an example. 729 See "nreqs" for an example.
634 730
731 IO::AIO::poll
732 Waits until some requests have been handled.
733
734 Strictly equivalent to:
735
736 IO::AIO::poll_wait, IO::AIO::poll_cb
737 if IO::AIO::nreqs;
738
635 IO::AIO::nreqs 739 IO::AIO::flush
636 Returns the number of requests currently in the ready, execute 740 Wait till all outstanding AIO requests have been handled.
637 or pending states (i.e. for which their callback has not been
638 invoked yet).
639 741
640 Example: wait till there are no outstanding requests anymore: 742 Strictly equivalent to:
641 743
642 IO::AIO::poll_wait, IO::AIO::poll_cb 744 IO::AIO::poll_wait, IO::AIO::poll_cb
643 while IO::AIO::nreqs; 745 while IO::AIO::nreqs;
644 746
645 IO::AIO::nready 747 CONTROLLING THE NUMBER OF THREADS
646 Returns the number of requests currently in the ready state (not
647 yet executed).
648
649 IO::AIO::npending
650 Returns the number of requests currently in the pending state
651 (executed, but not yet processed by poll_cb).
652
653 IO::AIO::flush
654 Wait till all outstanding AIO requests have been handled.
655
656 Strictly equivalent to:
657
658 IO::AIO::poll_wait, IO::AIO::poll_cb
659 while IO::AIO::nreqs;
660
661 IO::AIO::poll
662 Waits until some requests have been handled.
663
664 Strictly equivalent to:
665
666 IO::AIO::poll_wait, IO::AIO::poll_cb
667 if IO::AIO::nreqs;
668
669 IO::AIO::min_parallel $nthreads 748 IO::AIO::min_parallel $nthreads
670 Set the minimum number of AIO threads to $nthreads. The current 749 Set the minimum number of AIO threads to $nthreads. The current
671 default is 8, which means eight asynchronous operations can 750 default is 8, which means eight asynchronous operations can
672 execute concurrently at any one time (the number of outstanding 751 execute concurrently at any one time (the number of outstanding
673 requests, however, is unlimited). 752 requests, however, is unlimited).
674 753
675 IO::AIO starts threads only on demand, when an AIO request is 754 IO::AIO starts threads only on demand, when an AIO request is
676 queued and no free thread exists. 755 queued and no free thread exists. Please note that queueing up a
756 hundred requests can create demand for a hundred threads, even
757 if it turns out that everything is in the cache and could have
758 been processed faster by a single thread.
677 759
678 It is recommended to keep the number of threads relatively low, 760 It is recommended to keep the number of threads relatively low,
679 as some Linux kernel versions will scale negatively with the 761 as some Linux kernel versions will scale negatively with the
680 number of threads (higher parallelity => MUCH higher latency). 762 number of threads (higher parallelity => MUCH higher latency).
681 With current Linux 2.6 versions, 4-32 threads should be fine. 763 With current Linux 2.6 versions, 4-32 threads should be fine.
… …
697 to ensure that all threads are killed and that there are no 779 to ensure that all threads are killed and that there are no
698 outstanding requests. 780 outstanding requests.
699 781
700 Under normal circumstances you don't need to call this function. 782 Under normal circumstances you don't need to call this function.
701 783
784 IO::AIO::max_idle $nthreads
785 Limit the number of threads (default: 4) that are allowed to
786 idle (i.e., threads that did not get a request to process within
787 10 seconds). That means if a thread becomes idle while $nthreads
788 other threads are also idle, it will free its resources and
789 exit.
790
791 This is useful when you allow a large number of threads (e.g.
792 100 or 1000) to allow for extremely high load situations, but
793 want to free resources under normal circumstances (1000 threads
794 can easily consume 30MB of RAM).
795
796 The default is probably ok in most situations, especially if
797 thread creation is fast. If thread creation is very slow on your
798 system you might want to use larger values.
799
702 $oldmaxreqs = IO::AIO::max_outstanding $maxreqs 800 $oldmaxreqs = IO::AIO::max_outstanding $maxreqs
703 This is a very bad function to use in interactive programs 801 This is a very bad function to use in interactive programs
704 because it blocks, and a bad way to reduce concurrency because 802 because it blocks, and a bad way to reduce concurrency because
705 it is inexact: Better use an "aio_group" together with a feed 803 it is inexact: Better use an "aio_group" together with a feed
706 callback. 804 callback.
… …
716 814
717 You can still queue as many requests as you want. Therefore, 815 You can still queue as many requests as you want. Therefore,
718 "max_oustsanding" is mainly useful in simple scripts (with low 816 "max_oustsanding" is mainly useful in simple scripts (with low
719 values) or as a stop gap to shield against fatal memory overflow 817 values) or as a stop gap to shield against fatal memory overflow
720 (with large values). 818 (with large values).
819
820 STATISTICAL INFORMATION
821 IO::AIO::nreqs
822 Returns the number of requests currently in the ready, execute
823 or pending states (i.e. for which their callback has not been
824 invoked yet).
825
826 Example: wait till there are no outstanding requests anymore:
827
828 IO::AIO::poll_wait, IO::AIO::poll_cb
829 while IO::AIO::nreqs;
830
831 IO::AIO::nready
832 Returns the number of requests currently in the ready state (not
833 yet executed).
834
835 IO::AIO::npending
836 Returns the number of requests currently in the pending state
837 (executed, but not yet processed by poll_cb).
721 838
722 FORK BEHAVIOUR 839 FORK BEHAVIOUR
723 This module should do "the right thing" when the process using it 840 This module should do "the right thing" when the process using it
724 forks: 841 forks:
725 842

Diff Legend

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