ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libeio/eio.pod
(Generate patch)

Comparing libeio/eio.pod (file contents):
Revision 1.30 by root, Wed Jan 11 05:13:22 2012 UTC vs.
Revision 1.36 by root, Sun Jan 24 16:36:20 2016 UTC

… …
25similar functions, as well as less rarely ones such as C<mknod>, C<futime> 25similar functions, as well as less rarely ones such as C<mknod>, C<futime>
26or C<readlink>. 26or C<readlink>.
27 27
28It also offers wrappers around C<sendfile> (Solaris, Linux, HP-UX and 28It also offers wrappers around C<sendfile> (Solaris, Linux, HP-UX and
29FreeBSD, with emulation on other platforms) and C<readahead> (Linux, with 29FreeBSD, with emulation on other platforms) and C<readahead> (Linux, with
30emulation elsewhere>). 30emulation elsewhere).
31 31
32The goal is to enable you to write fully non-blocking programs. For 32The goal is to enable you to write fully non-blocking programs. For
33example, in a game server, you would not want to freeze for a few seconds 33example, in a game server, you would not want to freeze for a few seconds
34just because the server is running a backup and you happen to call 34just because the server is running a backup and you happen to call
35C<readdir>. 35C<readdir>.
… …
104This callback is invoked when libeio detects that all pending requests 104This callback is invoked when libeio detects that all pending requests
105have been handled. It is "edge-triggered", that is, it will only be 105have been handled. It is "edge-triggered", that is, it will only be
106called once after C<want_poll>. To put it differently, C<want_poll> and 106called once after C<want_poll>. To put it differently, C<want_poll> and
107C<done_poll> are invoked in pairs: after C<want_poll> you have to call 107C<done_poll> are invoked in pairs: after C<want_poll> you have to call
108C<eio_poll ()> until either C<eio_poll> indicates that everything has been 108C<eio_poll ()> until either C<eio_poll> indicates that everything has been
109handled or C<done_poll> has been called, which signals the same. 109handled or C<done_poll> has been called, which signals the same - only one
110method is needed.
110 111
111Note that C<eio_poll> might return after C<done_poll> and C<want_poll> 112Note that C<eio_poll> might return after C<done_poll> and C<want_poll>
112have been called again, so watch out for races in your code. 113have been called again, so watch out for races in your code.
113 114
115It is quite common to have an empty C<done_call> callback and only use
116the return value from C<eio_poll>, or, when C<eio_poll> is configured to
117handle all outstanding replies, it's enough to call C<eio_poll> once.
118
114As with C<want_poll>, this callback is called while locks are being held, 119As with C<want_poll>, this callback is called while locks are being held,
115so you I<must not call any libeio functions form within this callback>. 120so you I<must not call any libeio functions from within this callback>.
116 121
117=item int eio_poll () 122=item int eio_poll ()
118 123
119This function has to be called whenever there are pending requests that 124This function has to be called whenever there are pending requests that
120need finishing. You usually call this after C<want_poll> has indicated 125need finishing. You usually call this after C<want_poll> has indicated
… …
176 { 181 {
177 loop = EV_DEFAULT; 182 loop = EV_DEFAULT;
178 183
179 ev_idle_init (&repeat_watcher, repeat); 184 ev_idle_init (&repeat_watcher, repeat);
180 ev_async_init (&ready_watcher, ready); 185 ev_async_init (&ready_watcher, ready);
181 ev_async_start (loop &watcher); 186 ev_async_start (loop, &watcher);
182 187
183 eio_init (want_poll, 0); 188 eio_init (want_poll, 0);
184 } 189 }
185 190
186For most other event loops, you would typically use a pipe - the event 191For most other event loops, you would typically use a pipe - the event
… …
290 295
291Cancel the request (and all its subrequests). If the request is currently 296Cancel the request (and all its subrequests). If the request is currently
292executing it might still continue to execute, and in other cases it might 297executing it might still continue to execute, and in other cases it might
293still take a while till the request is cancelled. 298still take a while till the request is cancelled.
294 299
295Even if cancelled, the finish callback will still be invoked - the 300When cancelled, the finish callback will not be invoked.
296callbacks of all cancellable requests need to check whether the request
297has been cancelled by calling C<EIO_CANCELLED (req)>:
298
299 static int
300 my_eio_cb (eio_req *req)
301 {
302 if (EIO_CANCELLED (req))
303 return 0;
304 }
305
306In addition, cancelled requests will I<either> have C<< req->result >>
307set to C<-1> and C<errno> to C<ECANCELED>, or I<otherwise> they were
308successfully executed, despite being cancelled (e.g. when they have
309already been executed at the time they were cancelled).
310 301
311C<EIO_CANCELLED> is still true for requests that have successfully 302C<EIO_CANCELLED> is still true for requests that have successfully
312executed, as long as C<eio_cancel> was called on them at some point. 303executed, as long as C<eio_cancel> was called on them at some point.
313 304
314=back 305=back
… …
630 621
631=over 4 622=over 4
632 623
633=item eio_mtouch (void *addr, size_t length, int flags, int pri, eio_cb cb, void *data) 624=item eio_mtouch (void *addr, size_t length, int flags, int pri, eio_cb cb, void *data)
634 625
635Reads (C<flags == 0>) or modifies (C<flags == EIO_MT_MODIFY) the given 626Reads (C<flags == 0>) or modifies (C<flags == EIO_MT_MODIFY>) the given
636memory area, page-wise, that is, it reads (or reads and writes back) the 627memory area, page-wise, that is, it reads (or reads and writes back) the
637first octet of every page that spans the memory area. 628first octet of every page that spans the memory area.
638 629
639This can be used to page in some mmapped file, or dirty some pages. Note 630This can be used to page in some mmapped file, or dirty some pages. Note
640that dirtying is an unlocked read-write access, so races can ensue when 631that dirtying is an unlocked read-write access, so races can ensue when
… …
788#TODO 779#TODO
789 780
790void eio_grp_limit (eio_req *grp, int limit); 781void eio_grp_limit (eio_req *grp, int limit);
791 782
792 783
793=back
794
795 784
796=head1 LOW LEVEL REQUEST API 785=head1 LOW LEVEL REQUEST API
797 786
798#TODO 787#TODO
799 788
… …
926This symbol governs the stack size for each eio thread. Libeio itself 915This symbol governs the stack size for each eio thread. Libeio itself
927was written to use very little stackspace, but when using C<EIO_CUSTOM> 916was written to use very little stackspace, but when using C<EIO_CUSTOM>
928requests, you might want to increase this. 917requests, you might want to increase this.
929 918
930If this symbol is undefined (the default) then libeio will use its default 919If this symbol is undefined (the default) then libeio will use its default
931stack size (C<sizeof (void *) * 4096> currently). If it is defined, but 920stack size (C<sizeof (void *) * 4096> currently). In all other cases, the
932C<0>, then the default operating system stack size will be used. In all
933other cases, the value must be an expression that evaluates to the desired 921value must be an expression that evaluates to the desired stack size.
934stack size.
935 922
936=back 923=back
937 924
938 925
939=head1 PORTABILITY REQUIREMENTS 926=head1 PORTABILITY REQUIREMENTS

Diff Legend

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