… | |
… | |
131 | |
131 | |
132 | If C<eio_poll ()> is configured to not handle all results in one go |
132 | If C<eio_poll ()> is configured to not handle all results in one go |
133 | (i.e. it returns C<-1>) then you should start an idle watcher that calls |
133 | (i.e. it returns C<-1>) then you should start an idle watcher that calls |
134 | C<eio_poll> until it returns something C<!= -1>. |
134 | C<eio_poll> until it returns something C<!= -1>. |
135 | |
135 | |
136 | A full-featured conenctor between libeio and libev would look as follows |
136 | A full-featured connector between libeio and libev would look as follows |
137 | (if C<eio_poll> is handling all requests, it can of course be simplified a |
137 | (if C<eio_poll> is handling all requests, it can of course be simplified a |
138 | lot by removing the idle watcher logic): |
138 | lot by removing the idle watcher logic): |
139 | |
139 | |
140 | static struct ev_loop *loop; |
140 | static struct ev_loop *loop; |
141 | static ev_idle repeat_watcher; |
141 | static ev_idle repeat_watcher; |
… | |
… | |
183 | to read that byte, and in the callback for the read end, you would call |
183 | to read that byte, and in the callback for the read end, you would call |
184 | C<eio_poll>. |
184 | C<eio_poll>. |
185 | |
185 | |
186 | You don't have to take special care in the case C<eio_poll> doesn't handle |
186 | You don't have to take special care in the case C<eio_poll> doesn't handle |
187 | all requests, as the done callback will not be invoked, so the event loop |
187 | all requests, as the done callback will not be invoked, so the event loop |
188 | will still signal readyness for the pipe until I<all> results have been |
188 | will still signal readiness for the pipe until I<all> results have been |
189 | processed. |
189 | processed. |
190 | |
190 | |
191 | |
191 | |
192 | =head1 HIGH LEVEL REQUEST API |
192 | =head1 HIGH LEVEL REQUEST API |
193 | |
193 | |
… | |
… | |
261 | } |
261 | } |
262 | |
262 | |
263 | /* the first three arguments are passed to open(2) */ |
263 | /* the first three arguments are passed to open(2) */ |
264 | /* the remaining are priority, callback and data */ |
264 | /* the remaining are priority, callback and data */ |
265 | if (!eio_open ("/etc/passwd", O_RDONLY, 0, 0, file_open_done, 0)) |
265 | if (!eio_open ("/etc/passwd", O_RDONLY, 0, 0, file_open_done, 0)) |
266 | abort (); /* something ent wrong, we will all die!!! */ |
266 | abort (); /* something went wrong, we will all die!!! */ |
267 | |
267 | |
268 | Note that you additionally need to call C<eio_poll> when the C<want_cb> |
268 | Note that you additionally need to call C<eio_poll> when the C<want_cb> |
269 | indicates that requests are ready to be processed. |
269 | indicates that requests are ready to be processed. |
270 | |
270 | |
271 | =head2 CANCELLING REQUESTS |
271 | =head2 CANCELLING REQUESTS |
272 | |
272 | |
273 | Sometimes the need for a request goes away before the request is |
273 | Sometimes the need for a request goes away before the request is |
274 | finished. In that case, one can cancel the reqiest by a call to |
274 | finished. In that case, one can cancel the request by a call to |
275 | C<eio_cancel>: |
275 | C<eio_cancel>: |
276 | |
276 | |
277 | =over 4 |
277 | =over 4 |
278 | |
278 | |
279 | =item eio_cancel (eio_req *req) |
279 | =item eio_cancel (eio_req *req) |
280 | |
280 | |
281 | Cancel the request. If the request is currently executing it might still |
281 | Cancel the request (and all its subrequests). If the request is currently |
282 | continue to execute, and in other cases it might still take a while till |
282 | executing it might still continue to execute, and in other cases it might |
283 | the request is cancelled. |
283 | still take a while till the request is cancelled. |
284 | |
284 | |
285 | Even if cancelled, the finish callback will still be invoked - the |
285 | Even if cancelled, the finish callback will still be invoked - the |
286 | callbacks of all cancellable requests need to check whether the request |
286 | callbacks of all cancellable requests need to check whether the request |
287 | has been cancelled by calling C<EIO_CANCELLED (req)>: |
287 | has been cancelled by calling C<EIO_CANCELLED (req)>: |
288 | |
288 | |
… | |
… | |
291 | { |
291 | { |
292 | if (EIO_CANCELLED (req)) |
292 | if (EIO_CANCELLED (req)) |
293 | return 0; |
293 | return 0; |
294 | } |
294 | } |
295 | |
295 | |
296 | In addition, cancelled requests will either have C<< req->result >> set to |
296 | In addition, cancelled requests will I<either> have C<< req->result >> |
297 | C<-1> and C<errno> to C<ECANCELED>, or otherwise they were successfully |
297 | set to C<-1> and C<errno> to C<ECANCELED>, or I<otherwise> they were |
298 | executed despite being cancelled (e.g. when they have already been |
298 | successfully executed, despite being cancelled (e.g. when they have |
299 | executed at the time they were cancelled). |
299 | already been executed at the time they were cancelled). |
|
|
300 | |
|
|
301 | C<EIO_CANCELLED> is still true for requests that have successfully |
|
|
302 | executed, as long as C<eio_cancel> was called on them at some point. |
300 | |
303 | |
301 | =back |
304 | =back |
302 | |
305 | |
303 | =head2 AVAILABLE REQUESTS |
306 | =head2 AVAILABLE REQUESTS |
304 | |
307 | |
… | |
… | |
431 | =back |
434 | =back |
432 | |
435 | |
433 | =head3 READING DIRECTORIES |
436 | =head3 READING DIRECTORIES |
434 | |
437 | |
435 | Reading directories sounds simple, but can be rather demanding, especially |
438 | Reading directories sounds simple, but can be rather demanding, especially |
436 | if you want to do stuff such as traversing a diretcory hierarchy or |
439 | if you want to do stuff such as traversing a directory hierarchy or |
437 | processing all files in a directory. Libeio can assist thess complex tasks |
440 | processing all files in a directory. Libeio can assist these complex tasks |
438 | with it's C<eio_readdir> call. |
441 | with it's C<eio_readdir> call. |
439 | |
442 | |
440 | =over 4 |
443 | =over 4 |
441 | |
444 | |
442 | =item eio_readdir (const char *path, int flags, int pri, eio_cb cb, void *data) |
445 | =item eio_readdir (const char *path, int flags, int pri, eio_cb cb, void *data) |
… | |
… | |
534 | When this flag is specified, then the names will be returned in an order |
537 | When this flag is specified, then the names will be returned in an order |
535 | suitable for stat()'ing each one. That is, when you plan to stat() |
538 | suitable for stat()'ing each one. That is, when you plan to stat() |
536 | all files in the given directory, then the returned order will likely |
539 | all files in the given directory, then the returned order will likely |
537 | be fastest. |
540 | be fastest. |
538 | |
541 | |
539 | If both this flag and C<EIO_READDIR_DIRS_FIRST> are specified, then |
542 | If both this flag and C<EIO_READDIR_DIRS_FIRST> are specified, then the |
540 | the likely dirs come first, resulting in a less optimal stat order. |
543 | likely directories come first, resulting in a less optimal stat order. |
541 | |
544 | |
542 | =item EIO_READDIR_FOUND_UNKNOWN |
545 | =item EIO_READDIR_FOUND_UNKNOWN |
543 | |
546 | |
544 | This flag should not be specified when calling C<eio_readdir>. Instead, |
547 | This flag should not be specified when calling C<eio_readdir>. Instead, |
545 | it is being set by C<eio_readdir> (you can access the C<flags> via C<< |
548 | it is being set by C<eio_readdir> (you can access the C<flags> via C<< |
546 | req->int1 >>, when any of the C<type>'s found were C<EIO_DT_UNKNOWN>. The |
549 | req->int1 >>, when any of the C<type>'s found were C<EIO_DT_UNKNOWN>. The |
547 | absense of this flag therefore indicates that all C<type>'s are known, |
550 | absence of this flag therefore indicates that all C<type>'s are known, |
548 | which can be used to speed up some algorithms. |
551 | which can be used to speed up some algorithms. |
549 | |
552 | |
550 | A typical use case would be to identify all subdirectories within a |
553 | A typical use case would be to identify all subdirectories within a |
551 | directory - you would ask C<eio_readdir> for C<EIO_READDIR_DIRS_FIRST>. If |
554 | directory - you would ask C<eio_readdir> for C<EIO_READDIR_DIRS_FIRST>. If |
552 | then this flag is I<NOT> set, then all the entries at the beginning of the |
555 | then this flag is I<NOT> set, then all the entries at the beginning of the |
… | |
… | |
640 | |
643 | |
641 | eio_custom (my_open, 0, my_open_done, "/etc/passwd"); |
644 | eio_custom (my_open, 0, my_open_done, "/etc/passwd"); |
642 | |
645 | |
643 | =item eio_busy (eio_tstamp delay, int pri, eio_cb cb, void *data) |
646 | =item eio_busy (eio_tstamp delay, int pri, eio_cb cb, void *data) |
644 | |
647 | |
645 | This is a a request that takes C<delay> seconds to execute, but otherwise |
648 | This is a request that takes C<delay> seconds to execute, but otherwise |
646 | does nothing - it simply puts one of the worker threads to sleep for this |
649 | does nothing - it simply puts one of the worker threads to sleep for this |
647 | long. |
650 | long. |
648 | |
651 | |
649 | This request can be used to artificially increase load, e.g. for debugging |
652 | This request can be used to artificially increase load, e.g. for debugging |
650 | or benchmarking reasons. |
653 | or benchmarking reasons. |
… | |
… | |
666 | There are two primary use cases for this: a) bundle many requests into a |
669 | There are two primary use cases for this: a) bundle many requests into a |
667 | single, composite, request with a definite callback and the ability to |
670 | single, composite, request with a definite callback and the ability to |
668 | cancel the whole request with its subrequests and b) limiting the number |
671 | cancel the whole request with its subrequests and b) limiting the number |
669 | of "active" requests. |
672 | of "active" requests. |
670 | |
673 | |
671 | Further below you will find more dicussion of these topics - first follows |
674 | Further below you will find more discussion of these topics - first |
672 | the reference section detailing the request generator and other methods. |
675 | follows the reference section detailing the request generator and other |
|
|
676 | methods. |
673 | |
677 | |
674 | =over 4 |
678 | =over 4 |
675 | |
679 | |
676 | =item eio_req *grp = eio_grp (eio_cb cb, void *data) |
680 | =item eio_req *grp = eio_grp (eio_cb cb, void *data) |
677 | |
681 | |
… | |
… | |
748 | for example, in interactive programs, you might want to limit this time to |
752 | for example, in interactive programs, you might want to limit this time to |
749 | C<0.01> seconds or so. |
753 | C<0.01> seconds or so. |
750 | |
754 | |
751 | Note that: |
755 | Note that: |
752 | |
756 | |
|
|
757 | =over 4 |
|
|
758 | |
753 | a) libeio doesn't know how long your request callbacks take, so the time |
759 | =item a) libeio doesn't know how long your request callbacks take, so the |
754 | spent in C<eio_poll> is up to one callback invocation longer then this |
760 | time spent in C<eio_poll> is up to one callback invocation longer then |
755 | interval. |
761 | this interval. |
756 | |
762 | |
757 | b) this is implemented by calling C<gettimeofday> after each request, |
763 | =item b) this is implemented by calling C<gettimeofday> after each |
758 | which can be costly. |
764 | request, which can be costly. |
759 | |
765 | |
760 | c) at least one request will be handled. |
766 | =item c) at least one request will be handled. |
|
|
767 | |
|
|
768 | =back |
761 | |
769 | |
762 | =item eio_set_max_poll_reqs (unsigned int nreqs) |
770 | =item eio_set_max_poll_reqs (unsigned int nreqs) |
763 | |
771 | |
764 | When C<nreqs> is non-zero, then C<eio_poll> will not handle more than |
772 | When C<nreqs> is non-zero, then C<eio_poll> will not handle more than |
765 | C<nreqs> requests per invocation. This is a less costly way to limit the |
773 | C<nreqs> requests per invocation. This is a less costly way to limit the |