[ViewVC] Diff of: cvs/libeio/eio.pod

Comparing libeio/eio.pod (file contents):
Revision 1.22 by root, Fri Jul 8 01:12:39 2011 UTC vs.
Revision 1.27 by root, Sun Jul 24 03:32:54 2011 UTC

 Unlike the name component C<stamp> might indicate, it is also used for
 time differences throughout libeio.
 =head2 FORK SUPPORT
-Calling C<fork ()> is fully supported by this module - but you must not
+Usage of pthreads in a program changes the semantics of fork
-rely on this. It is currently implemented in these steps:
+considerably. Specifically, only async-safe functions can be called after
+fork. Libeio uses pthreads, so this applies, and makes using fork hard for
+anything but relatively fork + exec uses.
-  1. wait till all requests in "execute" state have been handled
+This library only works in the process that initialised it: Forking is
-     (basically requests that are already handed over to the kernel).
+fully supported, but using libeio in any other process than the one that
-  2. fork
+called C<eio_init> is not.
-  3. in the parent, continue business as usual, done
-  4. in the child, destroy all ready and pending requests and free the
-     memory used by the worker threads. This gives you a fully empty
-     libeio queue.
-Note, however, since libeio does use threads, the above guarantee doesn't
+You might get around by not I<using> libeio before (or after) forking in
-cover your libc, for example, malloc and other libc functions are not
+the parent, and using it in the child afterwards. You could also try to
-fork-safe, so there is very little you can do after a fork, and in fact,
+call the L<eio_init> function again in the child, which will brutally
-the above might crash, and thus change.
+reinitialise all data structures, which isn't POSIX conformant, but
+typically works.
+Otherwise, the only recommendation you should follow is: treat fork code
+the same way you treat signal handlers, and only ever call C<eio_init> in
+the process that uses it, and only once ever.
 =head1 INITIALISATION/INTEGRATION
 Before you can call any eio functions you first have to initialise the
 library. The library integrates into any event loop, but can also be used
 This function initialises the library. On success it returns C<0>, on
 failure it returns C<-1> and sets C<errno> appropriately.
 It accepts two function pointers specifying callbacks as argument, both of
 which can be C<0>, in which case the callback isn't called.
+There is currently no way to change these callbacks later, or to
+"uninitialise" the library again.
 =item want_poll callback
 The C<want_poll> callback is invoked whenever libeio wants attention (i.e.
 it wants to be polled by calling C<eio_poll>). It is "edge-triggered",
 =item eio_readahead (int fd, off_t offset, size_t length, int pri, eio_cb cb, void *data)
 Calls C<readahead(2)>. If the syscall is missing, then the call is
 emulated by simply reading the data (currently in 64kiB chunks).
+=item eio_syncfs (int fd, int pri, eio_cb cb, void *data)
+Calls Linux' C<syncfs> syscall, if available. Returns C<-1> and sets
+C<errno> to C<ENOSYS> if the call is missing I<but still calls sync()>,
+if the C<fd> is C<< >= 0 >>, so you can probe for the availability of the
+syscall with a negative C<fd> argument and checking for C<-1/ENOSYS>.
 =item eio_sync_file_range (int fd, off_t offset, size_t nbytes, unsigned int flags, int pri, eio_cb cb, void *data)
 Calls C<sync_file_range>. If the syscall is missing, then this is the same
 as calling C<fdatasync>.
 =over 4
 =item eio_req *grp = eio_grp (eio_cb cb, void *data)
-Creates, submits and returns a group request.
+Creates, submits and returns a group request. Note that it doesn't have a
+priority, unlike all other requests.
 =item eio_grp_add (eio_req *grp, eio_req *req)
 Adds a request to the request group.
 =item eio_grp_cancel (eio_req *grp)
 Cancels all requests I<in> the group, but I<not> the group request
-itself. You can cancel the group request via a normal C<eio_cancel> call.
+itself. You can cancel the group request I<and> all subrequests via a
+normal C<eio_cancel> call.
 =back
+=head4 GROUP REQUEST LIFETIME
+Left alone, a group request will instantly move to the pending state and
+will be finished at the next call of C<eio_poll>.
+The usefulness stems from the fact that, if a subrequest is added to a
+group I<before> a call to C<eio_poll>, via C<eio_grp_add>, then the group
+will not finish until all the subrequests have finished.
+So the usage cycle of a group request is like this: after it is created,
+you normally instantly add a subrequest. If none is added, the group
+request will finish on it's own. As long as subrequests are added before
+the group request is finished it will be kept from finishing, that is the
+callbacks of any subrequests can, in turn, add more requests to the group,
+and as long as any requests are active, the group request itself will not
+finish.
+=head4 CREATING COMPOSITE REQUESTS
+Imagine you wanted to create an C<eio_load> request that opens a file,
+reads it and closes it. This means it has to execute at least three eio
+requests, but for various reasons it might be nice if that request looked
+like any other eio request.
+This can be done with groups:
+=over 4
+=item 1) create the request object
+Create a group that contains all further requests. This is the request you
+can return as "the load request".
+=item 2) open the file, maybe
+Next, open the file with C<eio_open> and add the request to the group
+request and you are finished setting up the request.
+If, for some reason, you cannot C<eio_open> (path is a null ptr?) you
+can set C<< grp->result >> to C<-1> to signal an error and let the group
+request finish on its own.
+=item 3) open callback adds more requests
+In the open callback, if the open was not successful, copy C<<
+req->errorno >> to C<< grp->errorno >> and set C<< grp->errorno >> to
+C<-1> to signal an error.
+Otherwise, malloc some memory or so and issue a read request, adding the
+read request to the group.
+=item 4) continue issuing requests till finished
+In the real callback, check for errors and possibly continue with
+C<eio_close> or any other eio request in the same way.
+As soon as no new requests are added the group request will finish. Make
+sure you I<always> set C<< grp->result >> to some sensible value.
+=back
+=head4 REQUEST LIMITING
 #TODO
-/*****************************************************************************/
-/* groups */
-eio_req *eio_grp       (eio_cb cb, void *data);
-void eio_grp_feed      (eio_req *grp, void (*feed)(eio_req *req), int limit);
 void eio_grp_limit     (eio_req *grp, int limit);
-void eio_grp_cancel    (eio_req *grp); /* cancels all sub requests but not the group */
 =back
 This symbol governs the stack size for each eio thread. Libeio itself
 was written to use very little stackspace, but when using C<EIO_CUSTOM>
 requests, you might want to increase this.
 If this symbol is undefined (the default) then libeio will use its default
-stack size (C<sizeof (long) * 4096> currently).  If it is defined, but
+stack size (C<sizeof (void *) * 4096> currently). If it is defined, but
 C<0>, then the default operating system stack size will be used. In all
 other cases, the value must be an expression that evaluates to the desired
 stack size.
 =back

Diff Legend

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

Comparing libeio/eio.pod (file contents): Revision 1.22 by root, Fri Jul 8 01:12:39 2011 UTC vs. Revision 1.27 by root, Sun Jul 24 03:32:54 2011 UTC

Diff Legend

Comparing libeio/eio.pod (file contents):
Revision 1.22 by root, Fri Jul 8 01:12:39 2011 UTC vs.
Revision 1.27 by root, Sun Jul 24 03:32:54 2011 UTC