--- libeio/eio.pod	2011/07/14 19:34:39	1.25
+++ libeio/eio.pod	2011/09/26 17:10:10	1.29
@@ -47,21 +47,24 @@
 
 =head2 FORK SUPPORT
 
-Calling C<fork ()> is fully supported by this module - but you must not
-rely on this. It is currently implemented in these steps:
-
-  1. wait till all requests in "execute" state have been handled
-     (basically requests that are already handed over to the kernel).
-  2. fork
-  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
-cover your libc, for example, malloc and other libc functions are not
-fork-safe, so there is very little you can do after a fork, and in fact,
-the above might crash, and thus change.
+Usage of pthreads in a program changes the semantics of fork
+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.
+
+This library only works in the process that initialised it: Forking is
+fully supported, but using libeio in any other process than the one that
+called C<eio_init> is not.
+
+You might get around by not I<using> libeio before (or after) forking in
+the parent, and using it in the child afterwards. You could also try to
+call the L<eio_init> function again in the child, which will brutally
+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
 
@@ -81,6 +84,9 @@
 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.
@@ -229,13 +235,17 @@
 
 =back
 
+Members not explicitly described as accessible must not be
+accessed. Specifically, there is no guarantee that any members will still
+have the value they had when the request was submitted.
+
 The return value of the callback is normally C<0>, which tells libeio to
 continue normally. If a callback returns a nonzero value, libeio will
 stop processing results (in C<eio_poll>) and will return the value to its
 caller.
 
-Memory areas passed to libeio must stay valid as long as a request
-executes, with the exception of paths, which are being copied
+Memory areas passed to libeio wrappers must stay valid as long as a
+request executes, with the exception of paths, which are being copied
 internally. Any memory libeio itself allocates will be freed after the
 finish callback has been called. If you want to manage all memory passed
 to libeio yourself you can use the low-level API.
@@ -588,6 +598,13 @@
 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