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

Comparing libeio/eio.pod (file contents):
Revision 1.23 by root, Wed Jul 13 21:31:40 2011 UTC vs.
Revision 1.26 by root, Mon Jul 18 02:59:58 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",
… …
707=head4 GROUP REQUEST LIFETIME 713=head4 GROUP REQUEST LIFETIME
708 714
709Left alone, a group request will instantly move to the pending state and 715Left alone, a group request will instantly move to the pending state and
710will be finished at the next call of C<eio_poll>. 716will be finished at the next call of C<eio_poll>.
711 717
712There usefulness stems from the fact that, if a subrequest is added to a 718The usefulness stems from the fact that, if a subrequest is added to a
713group I<before> a call to C<eio_poll>, via C<eio_grp_add>, then the group 719group I<before> a call to C<eio_poll>, via C<eio_grp_add>, then the group
714will not finish until all the subrequests have finished. 720will not finish until all the subrequests have finished.
715 721
716So the usage cycle of a group request is like this: after it is created, 722So the usage cycle of a group request is like this: after it is created,
717you normally instantly add a subrequest. If none is added, the group 723you normally instantly add a subrequest. If none is added, the group
… …
738can return as "the load request". 744can return as "the load request".
739 745
740=item 2) open the file, maybe 746=item 2) open the file, maybe
741 747
742Next, open the file with C<eio_open> and add the request to the group 748Next, open the file with C<eio_open> and add the request to the group
743request and you are finished steting up the request. 749request and you are finished setting up the request.
744 750
745If, for some reason, you cannot C<eio_open> (path is a null ptr?) you 751If, for some reason, you cannot C<eio_open> (path is a null ptr?) you
746cna set C<< grp->result >> to C<-1> to signal an error and let the gorup 752can set C<< grp->result >> to C<-1> to signal an error and let the group
747request finish on its own. 753request finish on its own.
748 754
749=item 3) open callback adds more requests 755=item 3) open callback adds more requests
750 756
751In the open callback, if the open was not successful, copy C<< 757In the open callback, if the open was not successful, copy C<<
… …
753C<-1> to signal an error. 759C<-1> to signal an error.
754 760
755Otherwise, malloc some memory or so and issue a read request, adding the 761Otherwise, malloc some memory or so and issue a read request, adding the
756read request to the group. 762read request to the group.
757 763
758=item 4) continue issuign requests till finished 764=item 4) continue issuing requests till finished
759 765
760In the real callback, check for errors and possibly continue with 766In the real callback, check for errors and possibly continue with
761C<eio_close> or any other eio request in the same way. 767C<eio_close> or any other eio request in the same way.
762 768
763As soon as no new requests are added the group request will finish. Make 769As soon as no new requests are added the group request will finish. Make
… …
909This symbol governs the stack size for each eio thread. Libeio itself 915This symbol governs the stack size for each eio thread. Libeio itself
910was written to use very little stackspace, but when using C<EIO_CUSTOM> 916was written to use very little stackspace, but when using C<EIO_CUSTOM>
911requests, you might want to increase this. 917requests, you might want to increase this.
912 918
913If this symbol is undefined (the default) then libeio will use its default 919If this symbol is undefined (the default) then libeio will use its default
914stack size (C<sizeof (long) * 4096> currently). If it is defined, but 920stack size (C<sizeof (void *) * 4096> currently). If it is defined, but
915C<0>, then the default operating system stack size will be used. In all 921C<0>, then the default operating system stack size will be used. In all
916other cases, the value must be an expression that evaluates to the desired 922other cases, the value must be an expression that evaluates to the desired
917stack size. 923stack size.
918 924
919=back 925=back

Diff Legend

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