[ViewVC] Diff of: cvs/libeio/eio.pod

Comparing libeio/eio.pod (file contents):
Revision 1.19 by root, Tue Jul 5 20:38:47 2011 UTC vs.
Revision 1.23 by root, Wed Jul 13 21:31:40 2011 UTC

…		…
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;
…		…
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	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
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

Diff Legend

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

Comparing libeio/eio.pod (file contents): Revision 1.19 by root, Tue Jul 5 20:38:47 2011 UTC vs. Revision 1.23 by root, Wed Jul 13 21:31:40 2011 UTC

Diff Legend

Comparing libeio/eio.pod (file contents):
Revision 1.19 by root, Tue Jul 5 20:38:47 2011 UTC vs.
Revision 1.23 by root, Wed Jul 13 21:31:40 2011 UTC