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

Comparing libeio/eio.pod (file contents):
Revision 1.21 by root, Thu Jul 7 22:36:18 2011 UTC vs.
Revision 1.27 by root, Sun Jul 24 03:32:54 2011 UTC

… …
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",
… …
405 free (target); 411 free (target);
406 } 412 }
407 413
408=item eio_realpath (const char *path, int pri, eio_cb cb, void *data) 414=item eio_realpath (const char *path, int pri, eio_cb cb, void *data)
409 415
410Similar to the realpath libc function, but unlike that one, result is 416Similar to the realpath libc function, but unlike that one, C<<
411C<-1> on failure and the length of the returned path in C<ptr2> (which is 417req->result >> is C<-1> on failure. On success, the result is the length
412not 0-terminated) - this is similar to readlink. 418of the returned path in C<ptr2> (which is I<NOT> 0-terminated) - this is
419similar to readlink.
413 420
414=item eio_stat (const char *path, int pri, eio_cb cb, void *data) 421=item eio_stat (const char *path, int pri, eio_cb cb, void *data)
415 422
416=item eio_lstat (const char *path, int pri, eio_cb cb, void *data) 423=item eio_lstat (const char *path, int pri, eio_cb cb, void *data)
417 424
… …
585=item eio_readahead (int fd, off_t offset, size_t length, int pri, eio_cb cb, void *data) 592=item eio_readahead (int fd, off_t offset, size_t length, int pri, eio_cb cb, void *data)
586 593
587Calls C<readahead(2)>. If the syscall is missing, then the call is 594Calls C<readahead(2)>. If the syscall is missing, then the call is
588emulated by simply reading the data (currently in 64kiB chunks). 595emulated by simply reading the data (currently in 64kiB chunks).
589 596
597=item eio_syncfs (int fd, int pri, eio_cb cb, void *data)
598
599Calls Linux' C<syncfs> syscall, if available. Returns C<-1> and sets
600C<errno> to C<ENOSYS> if the call is missing I<but still calls sync()>,
601if the C<fd> is C<< >= 0 >>, so you can probe for the availability of the
602syscall with a negative C<fd> argument and checking for C<-1/ENOSYS>.
603
590=item eio_sync_file_range (int fd, off_t offset, size_t nbytes, unsigned int flags, int pri, eio_cb cb, void *data) 604=item eio_sync_file_range (int fd, off_t offset, size_t nbytes, unsigned int flags, int pri, eio_cb cb, void *data)
591 605
592Calls C<sync_file_range>. If the syscall is missing, then this is the same 606Calls C<sync_file_range>. If the syscall is missing, then this is the same
593as calling C<fdatasync>. 607as calling C<fdatasync>.
594 608
… …
686 700
687=over 4 701=over 4
688 702
689=item eio_req *grp = eio_grp (eio_cb cb, void *data) 703=item eio_req *grp = eio_grp (eio_cb cb, void *data)
690 704
691Creates, submits and returns a group request. 705Creates, submits and returns a group request. Note that it doesn't have a
706priority, unlike all other requests.
692 707
693=item eio_grp_add (eio_req *grp, eio_req *req) 708=item eio_grp_add (eio_req *grp, eio_req *req)
694 709
695Adds a request to the request group. 710Adds a request to the request group.
696 711
697=item eio_grp_cancel (eio_req *grp) 712=item eio_grp_cancel (eio_req *grp)
698 713
699Cancels all requests I<in> the group, but I<not> the group request 714Cancels all requests I<in> the group, but I<not> the group request
700itself. You can cancel the group request via a normal C<eio_cancel> call. 715itself. You can cancel the group request I<and> all subrequests via a
716normal C<eio_cancel> call.
701 717
702
703
704=back 718=back
705 719
720=head4 GROUP REQUEST LIFETIME
721
722Left alone, a group request will instantly move to the pending state and
723will be finished at the next call of C<eio_poll>.
724
725The usefulness stems from the fact that, if a subrequest is added to a
726group I<before> a call to C<eio_poll>, via C<eio_grp_add>, then the group
727will not finish until all the subrequests have finished.
728
729So the usage cycle of a group request is like this: after it is created,
730you normally instantly add a subrequest. If none is added, the group
731request will finish on it's own. As long as subrequests are added before
732the group request is finished it will be kept from finishing, that is the
733callbacks of any subrequests can, in turn, add more requests to the group,
734and as long as any requests are active, the group request itself will not
735finish.
736
737=head4 CREATING COMPOSITE REQUESTS
738
739Imagine you wanted to create an C<eio_load> request that opens a file,
740reads it and closes it. This means it has to execute at least three eio
741requests, but for various reasons it might be nice if that request looked
742like any other eio request.
743
744This can be done with groups:
745
746=over 4
747
748=item 1) create the request object
749
750Create a group that contains all further requests. This is the request you
751can return as "the load request".
752
753=item 2) open the file, maybe
754
755Next, open the file with C<eio_open> and add the request to the group
756request and you are finished setting up the request.
757
758If, for some reason, you cannot C<eio_open> (path is a null ptr?) you
759can set C<< grp->result >> to C<-1> to signal an error and let the group
760request finish on its own.
761
762=item 3) open callback adds more requests
763
764In the open callback, if the open was not successful, copy C<<
765req->errorno >> to C<< grp->errorno >> and set C<< grp->errorno >> to
766C<-1> to signal an error.
767
768Otherwise, malloc some memory or so and issue a read request, adding the
769read request to the group.
770
771=item 4) continue issuing requests till finished
772
773In the real callback, check for errors and possibly continue with
774C<eio_close> or any other eio request in the same way.
775
776As 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.
778
779=back
780
781=head4 REQUEST LIMITING
706 782
707 783
708#TODO 784#TODO
709 785
710/*****************************************************************************/
711/* groups */
712
713eio_req *eio_grp (eio_cb cb, void *data);
714void eio_grp_feed (eio_req *grp, void (*feed)(eio_req *req), int limit);
715void eio_grp_limit (eio_req *grp, int limit); 786void eio_grp_limit (eio_req *grp, int limit);
716void eio_grp_cancel (eio_req *grp); /* cancels all sub requests but not the group */
717 787
718 788
719=back 789=back
720 790
721 791
… …
852This symbol governs the stack size for each eio thread. Libeio itself 922This symbol governs the stack size for each eio thread. Libeio itself
853was written to use very little stackspace, but when using C<EIO_CUSTOM> 923was written to use very little stackspace, but when using C<EIO_CUSTOM>
854requests, you might want to increase this. 924requests, you might want to increase this.
855 925
856If this symbol is undefined (the default) then libeio will use its default 926If this symbol is undefined (the default) then libeio will use its default
857stack size (C<sizeof (long) * 4096> currently). If it is defined, but 927stack size (C<sizeof (void *) * 4096> currently). If it is defined, but
858C<0>, then the default operating system stack size will be used. In all 928C<0>, then the default operating system stack size will be used. In all
859other cases, the value must be an expression that evaluates to the desired 929other cases, the value must be an expression that evaluates to the desired
860stack size. 930stack size.
861 931
862=back 932=back

Diff Legend

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