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

Comparing libeio/eio.pod (file contents):
Revision 1.26 by root, Mon Jul 18 02:59:58 2011 UTC vs.
Revision 1.33 by root, Thu Jan 24 06:26:18 2013 UTC

… …
25similar functions, as well as less rarely ones such as C<mknod>, C<futime> 25similar functions, as well as less rarely ones such as C<mknod>, C<futime>
26or C<readlink>. 26or C<readlink>.
27 27
28It also offers wrappers around C<sendfile> (Solaris, Linux, HP-UX and 28It also offers wrappers around C<sendfile> (Solaris, Linux, HP-UX and
29FreeBSD, with emulation on other platforms) and C<readahead> (Linux, with 29FreeBSD, with emulation on other platforms) and C<readahead> (Linux, with
30emulation elsewhere>). 30emulation elsewhere).
31 31
32The goal is to enable you to write fully non-blocking programs. For 32The goal is to enable you to write fully non-blocking programs. For
33example, in a game server, you would not want to freeze for a few seconds 33example, in a game server, you would not want to freeze for a few seconds
34just because the server is running a backup and you happen to call 34just because the server is running a backup and you happen to call
35C<readdir>. 35C<readdir>.
… …
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:
… …
592=item eio_readahead (int fd, off_t offset, size_t length, int pri, eio_cb cb, void *data) 596=item eio_readahead (int fd, off_t offset, size_t length, int pri, eio_cb cb, void *data)
593 597
594Calls C<readahead(2)>. If the syscall is missing, then the call is 598Calls C<readahead(2)>. If the syscall is missing, then the call is
595emulated by simply reading the data (currently in 64kiB chunks). 599emulated by simply reading the data (currently in 64kiB chunks).
596 600
601=item eio_syncfs (int fd, int pri, eio_cb cb, void *data)
602
603Calls Linux' C<syncfs> syscall, if available. Returns C<-1> and sets
604C<errno> to C<ENOSYS> if the call is missing I<but still calls sync()>,
605if the C<fd> is C<< >= 0 >>, so you can probe for the availability of the
606syscall with a negative C<fd> argument and checking for C<-1/ENOSYS>.
607
597=item eio_sync_file_range (int fd, off_t offset, size_t nbytes, unsigned int flags, int pri, eio_cb cb, void *data) 608=item eio_sync_file_range (int fd, off_t offset, size_t nbytes, unsigned int flags, int pri, eio_cb cb, void *data)
598 609
599Calls C<sync_file_range>. If the syscall is missing, then this is the same 610Calls C<sync_file_range>. If the syscall is missing, then this is the same
600as calling C<fdatasync>. 611as calling C<fdatasync>.
601 612
… …
619 630
620=over 4 631=over 4
621 632
622=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)
623 634
624Reads (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
625memory 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
626first octet of every page that spans the memory area. 637first octet of every page that spans the memory area.
627 638
628This 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
629that 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
… …
753request finish on its own. 764request finish on its own.
754 765
755=item 3) open callback adds more requests 766=item 3) open callback adds more requests
756 767
757In the open callback, if the open was not successful, copy C<< 768In the open callback, if the open was not successful, copy C<<
758req->errorno >> to C<< grp->errorno >> and set C<< grp->errorno >> to 769req->errorno >> to C<< grp->errorno >> and set C<< grp->result >> to
759C<-1> to signal an error. 770C<-1> to signal an error.
760 771
761Otherwise, 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
762read request to the group. 773read request to the group.
763 774
764=item 4) continue issuing requests till finished 775=item 4) continue issuing requests till finished
765 776
766In the real callback, check for errors and possibly continue with 777In the read callback, check for errors and possibly continue with
767C<eio_close> or any other eio request in the same way. 778C<eio_close> or any other eio request in the same way.
768 779
769As 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
770sure you I<always> set C<< grp->result >> to some sensible value. 781sure you I<always> set C<< grp->result >> to some sensible value.
771 782
772=back 783=back
773 784
774=head4 REQUEST LIMITING 785=head4 REQUEST LIMITING
… …
776 787
777#TODO 788#TODO
778 789
779void eio_grp_limit (eio_req *grp, int limit); 790void eio_grp_limit (eio_req *grp, int limit);
780 791
781
782=back
783 792
784 793
785=head1 LOW LEVEL REQUEST API 794=head1 LOW LEVEL REQUEST API
786 795
787#TODO 796#TODO
… …
915This symbol governs the stack size for each eio thread. Libeio itself 924This symbol governs the stack size for each eio thread. Libeio itself
916was written to use very little stackspace, but when using C<EIO_CUSTOM> 925was written to use very little stackspace, but when using C<EIO_CUSTOM>
917requests, you might want to increase this. 926requests, you might want to increase this.
918 927
919If this symbol is undefined (the default) then libeio will use its default 928If this symbol is undefined (the default) then libeio will use its default
920stack size (C<sizeof (void *) * 4096> currently). If it is defined, but 929stack size (C<sizeof (void *) * 4096> currently). In all other cases, the
921C<0>, then the default operating system stack size will be used. In all
922other cases, the value must be an expression that evaluates to the desired 930value must be an expression that evaluates to the desired stack size.
923stack size.
924 931
925=back 932=back
926 933
927 934
928=head1 PORTABILITY REQUIREMENTS 935=head1 PORTABILITY REQUIREMENTS

Diff Legend

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