| … | |
… | |
| 11 | The newest version of this document is also available as an html-formatted |
11 | The newest version of this document is also available as an html-formatted |
| 12 | web page you might find easier to navigate when reading it for the first |
12 | web page you might find easier to navigate when reading it for the first |
| 13 | time: L<http://pod.tst.eu/http://cvs.schmorp.de/libeio/eio.pod>. |
13 | time: L<http://pod.tst.eu/http://cvs.schmorp.de/libeio/eio.pod>. |
| 14 | |
14 | |
| 15 | Note that this library is a by-product of the C<IO::AIO> perl |
15 | Note that this library is a by-product of the C<IO::AIO> perl |
| 16 | module, and many of the subtler points regarding requets lifetime |
16 | module, and many of the subtler points regarding requests lifetime |
| 17 | and so on are only documented in its documentation at the |
17 | and so on are only documented in its documentation at the |
| 18 | moment: L<http://pod.tst.eu/http://cvs.schmorp.de/IO-AIO/AIO.pm>. |
18 | moment: L<http://pod.tst.eu/http://cvs.schmorp.de/IO-AIO/AIO.pm>. |
| 19 | |
19 | |
| 20 | =head2 FEATURES |
20 | =head2 FEATURES |
| 21 | |
21 | |
| 22 | This library provides fully asynchronous versions of most POSIX functions |
22 | This library provides fully asynchronous versions of most POSIX functions |
| 23 | dealign with I/O. Unlike most asynchronous libraries, this not only |
23 | dealing with I/O. Unlike most asynchronous libraries, this not only |
| 24 | includes C<read> and C<write>, but also C<open>, C<stat>, C<unlink> and |
24 | includes C<read> and C<write>, but also C<open>, C<stat>, C<unlink> and |
| 25 | similar functions, as well as less rarely ones such as C<mknod>, C<futime> |
25 | similar functions, as well as less rarely ones such as C<mknod>, C<futime> |
| 26 | or C<readlink>. |
26 | or C<readlink>. |
| 27 | |
27 | |
| 28 | It also offers wrappers around C<sendfile> (Solaris, Linux, HP-UX and |
28 | It also offers wrappers around C<sendfile> (Solaris, Linux, HP-UX and |
| … | |
… | |
| 37 | =head2 TIME REPRESENTATION |
37 | =head2 TIME REPRESENTATION |
| 38 | |
38 | |
| 39 | Libeio represents time as a single floating point number, representing the |
39 | Libeio represents time as a single floating point number, representing the |
| 40 | (fractional) number of seconds since the (POSIX) epoch (somewhere near |
40 | (fractional) number of seconds since the (POSIX) epoch (somewhere near |
| 41 | the beginning of 1970, details are complicated, don't ask). This type is |
41 | the beginning of 1970, details are complicated, don't ask). This type is |
| 42 | called C<eio_tstamp>, but it is guarenteed to be of type C<double> (or |
42 | called C<eio_tstamp>, but it is guaranteed to be of type C<double> (or |
| 43 | better), so you can freely use C<double> yourself. |
43 | better), so you can freely use C<double> yourself. |
| 44 | |
44 | |
| 45 | Unlike the name component C<stamp> might indicate, it is also used for |
45 | Unlike the name component C<stamp> might indicate, it is also used for |
| 46 | time differences throughout libeio. |
46 | time differences throughout libeio. |
| 47 | |
47 | |
| … | |
… | |
| 97 | handled or C<done_poll> has been called, which signals the same. |
97 | handled or C<done_poll> has been called, which signals the same. |
| 98 | |
98 | |
| 99 | Note that C<eio_poll> might return after C<done_poll> and C<want_poll> |
99 | Note that C<eio_poll> might return after C<done_poll> and C<want_poll> |
| 100 | have been called again, so watch out for races in your code. |
100 | have been called again, so watch out for races in your code. |
| 101 | |
101 | |
| 102 | As with C<want_poll>, this callback is called while lcoks are being held, |
102 | As with C<want_poll>, this callback is called while locks are being held, |
| 103 | so you I<must not call any libeio functions form within this callback>. |
103 | so you I<must not call any libeio functions form within this callback>. |
| 104 | |
104 | |
| 105 | =item int eio_poll () |
105 | =item int eio_poll () |
| 106 | |
106 | |
| 107 | This function has to be called whenever there are pending requests that |
107 | This function has to be called whenever there are pending requests that |
| … | |
… | |
| 126 | libev resets/rearms the async watcher before calling your callback, |
126 | libev resets/rearms the async watcher before calling your callback, |
| 127 | and therefore, before calling C<eio_poll>. This might result in (some) |
127 | and therefore, before calling C<eio_poll>. This might result in (some) |
| 128 | spurious wake-ups, but is generally harmless. |
128 | spurious wake-ups, but is generally harmless. |
| 129 | |
129 | |
| 130 | For most other event loops, you would typically use a pipe - the event |
130 | For most other event loops, you would typically use a pipe - the event |
| 131 | loop should be told to wait for read readyness on the read end. In |
131 | loop should be told to wait for read readiness on the read end. In |
| 132 | C<want_poll> you would write a single byte, in C<done_poll> you would try |
132 | C<want_poll> you would write a single byte, in C<done_poll> you would try |
| 133 | to read that byte, and in the callback for the read end, you would call |
133 | to read that byte, and in the callback for the read end, you would call |
| 134 | C<eio_poll>. The race is avoided here because the event loop should invoke |
134 | C<eio_poll>. The race is avoided here because the event loop should invoke |
| 135 | your callback again and again until the byte has been read (as the pipe |
135 | your callback again and again until the byte has been read (as the pipe |
| 136 | read callback does not read it, only C<done_poll>). |
136 | read callback does not read it, only C<done_poll>). |
| … | |
… | |
| 185 | =item eio_set_max_idle (unsigned int nthreads) |
185 | =item eio_set_max_idle (unsigned int nthreads) |
| 186 | |
186 | |
| 187 | Libeio uses threads internally to handle most requests, and will start and stop threads on demand. |
187 | Libeio uses threads internally to handle most requests, and will start and stop threads on demand. |
| 188 | |
188 | |
| 189 | This call can be used to limit the number of idle threads (threads without |
189 | This call can be used to limit the number of idle threads (threads without |
| 190 | work to do): libeio will keep some threads idle in preperation for more |
190 | work to do): libeio will keep some threads idle in preparation for more |
| 191 | requests, but never longer than C<nthreads> threads. |
191 | requests, but never longer than C<nthreads> threads. |
| 192 | |
192 | |
| 193 | In addition to this, libeio will also stop threads when they are idle for |
193 | In addition to this, libeio will also stop threads when they are idle for |
| 194 | a few seconds, regardless of this setting. |
194 | a few seconds, regardless of this setting. |
| 195 | |
195 | |
