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

Comparing IO-AIO/README (file contents):
Revision 1.37 by root, Fri Jun 12 16:55:17 2009 UTC vs.
Revision 1.38 by root, Sat Jun 27 03:19:27 2009 UTC

… …
28 28
29 # AnyEvent integration (EV, Event, Glib, Tk, POE, urxvt, pureperl...) 29 # AnyEvent integration (EV, Event, Glib, Tk, POE, urxvt, pureperl...)
30 use AnyEvent::AIO; 30 use AnyEvent::AIO;
31 31
32 # EV integration 32 # EV integration
33 my $w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb; 33 my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
34 34
35 # Event integration 35 # Event integration
36 Event->io (fd => IO::AIO::poll_fileno, 36 Event->io (fd => IO::AIO::poll_fileno,
37 poll => 'r', 37 poll => 'r',
38 cb => \&IO::AIO::poll_cb); 38 cb => \&IO::AIO::poll_cb);
… …
49 Danga::Socket->AddOtherFds (IO::AIO::poll_fileno => 49 Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>
50 \&IO::AIO::poll_cb); 50 \&IO::AIO::poll_cb);
51 51
52DESCRIPTION 52DESCRIPTION
53 This module implements asynchronous I/O using whatever means your 53 This module implements asynchronous I/O using whatever means your
54 operating system supports. 54 operating system supports. It is implemented as an interface to "libeio"
55 (<http://software.schmorp.de/pkg/libeio.html>).
55 56
56 Asynchronous means that operations that can normally block your program 57 Asynchronous means that operations that can normally block your program
57 (e.g. reading from disk) will be done asynchronously: the operation will 58 (e.g. reading from disk) will be done asynchronously: the operation will
58 still block, but you can do something else in the meantime. This is 59 still block, but you can do something else in the meantime. This is
59 extremely useful for programs that need to stay interactive even when 60 extremely useful for programs that need to stay interactive even when
… …
64 operations concurrently. 65 operations concurrently.
65 66
66 While most of this works on all types of file descriptors (for example 67 While most of this works on all types of file descriptors (for example
67 sockets), using these functions on file descriptors that support 68 sockets), using these functions on file descriptors that support
68 nonblocking operation (again, sockets, pipes etc.) is very inefficient. 69 nonblocking operation (again, sockets, pipes etc.) is very inefficient.
69 Use an event loop for that (such as the Event module): IO::AIO will 70 Use an event loop for that (such as the EV module): IO::AIO will
70 naturally fit into such an event loop itself. 71 naturally fit into such an event loop itself.
71 72
72 In this version, a number of threads are started that execute your 73 In this version, a number of threads are started that execute your
73 requests and signal their completion. You don't need thread support in 74 requests and signal their completion. You don't need thread support in
74 perl, and the threads created by this module will not be visible to 75 perl, and the threads created by this module will not be visible to
… …
83 it is currently not reentrant in any way, so use appropriate locking 84 it is currently not reentrant in any way, so use appropriate locking
84 yourself, always call "poll_cb" from within the same thread, or never 85 yourself, always call "poll_cb" from within the same thread, or never
85 call "poll_cb" (or other "aio_" functions) recursively. 86 call "poll_cb" (or other "aio_" functions) recursively.
86 87
87 EXAMPLE 88 EXAMPLE
88 This is a simple example that uses the Event module and loads 89 This is a simple example that uses the EV module and loads /etc/passwd
89 /etc/passwd asynchronously: 90 asynchronously:
90 91
91 use Fcntl; 92 use Fcntl;
92 use Event; 93 use EV;
93 use IO::AIO; 94 use IO::AIO;
94 95
95 # register the IO::AIO callback with Event 96 # register the IO::AIO callback with EV
96 Event->io (fd => IO::AIO::poll_fileno, 97 my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
97 poll => 'r',
98 cb => \&IO::AIO::poll_cb);
99 98
100 # queue the request to open /etc/passwd 99 # queue the request to open /etc/passwd
101 aio_open "/etc/passwd", O_RDONLY, 0, sub { 100 aio_open "/etc/passwd", O_RDONLY, 0, sub {
102 my $fh = shift 101 my $fh = shift
103 or die "error while opening: $!"; 102 or die "error while opening: $!";
… …
115 114
116 # file contents now in $contents 115 # file contents now in $contents
117 print $contents; 116 print $contents;
118 117
119 # exit event loop and program 118 # exit event loop and program
120 Event::unloop; 119 EV::unloop;
121 }; 120 };
122 }; 121 };
123 122
124 # possibly queue up other requests, or open GUI windows, 123 # possibly queue up other requests, or open GUI windows,
125 # check for sockets etc. etc. 124 # check for sockets etc. etc.
126 125
127 # process events as long as there are some: 126 # process events as long as there are some:
128 Event::loop; 127 EV::loop;
129 128
130REQUEST ANATOMY AND LIFETIME 129REQUEST ANATOMY AND LIFETIME
131 Every "aio_*" function creates a request. which is a C data structure 130 Every "aio_*" function creates a request. which is a C data structure
132 not directly visible to Perl. 131 not directly visible to Perl.
133 132
… …
474 you need to know, you have to run stat yourself. Also, for speed 473 you need to know, you have to run stat yourself. Also, for speed
475 reasons, the $type scalars are read-only: you can not modify 474 reasons, the $type scalars are read-only: you can not modify
476 them. 475 them.
477 476
478 $inode is the inode number (which might not be exact on systems 477 $inode is the inode number (which might not be exact on systems
479 with 64 bit inode numbers and 32 bit perls). On systems that do 478 with 64 bit inode numbers and 32 bit perls). This field has
480 not deliver the inode information, this will always be zero. 479 unspecified content on systems that do not deliver the inode
480 information.
481 481
482 IO::AIO::READDIR_DIRS_FIRST 482 IO::AIO::READDIR_DIRS_FIRST
483 When this flag is set, then the names will be returned in an 483 When this flag is set, then the names will be returned in an
484 order where likely directories come first. This is useful when 484 order where likely directories come first. This is useful when
485 you need to quickly find directories, or you want to find all 485 you need to quickly find directories, or you want to find all
… …
826 SUPPORT FUNCTIONS 826 SUPPORT FUNCTIONS
827 EVENT PROCESSING AND EVENT LOOP INTEGRATION 827 EVENT PROCESSING AND EVENT LOOP INTEGRATION
828 $fileno = IO::AIO::poll_fileno 828 $fileno = IO::AIO::poll_fileno
829 Return the *request result pipe file descriptor*. This filehandle 829 Return the *request result pipe file descriptor*. This filehandle
830 must be polled for reading by some mechanism outside this module 830 must be polled for reading by some mechanism outside this module
831 (e.g. Event or select, see below or the SYNOPSIS). If the pipe 831 (e.g. EV, Glib, select and so on, see below or the SYNOPSIS). If the
832 becomes readable you have to call "poll_cb" to check the results. 832 pipe becomes readable you have to call "poll_cb" to check the
833 results.
833 834
834 See "poll_cb" for an example. 835 See "poll_cb" for an example.
835 836
836 IO::AIO::poll_cb 837 IO::AIO::poll_cb
837 Process some outstanding events on the result pipe. You have to call 838 Process some outstanding events on the result pipe. You have to call
… …
844 If not all requests were processed for whatever reason, the 845 If not all requests were processed for whatever reason, the
845 filehandle will still be ready when "poll_cb" returns, so normally 846 filehandle will still be ready when "poll_cb" returns, so normally
846 you don't have to do anything special to have it called later. 847 you don't have to do anything special to have it called later.
847 848
848 Example: Install an Event watcher that automatically calls 849 Example: Install an Event watcher that automatically calls
849 IO::AIO::poll_cb with high priority: 850 IO::AIO::poll_cb with high priority (more examples can be found in
851 the SYNOPSIS section, at the top of this document):
850 852
851 Event->io (fd => IO::AIO::poll_fileno, 853 Event->io (fd => IO::AIO::poll_fileno,
852 poll => 'r', async => 1, 854 poll => 'r', async => 1,
853 cb => \&IO::AIO::poll_cb); 855 cb => \&IO::AIO::poll_cb);
854 856
… …
994 996
995 IO::AIO::npending 997 IO::AIO::npending
996 Returns the number of requests currently in the pending state 998 Returns the number of requests currently in the pending state
997 (executed, but not yet processed by poll_cb). 999 (executed, but not yet processed by poll_cb).
998 1000
1001 MISCELLANEOUS FUNCTIONS
1002 IO::AIO implements some functions that might be useful, but are not
1003 asynchronous.
1004
1005 IO::AIO::sendfile $ofh, $ifh, $offset, $count
1006 Calls the "eio_sendfile_sync" function, which is like
1007 "aio_sendfile", but is blocking (this makes most sense if you know
1008 the input data is likely cached already and the output filehandle is
1009 set to non-blocking operations).
1010
1011 Returns the number of bytes copied, or -1 on error.
1012
1013 IO::AIO::fadvise $fh, $offset, $len, $advice
1014 Simply calls the "posix_fadvise" function (see it's manpage for
1015 details). The following advice constants are avaiable:
1016 "IO::AIO::FADV_NORMAL", "IO::AIO::FADV_SEQUENTIAL",
1017 "IO::AIO::FADV_RANDOM", "IO::AIO::FADV_NOREUSE",
1018 "IO::AIO::FADV_WILLNEED", "IO::AIO::FADV_DONTNEED".
1019
1020 On systems that do not implement "posix_fadvise", this function
1021 returns ENOSYS, otherwise the return value of "posix_fadvise".
1022
999 FORK BEHAVIOUR 1023 FORK BEHAVIOUR
1000 This module should do "the right thing" when the process using it forks: 1024 This module should do "the right thing" when the process using it forks:
1001 1025
1002 Before the fork, IO::AIO enters a quiescent state where no requests can 1026 Before the fork, IO::AIO enters a quiescent state where no requests can
1003 be added in other threads and no results will be processed. After the 1027 be added in other threads and no results will be processed. After the

Diff Legend

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