… | |
… | |
51 | =head1 DESCRIPTION |
51 | =head1 DESCRIPTION |
52 | |
52 | |
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. |
55 | |
55 | |
56 | Currently, a number of threads are started that execute your read/writes |
56 | In this version, a number of threads are started that execute your |
57 | and signal their completion. You don't need thread support in perl, and |
57 | requests and signal their completion. You don't need thread support |
58 | the threads created by this module will not be visible to perl. In the |
58 | in perl, and the threads created by this module will not be visible |
59 | future, this module might make use of the native aio functions available |
59 | to perl. In the future, this module might make use of the native aio |
60 | on many operating systems. However, they are often not well-supported |
60 | functions available on many operating systems. However, they are often |
61 | (Linux doesn't allow them on normal files currently, for example), |
61 | not well-supported or restricted (Linux doesn't allow them on normal |
62 | and they would only support aio_read and aio_write, so the remaining |
62 | files currently, for example), and they would only support aio_read and |
63 | functionality would have to be implemented using threads anyway. |
63 | aio_write, so the remaining functionality would have to be implemented |
|
|
64 | using threads anyway. |
64 | |
65 | |
65 | Although the module will work with in the presence of other threads, |
66 | Although the module will work with in the presence of other (Perl-) |
66 | it is currently not reentrant in any way, so use appropriate locking |
67 | threads, it is currently not reentrant in any way, so use appropriate |
67 | yourself, always call C<poll_cb> from within the same thread, or never |
68 | locking yourself, always call C<poll_cb> from within the same thread, or |
68 | call C<poll_cb> (or other C<aio_> functions) recursively. |
69 | never call C<poll_cb> (or other C<aio_> functions) recursively. |
|
|
70 | |
|
|
71 | =head1 REQUEST ANATOMY AND LIFETIME |
|
|
72 | |
|
|
73 | Every C<aio_*> function creates a request. which is a C data structure not |
|
|
74 | directly visible to Perl. |
|
|
75 | |
|
|
76 | If called in non-void context, every request function returns a Perl |
|
|
77 | object representing the request. In void context, nothing is returned, |
|
|
78 | which saves a bit of memory. |
|
|
79 | |
|
|
80 | The perl object is a fairly standard ref-to-hash object. The hash contents |
|
|
81 | are not used by IO::AIO so you are free to store anything you like in it. |
|
|
82 | |
|
|
83 | During their existance, aio requests travel through the following states, |
|
|
84 | in order: |
|
|
85 | |
|
|
86 | =over 4 |
|
|
87 | |
|
|
88 | =item ready |
|
|
89 | |
|
|
90 | Immediately after a request is created it is put into the ready state, |
|
|
91 | waiting for a thread to execute it. |
|
|
92 | |
|
|
93 | =item execute |
|
|
94 | |
|
|
95 | A thread has accepted the request for processing and is currently |
|
|
96 | executing it (e.g. blocking in read). |
|
|
97 | |
|
|
98 | =item pending |
|
|
99 | |
|
|
100 | The request has been executed and is waiting for result processing. |
|
|
101 | |
|
|
102 | While request submission and execution is fully asynchronous, result |
|
|
103 | processing is not and relies on the perl interpreter calling C<poll_cb> |
|
|
104 | (or another function with the same effect). |
|
|
105 | |
|
|
106 | =item result |
|
|
107 | |
|
|
108 | The request results are processed synchronously by C<poll_cb>. |
|
|
109 | |
|
|
110 | The C<poll_cb> function will process all outstanding aio requests by |
|
|
111 | calling their callbacks, freeing memory associated with them and managing |
|
|
112 | any groups they are contained in. |
|
|
113 | |
|
|
114 | =item done |
|
|
115 | |
|
|
116 | Request has reached the end of its lifetime and holds no resources anymore |
|
|
117 | (except possibly for the Perl object, but its connection to the actual |
|
|
118 | aio request is severed and calling its methods will either do nothing or |
|
|
119 | result in a runtime error). |
69 | |
120 | |
70 | =cut |
121 | =cut |
71 | |
122 | |
72 | package IO::AIO; |
123 | package IO::AIO; |
73 | |
124 | |
… | |
… | |
591 | =head2 IO::AIO::REQ CLASS |
642 | =head2 IO::AIO::REQ CLASS |
592 | |
643 | |
593 | All non-aggregate C<aio_*> functions return an object of this class when |
644 | All non-aggregate C<aio_*> functions return an object of this class when |
594 | called in non-void context. |
645 | called in non-void context. |
595 | |
646 | |
596 | A request always moves through the following five states in its lifetime, |
|
|
597 | in order: B<ready> (request has been created, but has not been executed |
|
|
598 | yet), B<execute> (request is currently being executed), B<pending> |
|
|
599 | (request has been executed but callback has not been called yet), |
|
|
600 | B<result> (results are being processed synchronously, includes calling the |
|
|
601 | callback) and B<done> (request has reached the end of its lifetime and |
|
|
602 | holds no resources anymore). |
|
|
603 | |
|
|
604 | =over 4 |
647 | =over 4 |
605 | |
648 | |
606 | =item cancel $req |
649 | =item cancel $req |
607 | |
650 | |
608 | Cancels the request, if possible. Has the effect of skipping execution |
651 | Cancels the request, if possible. Has the effect of skipping execution |
… | |
… | |
888 | This module should do "the right thing" when the process using it forks: |
931 | This module should do "the right thing" when the process using it forks: |
889 | |
932 | |
890 | Before the fork, IO::AIO enters a quiescent state where no requests |
933 | Before the fork, IO::AIO enters a quiescent state where no requests |
891 | can be added in other threads and no results will be processed. After |
934 | can be added in other threads and no results will be processed. After |
892 | the fork the parent simply leaves the quiescent state and continues |
935 | the fork the parent simply leaves the quiescent state and continues |
893 | request/result processing, while the child clears the request/result |
936 | request/result processing, while the child frees the request/result queue |
894 | queue (so the requests started before the fork will only be handled in |
937 | (so that the requests started before the fork will only be handled in the |
895 | the parent). Threads will be started on demand until the limit ste in the |
938 | parent). Threads will be started on demand until the limit set in the |
896 | parent process has been reached again. |
939 | parent process has been reached again. |
|
|
940 | |
|
|
941 | Temporary memory that was allocated for request processing is not |
|
|
942 | reclaimed in the child, however. While this is possible in some cases, it |
|
|
943 | is almost impossible in others (threads are evil you know), so you will |
|
|
944 | have to live with it. This is around 64k buffer (for sendfile, readahead |
|
|
945 | emulation) + the size of the directory being scanned (readdir). |
897 | |
946 | |
898 | In short: the parent will, after a short pause, continue as if fork had |
947 | In short: the parent will, after a short pause, continue as if fork had |
899 | not been called, while the child will act as if IO::AIO has not been used |
948 | not been called, while the child will act as if IO::AIO has not been used |
900 | yet. |
949 | yet. |
901 | |
950 | |
902 | =head2 MEMORY USAGE |
951 | =head2 MEMORY USAGE |
903 | |
952 | |
|
|
953 | Per-request usage: |
|
|
954 | |
904 | Each aio request uses - depending on your architecture - around 128 bytes |
955 | Each aio request uses - depending on your architecture - around 100-200 |
905 | of memory. In addition, stat requests need a stat buffer (possibly a few |
956 | bytes of memory. In addition, stat requests need a stat buffer (possibly |
906 | hundred bytes). Perl scalars and other data passed into aio requests will |
957 | a few hundred bytes), readdir requires a result buffer and so on. Perl |
907 | also be locked. |
958 | scalars and other data passed into aio requests will also be locked and |
|
|
959 | will consume memory till the request has entered the done state. |
908 | |
960 | |
909 | This is now awfully much, so queuing lots of requests is not usually a |
961 | This is now awfully much, so queuing lots of requests is not usually a |
910 | problem. |
962 | problem. |
911 | |
963 | |
912 | Each thread needs a stack area which is usually around 16k, sometimes much |
964 | Per-thread usage: |
913 | larger, depending on the OS. |
965 | |
|
|
966 | In the execution phase, some aio requests require more memory for |
|
|
967 | temporary buffers, and each thread requires a stack and other data |
|
|
968 | structures (usually around 16k-128k, depending on the OS). |
|
|
969 | |
|
|
970 | =head1 KNOWN BUGS |
|
|
971 | |
|
|
972 | See FORK BEHAVIOUR, above. |
914 | |
973 | |
915 | =head1 SEE ALSO |
974 | =head1 SEE ALSO |
916 | |
975 | |
917 | L<Coro::AIO>. |
976 | L<Coro::AIO>. |
918 | |
977 | |