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

Comparing libeio/eio.pod (file contents):
Revision 1.10 by root, Sun Jun 5 23:22:04 2011 UTC vs.
Revision 1.15 by root, Tue Jul 5 16:57:41 2011 UTC

… …
124=back 124=back
125 125
126For libev, you would typically use an C<ev_async> watcher: the 126For libev, you would typically use an C<ev_async> watcher: the
127C<want_poll> callback would invoke C<ev_async_send> to wake up the event 127C<want_poll> callback would invoke C<ev_async_send> to wake up the event
128loop. Inside the callback set for the watcher, one would call C<eio_poll 128loop. Inside the callback set for the watcher, one would call C<eio_poll
129()> (followed by C<ev_async_send> again if C<eio_poll> indicates that not 129()>.
130all requests have been handled yet). The race is taken care of because 130
131libev resets/rearms the async watcher before calling your callback, 131If C<eio_poll ()> is configured to not handle all results in one go
132and therefore, before calling C<eio_poll>. This might result in (some) 132(i.e. it returns C<-1>) then you should start an idle watcher that calls
133spurious wake-ups, but is generally harmless. 133C<eio_poll> until it returns something C<!= -1>.
134
135A full-featured wrapper would look as follows (if C<eio_poll> is handling
136all requests, it can of course be simplified a lot by removing the idle
137watcher logic):
138
139 static struct ev_loop *loop;
140 static ev_idle repeat_watcher;
141 static ev_async ready_watcher;
142
143 /* idle watcher callback, only used when eio_poll */
144 /* didn't handle all results in one call */
145 static void
146 repeat (EV_P_ ev_idle *w, int revents)
147 {
148 if (eio_poll () != -1)
149 ev_idle_stop (EV_A_ w);
150 }
151
152 /* eio has some results, process them */
153 static void
154 ready (EV_P_ ev_async *w, int revents)
155 {
156 if (eio_poll () == -1)
157 ev_idle_start (EV_A_ &repeat_watcher);
158 }
159
160 /* wake up the event loop */
161 static void
162 want_poll (void)
163 {
164 ev_async_send (loop, &ready_watcher)
165 }
166
167 void
168 my_init_eio ()
169 {
170 loop = EV_DEFAULT;
171
172 ev_idle_init (&repeat_watcher, repeat);
173 ev_async_init (&ready_watcher, ready);
174 ev_async_start (loop &watcher);
175
176 eio_init (want_poll, 0);
177 }
134 178
135For most other event loops, you would typically use a pipe - the event 179For most other event loops, you would typically use a pipe - the event
136loop should be told to wait for read readiness on the read end. In 180loop should be told to wait for read readiness on the read end. In
137C<want_poll> you would write a single byte, in C<done_poll> you would try 181C<want_poll> you would write a single byte, in C<done_poll> you would try
138to read that byte, and in the callback for the read end, you would call 182to read that byte, and in the callback for the read end, you would call
… …
153 197
154You submit a request by calling the relevant C<eio_TYPE> function with the 198You submit a request by calling the relevant C<eio_TYPE> function with the
155required parameters, a callback of type C<int (*eio_cb)(eio_req *req)> 199required parameters, a callback of type C<int (*eio_cb)(eio_req *req)>
156(called C<eio_cb> below) and a freely usable C<void *data> argument. 200(called C<eio_cb> below) and a freely usable C<void *data> argument.
157 201
158The return value will either be 0 202The return value will either be 0, in case something went really wrong
203(which can basically only happen on very fatal errors, such as C<malloc>
204returning 0, which is rather unlikely), or a pointer to the newly-created
205and submitted C<eio_req *>.
159 206
160The callback will be called with an C<eio_req *> which contains the 207The callback will be called with an C<eio_req *> which contains the
161results of the request. The members you can access inside that structure 208results of the request. The members you can access inside that structure
162vary from request to request, except for: 209vary from request to request, except for:
163 210
… …
226custom data value as C<data>. 273custom data value as C<data>.
227 274
228=head3 POSIX API WRAPPERS 275=head3 POSIX API WRAPPERS
229 276
230These requests simply wrap the POSIX call of the same name, with the same 277These requests simply wrap the POSIX call of the same name, with the same
231arguments. If a function is not implemented by the OS and cnanot be emulated 278arguments. If a function is not implemented by the OS and cannot be emulated
232in some way, then all of these return C<-1> and set C<errorno> to C<ENOSYS>. 279in some way, then all of these return C<-1> and set C<errorno> to C<ENOSYS>.
233 280
234=over 4 281=over 4
235 282
236=item eio_open (const char *path, int flags, mode_t mode, int pri, eio_cb cb, void *data) 283=item eio_open (const char *path, int flags, mode_t mode, int pri, eio_cb cb, void *data)
… …
316 { 363 {
317 char *target = strndup ((char *)req->ptr2, req->result); 364 char *target = strndup ((char *)req->ptr2, req->result);
318 365
319 free (target); 366 free (target);
320 } 367 }
368
369=item eio_realpath (const char *path, int pri, eio_cb cb, void *data)
370
371Similar to the realpath libc function, but unlike that one, result is
372C<-1> on failure and the length of the returned path in C<ptr2> (which is
373not 0-terminated) - this is similar to readlink.
321 374
322=item eio_stat (const char *path, int pri, eio_cb cb, void *data) 375=item eio_stat (const char *path, int pri, eio_cb cb, void *data)
323 376
324=item eio_lstat (const char *path, int pri, eio_cb cb, void *data) 377=item eio_lstat (const char *path, int pri, eio_cb cb, void *data)
325 378
… …
568 621
569=back 622=back
570 623
571=head3 GROUPING AND LIMITING REQUESTS 624=head3 GROUPING AND LIMITING REQUESTS
572 625
626There is one more rather special request, C<eio_grp>. It is a very special
627aio request: Instead of doing something, it is a container for other eio
628requests.
629
630There are two primary use cases for this: a) bundle many requests into a
631single, composite, request with a definite callback and the ability to
632cancel the whole request with its subrequests and b) limiting the number
633of "active" requests.
634
635Further below you will find more dicussion of these topics - first follows
636the reference section detailing the request generator and other methods.
637
638=over 4
639
640=item eio_grp (eio_cb cb, void *data)
641
642Creates and submits a group request.
643
644=back
645
646
647
573#TODO 648#TODO
574 649
575/*****************************************************************************/ 650/*****************************************************************************/
576/* groups */ 651/* groups */
577 652

Diff Legend

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