| … | |
… | |
| 687 | |
687 | |
| 688 | =over 4 |
688 | =over 4 |
| 689 | |
689 | |
| 690 | =item eio_req *grp = eio_grp (eio_cb cb, void *data) |
690 | =item eio_req *grp = eio_grp (eio_cb cb, void *data) |
| 691 | |
691 | |
| 692 | 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. |
| 693 | |
694 | |
| 694 | =item eio_grp_add (eio_req *grp, eio_req *req) |
695 | =item eio_grp_add (eio_req *grp, eio_req *req) |
| 695 | |
696 | |
| 696 | Adds a request to the request group. |
697 | Adds a request to the request group. |
| 697 | |
698 | |
| 698 | =item eio_grp_cancel (eio_req *grp) |
699 | =item eio_grp_cancel (eio_req *grp) |
| 699 | |
700 | |
| 700 | 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 |
| 701 | 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. |
| 702 | |
704 | |
| 703 | |
|
|
| 704 | |
|
|
| 705 | =back |
705 | =back |
| 706 | |
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 | There 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 steting up the request. |
|
|
744 | |
|
|
745 | If, for some reason, you cannot C<eio_open> (path is a null ptr?) you |
|
|
746 | cna set C<< grp->result >> to C<-1> to signal an error and let the gorup |
|
|
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 issuign 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 |
| 707 | |
769 | |
| 708 | |
770 | |
| 709 | #TODO |
771 | #TODO |
| 710 | |
772 | |
| 711 | /*****************************************************************************/ |
|
|
| 712 | /* groups */ |
|
|
| 713 | |
|
|
| 714 | eio_req *eio_grp (eio_cb cb, void *data); |
|
|
| 715 | void eio_grp_feed (eio_req *grp, void (*feed)(eio_req *req), int limit); |
|
|
| 716 | void eio_grp_limit (eio_req *grp, int limit); |
773 | void eio_grp_limit (eio_req *grp, int limit); |
| 717 | void eio_grp_cancel (eio_req *grp); /* cancels all sub requests but not the group */ |
|
|
| 718 | |
774 | |
| 719 | |
775 | |
| 720 | =back |
776 | =back |
| 721 | |
777 | |
| 722 | |
778 | |
