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

Comparing libeio/eio.pod (file contents):
Revision 1.22 by root, Fri Jul 8 01:12:39 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>.
… …
45Unlike the name component C<stamp> might indicate, it is also used for 45Unlike the name component C<stamp> might indicate, it is also used for
46time differences throughout libeio. 46time differences throughout libeio.
47 47
48=head2 FORK SUPPORT 48=head2 FORK SUPPORT
49 49
50Calling C<fork ()> is fully supported by this module - but you must not 50Usage of pthreads in a program changes the semantics of fork
51rely on this. It is currently implemented in these steps: 51considerably. Specifically, only async-safe functions can be called after
52fork. Libeio uses pthreads, so this applies, and makes using fork hard for
53anything but relatively fork + exec uses.
52 54
53 1. wait till all requests in "execute" state have been handled 55This library only works in the process that initialised it: Forking is
54 (basically requests that are already handed over to the kernel). 56fully supported, but using libeio in any other process than the one that
55 2. fork 57called C<eio_init> is not.
56 3. in the parent, continue business as usual, done
57 4. in the child, destroy all ready and pending requests and free the
58 memory used by the worker threads. This gives you a fully empty
59 libeio queue.
60 58
61Note, however, since libeio does use threads, the above guarantee doesn't 59You might get around by not I<using> libeio before (or after) forking in
62cover your libc, for example, malloc and other libc functions are not 60the parent, and using it in the child afterwards. You could also try to
63fork-safe, so there is very little you can do after a fork, and in fact, 61call the L<eio_init> function again in the child, which will brutally
64the above might crash, and thus change. 62reinitialise all data structures, which isn't POSIX conformant, but
63typically works.
64
65Otherwise, the only recommendation you should follow is: treat fork code
66the same way you treat signal handlers, and only ever call C<eio_init> in
67the process that uses it, and only once ever.
65 68
66=head1 INITIALISATION/INTEGRATION 69=head1 INITIALISATION/INTEGRATION
67 70
68Before you can call any eio functions you first have to initialise the 71Before you can call any eio functions you first have to initialise the
69library. The library integrates into any event loop, but can also be used 72library. The library integrates into any event loop, but can also be used
… …
78This function initialises the library. On success it returns C<0>, on 81This function initialises the library. On success it returns C<0>, on
79failure it returns C<-1> and sets C<errno> appropriately. 82failure it returns C<-1> and sets C<errno> appropriately.
80 83
81It accepts two function pointers specifying callbacks as argument, both of 84It accepts two function pointers specifying callbacks as argument, both of
82which can be C<0>, in which case the callback isn't called. 85which can be C<0>, in which case the callback isn't called.
86
87There is currently no way to change these callbacks later, or to
88"uninitialise" the library again.
83 89
84=item want_poll callback 90=item want_poll callback
85 91
86The C<want_poll> callback is invoked whenever libeio wants attention (i.e. 92The C<want_poll> callback is invoked whenever libeio wants attention (i.e.
87it wants to be polled by calling C<eio_poll>). It is "edge-triggered", 93it wants to be polled by calling C<eio_poll>). It is "edge-triggered",
… …
227 233
228The 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.
229 235
230=back 236=back
231 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
232The 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
233continue normally. If a callback returns a nonzero value, libeio will 243continue normally. If a callback returns a nonzero value, libeio will
234stop 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
235caller. 245caller.
236 246
237Memory 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
238executes, with the exception of paths, which are being copied 248request executes, with the exception of paths, which are being copied
239internally. Any memory libeio itself allocates will be freed after the 249internally. Any memory libeio itself allocates will be freed after the
240finish 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
241to libeio yourself you can use the low-level API. 251to libeio yourself you can use the low-level API.
242 252
243For example, to open a file, you could do this: 253For example, to open a file, you could do this:
… …
586=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)
587 597
588Calls 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
589emulated by simply reading the data (currently in 64kiB chunks). 599emulated by simply reading the data (currently in 64kiB chunks).
590 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
591=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)
592 609
593Calls 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
594as calling C<fdatasync>. 611as calling C<fdatasync>.
595 612
… …
613 630
614=over 4 631=over 4
615 632
616=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)
617 634
618Reads (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
619memory 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
620first octet of every page that spans the memory area. 637first octet of every page that spans the memory area.
621 638
622This 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
623that 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
… …
687 704
688=over 4 705=over 4
689 706
690=item eio_req *grp = eio_grp (eio_cb cb, void *data) 707=item eio_req *grp = eio_grp (eio_cb cb, void *data)
691 708
692Creates, submits and returns a group request. 709Creates, submits and returns a group request. Note that it doesn't have a
710priority, unlike all other requests.
693 711
694=item eio_grp_add (eio_req *grp, eio_req *req) 712=item eio_grp_add (eio_req *grp, eio_req *req)
695 713
696Adds a request to the request group. 714Adds a request to the request group.
697 715
698=item eio_grp_cancel (eio_req *grp) 716=item eio_grp_cancel (eio_req *grp)
699 717
700Cancels all requests I<in> the group, but I<not> the group request 718Cancels all requests I<in> the group, but I<not> the group request
701itself. You can cancel the group request via a normal C<eio_cancel> call. 719itself. You can cancel the group request I<and> all subrequests via a
720normal C<eio_cancel> call.
702 721
703
704
705=back 722=back
706 723
724=head4 GROUP REQUEST LIFETIME
725
726Left alone, a group request will instantly move to the pending state and
727will be finished at the next call of C<eio_poll>.
728
729The usefulness stems from the fact that, if a subrequest is added to a
730group I<before> a call to C<eio_poll>, via C<eio_grp_add>, then the group
731will not finish until all the subrequests have finished.
732
733So the usage cycle of a group request is like this: after it is created,
734you normally instantly add a subrequest. If none is added, the group
735request will finish on it's own. As long as subrequests are added before
736the group request is finished it will be kept from finishing, that is the
737callbacks of any subrequests can, in turn, add more requests to the group,
738and as long as any requests are active, the group request itself will not
739finish.
740
741=head4 CREATING COMPOSITE REQUESTS
742
743Imagine you wanted to create an C<eio_load> request that opens a file,
744reads it and closes it. This means it has to execute at least three eio
745requests, but for various reasons it might be nice if that request looked
746like any other eio request.
747
748This can be done with groups:
749
750=over 4
751
752=item 1) create the request object
753
754Create a group that contains all further requests. This is the request you
755can return as "the load request".
756
757=item 2) open the file, maybe
758
759Next, open the file with C<eio_open> and add the request to the group
760request and you are finished setting up the request.
761
762If, for some reason, you cannot C<eio_open> (path is a null ptr?) you
763can set C<< grp->result >> to C<-1> to signal an error and let the group
764request finish on its own.
765
766=item 3) open callback adds more requests
767
768In the open callback, if the open was not successful, copy C<<
769req->errorno >> to C<< grp->errorno >> and set C<< grp->result >> to
770C<-1> to signal an error.
771
772Otherwise, malloc some memory or so and issue a read request, adding the
773read request to the group.
774
775=item 4) continue issuing requests till finished
776
777In the read callback, check for errors and possibly continue with
778C<eio_close> or any other eio request in the same way.
779
780As soon as no new requests are added, the group request will finish. Make
781sure you I<always> set C<< grp->result >> to some sensible value.
782
783=back
784
785=head4 REQUEST LIMITING
707 786
708 787
709#TODO 788#TODO
710 789
711/*****************************************************************************/
712/* groups */
713
714eio_req *eio_grp (eio_cb cb, void *data);
715void eio_grp_feed (eio_req *grp, void (*feed)(eio_req *req), int limit);
716void eio_grp_limit (eio_req *grp, int limit); 790void eio_grp_limit (eio_req *grp, int limit);
717void eio_grp_cancel (eio_req *grp); /* cancels all sub requests but not the group */
718 791
719
720=back
721 792
722 793
723=head1 LOW LEVEL REQUEST API 794=head1 LOW LEVEL REQUEST API
724 795
725#TODO 796#TODO
… …
853This symbol governs the stack size for each eio thread. Libeio itself 924This symbol governs the stack size for each eio thread. Libeio itself
854was 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>
855requests, you might want to increase this. 926requests, you might want to increase this.
856 927
857If 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
858stack size (C<sizeof (long) * 4096> currently). If it is defined, but 929stack size (C<sizeof (void *) * 4096> currently). In all other cases, the
859C<0>, then the default operating system stack size will be used. In all
860other cases, the value must be an expression that evaluates to the desired 930value must be an expression that evaluates to the desired stack size.
861stack size.
862 931
863=back 932=back
864 933
865 934
866=head1 PORTABILITY REQUIREMENTS 935=head1 PORTABILITY REQUIREMENTS

Diff Legend

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