… | |
… | |
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 |
29 | FreeBSD, with emulation on other platforms) and C<readahead> (Linux, with |
29 | FreeBSD, with emulation on other platforms) and C<readahead> (Linux, with |
30 | emulation elsewhere>). |
30 | emulation elsewhere>). |
31 | |
31 | |
32 | The goal is to enbale you to write fully non-blocking programs. For |
32 | The goal is to enable you to write fully non-blocking programs. For |
33 | example, in a game server, you would not want to freeze for a few seconds |
33 | example, in a game server, you would not want to freeze for a few seconds |
34 | just because the server is running a backup and you happen to call |
34 | just because the server is running a backup and you happen to call |
35 | C<readdir>. |
35 | C<readdir>. |
36 | |
36 | |
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 | |