ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libeio/eio.pod
(Generate patch)

Comparing libeio/eio.pod (file contents):
Revision 1.27 by root, Sun Jul 24 03:32:54 2011 UTC vs.
Revision 1.31 by root, Fri Dec 28 20:05:45 2012 UTC

… …
233 233
234The C<void *data> member simply stores the value of the C<data> argument. 234The C<void *data> member simply stores the value of the C<data> argument.
235 235
236=back 236=back
237 237
238Members not explicitly described as accessible must not be
239accessed. Specifically, there is no guarantee that any members will still
240have the value they had when the request was submitted.
241
238The return value of the callback is normally C<0>, which tells libeio to 242The return value of the callback is normally C<0>, which tells libeio to
239continue normally. If a callback returns a nonzero value, libeio will 243continue normally. If a callback returns a nonzero value, libeio will
240stop processing results (in C<eio_poll>) and will return the value to its 244stop processing results (in C<eio_poll>) and will return the value to its
241caller. 245caller.
242 246
243Memory areas passed to libeio must stay valid as long as a request 247Memory areas passed to libeio wrappers must stay valid as long as a
244executes, with the exception of paths, which are being copied 248request executes, with the exception of paths, which are being copied
245internally. Any memory libeio itself allocates will be freed after the 249internally. Any memory libeio itself allocates will be freed after the
246finish callback has been called. If you want to manage all memory passed 250finish callback has been called. If you want to manage all memory passed
247to libeio yourself you can use the low-level API. 251to libeio yourself you can use the low-level API.
248 252
249For example, to open a file, you could do this: 253For example, to open a file, you could do this:
… …
626 630
627=over 4 631=over 4
628 632
629=item eio_mtouch (void *addr, size_t length, int flags, int pri, eio_cb cb, void *data) 633=item eio_mtouch (void *addr, size_t length, int flags, int pri, eio_cb cb, void *data)
630 634
631Reads (C<flags == 0>) or modifies (C<flags == EIO_MT_MODIFY) the given 635Reads (C<flags == 0>) or modifies (C<flags == EIO_MT_MODIFY>) the given
632memory area, page-wise, that is, it reads (or reads and writes back) the 636memory area, page-wise, that is, it reads (or reads and writes back) the
633first octet of every page that spans the memory area. 637first octet of every page that spans the memory area.
634 638
635This can be used to page in some mmapped file, or dirty some pages. Note 639This can be used to page in some mmapped file, or dirty some pages. Note
636that dirtying is an unlocked read-write access, so races can ensue when 640that dirtying is an unlocked read-write access, so races can ensue when
… …
760request finish on its own. 764request finish on its own.
761 765
762=item 3) open callback adds more requests 766=item 3) open callback adds more requests
763 767
764In the open callback, if the open was not successful, copy C<< 768In the open callback, if the open was not successful, copy C<<
765req->errorno >> to C<< grp->errorno >> and set C<< grp->errorno >> to 769req->errorno >> to C<< grp->errorno >> and set C<< grp->result >> to
766C<-1> to signal an error. 770C<-1> to signal an error.
767 771
768Otherwise, malloc some memory or so and issue a read request, adding the 772Otherwise, malloc some memory or so and issue a read request, adding the
769read request to the group. 773read request to the group.
770 774
771=item 4) continue issuing requests till finished 775=item 4) continue issuing requests till finished
772 776
773In the real callback, check for errors and possibly continue with 777In the read callback, check for errors and possibly continue with
774C<eio_close> or any other eio request in the same way. 778C<eio_close> or any other eio request in the same way.
775 779
776As soon as no new requests are added the group request will finish. Make 780As soon as no new requests are added, the group request will finish. Make
777sure you I<always> set C<< grp->result >> to some sensible value. 781sure you I<always> set C<< grp->result >> to some sensible value.
778 782
779=back 783=back
780 784
781=head4 REQUEST LIMITING 785=head4 REQUEST LIMITING

Diff Legend

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