… | |
… | |
405 | free (target); |
405 | free (target); |
406 | } |
406 | } |
407 | |
407 | |
408 | =item eio_realpath (const char *path, int pri, eio_cb cb, void *data) |
408 | =item eio_realpath (const char *path, int pri, eio_cb cb, void *data) |
409 | |
409 | |
410 | Similar to the realpath libc function, but unlike that one, result is |
410 | Similar to the realpath libc function, but unlike that one, C<< |
411 | C<-1> on failure and the length of the returned path in C<ptr2> (which is |
411 | req->result >> is C<-1> on failure. On success, the result is the length |
412 | not 0-terminated) - this is similar to readlink. |
412 | of the returned path in C<ptr2> (which is I<NOT> 0-terminated) - this is |
|
|
413 | similar to readlink. |
413 | |
414 | |
414 | =item eio_stat (const char *path, int pri, eio_cb cb, void *data) |
415 | =item eio_stat (const char *path, int pri, eio_cb cb, void *data) |
415 | |
416 | |
416 | =item eio_lstat (const char *path, int pri, eio_cb cb, void *data) |
417 | =item eio_lstat (const char *path, int pri, eio_cb cb, void *data) |
417 | |
418 | |
… | |
… | |
593 | as calling C<fdatasync>. |
594 | as calling C<fdatasync>. |
594 | |
595 | |
595 | Flags can be any combination of C<EIO_SYNC_FILE_RANGE_WAIT_BEFORE>, |
596 | Flags can be any combination of C<EIO_SYNC_FILE_RANGE_WAIT_BEFORE>, |
596 | C<EIO_SYNC_FILE_RANGE_WRITE> and C<EIO_SYNC_FILE_RANGE_WAIT_AFTER>. |
597 | C<EIO_SYNC_FILE_RANGE_WRITE> and C<EIO_SYNC_FILE_RANGE_WAIT_AFTER>. |
597 | |
598 | |
|
|
599 | =item eio_fallocate (int fd, int mode, off_t offset, off_t len, int pri, eio_cb cb, void *data) |
|
|
600 | |
|
|
601 | Calls C<fallocate> (note: I<NOT> C<posix_fallocate>!). If the syscall is |
|
|
602 | missing, then it returns failure and sets C<errno> to C<ENOSYS>. |
|
|
603 | |
|
|
604 | The C<mode> argument can be C<0> (for behaviour similar to |
|
|
605 | C<posix_fallocate>), or C<EIO_FALLOC_FL_KEEP_SIZE>, which keeps the size |
|
|
606 | of the file unchanged (but still preallocates space beyond end of file). |
|
|
607 | |
598 | =back |
608 | =back |
599 | |
609 | |
600 | =head3 LIBEIO-SPECIFIC REQUESTS |
610 | =head3 LIBEIO-SPECIFIC REQUESTS |
601 | |
611 | |
602 | These requests are specific to libeio and do not correspond to any OS call. |
612 | These requests are specific to libeio and do not correspond to any OS call. |
… | |
… | |
677 | |
687 | |
678 | =over 4 |
688 | =over 4 |
679 | |
689 | |
680 | =item eio_req *grp = eio_grp (eio_cb cb, void *data) |
690 | =item eio_req *grp = eio_grp (eio_cb cb, void *data) |
681 | |
691 | |
682 | Creates, submits and returns a group request. |
692 | Creates, submits and returns a group request. Note that it doesn't have a |
|
|
693 | priority, unlike all other requests. |
683 | |
694 | |
684 | =item eio_grp_add (eio_req *grp, eio_req *req) |
695 | =item eio_grp_add (eio_req *grp, eio_req *req) |
685 | |
696 | |
686 | Adds a request to the request group. |
697 | Adds a request to the request group. |
687 | |
698 | |
688 | =item eio_grp_cancel (eio_req *grp) |
699 | =item eio_grp_cancel (eio_req *grp) |
689 | |
700 | |
690 | Cancels all requests I<in> the group, but I<not> the group request |
701 | Cancels all requests I<in> the group, but I<not> the group request |
691 | itself. You can cancel the group request via a normal C<eio_cancel> call. |
702 | itself. You can cancel the group request I<and> all subrequests via a |
|
|
703 | normal C<eio_cancel> call. |
692 | |
704 | |
693 | |
|
|
694 | |
|
|
695 | =back |
705 | =back |
696 | |
706 | |
|
|
707 | =head4 GROUP REQUEST LIFETIME |
|
|
708 | |
|
|
709 | Left alone, a group request will instantly move to the pending state and |
|
|
710 | will be finished at the next call of C<eio_poll>. |
|
|
711 | |
|
|
712 | The usefulness stems from the fact that, if a subrequest is added to a |
|
|
713 | group I<before> a call to C<eio_poll>, via C<eio_grp_add>, then the group |
|
|
714 | will not finish until all the subrequests have finished. |
|
|
715 | |
|
|
716 | So the usage cycle of a group request is like this: after it is created, |
|
|
717 | you normally instantly add a subrequest. If none is added, the group |
|
|
718 | request will finish on it's own. As long as subrequests are added before |
|
|
719 | the group request is finished it will be kept from finishing, that is the |
|
|
720 | callbacks of any subrequests can, in turn, add more requests to the group, |
|
|
721 | and as long as any requests are active, the group request itself will not |
|
|
722 | finish. |
|
|
723 | |
|
|
724 | =head4 CREATING COMPOSITE REQUESTS |
|
|
725 | |
|
|
726 | Imagine you wanted to create an C<eio_load> request that opens a file, |
|
|
727 | reads it and closes it. This means it has to execute at least three eio |
|
|
728 | requests, but for various reasons it might be nice if that request looked |
|
|
729 | like any other eio request. |
|
|
730 | |
|
|
731 | This can be done with groups: |
|
|
732 | |
|
|
733 | =over 4 |
|
|
734 | |
|
|
735 | =item 1) create the request object |
|
|
736 | |
|
|
737 | Create a group that contains all further requests. This is the request you |
|
|
738 | can return as "the load request". |
|
|
739 | |
|
|
740 | =item 2) open the file, maybe |
|
|
741 | |
|
|
742 | Next, open the file with C<eio_open> and add the request to the group |
|
|
743 | request and you are finished setting up the request. |
|
|
744 | |
|
|
745 | If, for some reason, you cannot C<eio_open> (path is a null ptr?) you |
|
|
746 | can set C<< grp->result >> to C<-1> to signal an error and let the group |
|
|
747 | request finish on its own. |
|
|
748 | |
|
|
749 | =item 3) open callback adds more requests |
|
|
750 | |
|
|
751 | In the open callback, if the open was not successful, copy C<< |
|
|
752 | req->errorno >> to C<< grp->errorno >> and set C<< grp->errorno >> to |
|
|
753 | C<-1> to signal an error. |
|
|
754 | |
|
|
755 | Otherwise, malloc some memory or so and issue a read request, adding the |
|
|
756 | read request to the group. |
|
|
757 | |
|
|
758 | =item 4) continue issuing requests till finished |
|
|
759 | |
|
|
760 | In the real callback, check for errors and possibly continue with |
|
|
761 | C<eio_close> or any other eio request in the same way. |
|
|
762 | |
|
|
763 | As soon as no new requests are added the group request will finish. Make |
|
|
764 | sure you I<always> set C<< grp->result >> to some sensible value. |
|
|
765 | |
|
|
766 | =back |
|
|
767 | |
|
|
768 | =head4 REQUEST LIMITING |
697 | |
769 | |
698 | |
770 | |
699 | #TODO |
771 | #TODO |
700 | |
772 | |
701 | /*****************************************************************************/ |
|
|
702 | /* groups */ |
|
|
703 | |
|
|
704 | eio_req *eio_grp (eio_cb cb, void *data); |
|
|
705 | void eio_grp_feed (eio_req *grp, void (*feed)(eio_req *req), int limit); |
|
|
706 | void eio_grp_limit (eio_req *grp, int limit); |
773 | void eio_grp_limit (eio_req *grp, int limit); |
707 | void eio_grp_cancel (eio_req *grp); /* cancels all sub requests but not the group */ |
|
|
708 | |
774 | |
709 | |
775 | |
710 | =back |
776 | =back |
711 | |
777 | |
712 | |
778 | |