diff options
author | root <root> | 2011-07-13 21:31:40 +0000 |
---|---|---|
committer | root <root> | 2011-07-13 21:31:40 +0000 |
commit | 2ca2adfe8748a6c38cea7accc626d567a0d6181e (patch) | |
tree | ce38f15950370e1c844c7d4caaaf48e0b11ef384 | |
parent | 4e772bc84196b8602643c5095bd1c2fca44d8f40 (diff) |
*** empty log message ***
-rw-r--r-- | eio.pod | 72 |
1 files changed, 64 insertions, 8 deletions
@@ -689,7 +689,8 @@ methods. =item eio_req *grp = eio_grp (eio_cb cb, void *data) -Creates, submits and returns a group request. +Creates, submits and returns a group request. Note that it doesn't have a +priority, unlike all other requests. =item eio_grp_add (eio_req *grp, eio_req *req) @@ -698,23 +699,78 @@ Adds a request to the request group. =item eio_grp_cancel (eio_req *grp) Cancels all requests I<in> the group, but I<not> the group request -itself. You can cancel the group request via a normal C<eio_cancel> call. +itself. You can cancel the group request I<and> all subrequests via a +normal C<eio_cancel> call. +=back + +=head4 GROUP REQUEST LIFETIME + +Left alone, a group request will instantly move to the pending state and +will be finished at the next call of C<eio_poll>. + +There usefulness stems from the fact that, if a subrequest is added to a +group I<before> a call to C<eio_poll>, via C<eio_grp_add>, then the group +will not finish until all the subrequests have finished. + +So the usage cycle of a group request is like this: after it is created, +you normally instantly add a subrequest. If none is added, the group +request will finish on it's own. As long as subrequests are added before +the group request is finished it will be kept from finishing, that is the +callbacks of any subrequests can, in turn, add more requests to the group, +and as long as any requests are active, the group request itself will not +finish. + +=head4 CREATING COMPOSITE REQUESTS + +Imagine you wanted to create an C<eio_load> request that opens a file, +reads it and closes it. This means it has to execute at least three eio +requests, but for various reasons it might be nice if that request looked +like any other eio request. + +This can be done with groups: + +=over 4 + +=item 1) create the request object +Create a group that contains all further requests. This is the request you +can return as "the load request". + +=item 2) open the file, maybe + +Next, open the file with C<eio_open> and add the request to the group +request and you are finished steting up the request. + +If, for some reason, you cannot C<eio_open> (path is a null ptr?) you +cna set C<< grp->result >> to C<-1> to signal an error and let the gorup +request finish on its own. + +=item 3) open callback adds more requests + +In the open callback, if the open was not successful, copy C<< +req->errorno >> to C<< grp->errorno >> and set C<< grp->errorno >> to +C<-1> to signal an error. + +Otherwise, malloc some memory or so and issue a read request, adding the +read request to the group. + +=item 4) continue issuign requests till finished + +In the real callback, check for errors and possibly continue with +C<eio_close> or any other eio request in the same way. + +As soon as no new requests are added the group request will finish. Make +sure you I<always> set C<< grp->result >> to some sensible value. =back +=head4 REQUEST LIMITING #TODO -/*****************************************************************************/ -/* groups */ - -eio_req *eio_grp (eio_cb cb, void *data); -void eio_grp_feed (eio_req *grp, void (*feed)(eio_req *req), int limit); void eio_grp_limit (eio_req *grp, int limit); -void eio_grp_cancel (eio_req *grp); /* cancels all sub requests but not the group */ =back |