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

Comparing libeio/eio.pod (file contents):
Revision 1.25 by root, Thu Jul 14 19:34:39 2011 UTC vs.
Revision 1.36 by root, Sun Jan 24 16:36:20 2016 UTC

 similar functions, as well as less rarely ones such as C<mknod>, C<futime>
 or C<readlink>.
 It also offers wrappers around C<sendfile> (Solaris, Linux, HP-UX and
 FreeBSD, with emulation on other platforms) and C<readahead> (Linux, with
-emulation elsewhere>).
+emulation elsewhere).
 The goal is to enable you to write fully non-blocking programs. For
 example, in a game server, you would not want to freeze for a few seconds
 just because the server is running a backup and you happen to call
 C<readdir>.
 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",
 This callback is invoked when libeio detects that all pending requests
 have been handled. It is "edge-triggered", that is, it will only be
 called once after C<want_poll>. To put it differently, C<want_poll> and
 C<done_poll> are invoked in pairs: after C<want_poll> you have to call
 C<eio_poll ()> until either C<eio_poll> indicates that everything has been
-handled or C<done_poll> has been called, which signals the same.
+handled or C<done_poll> has been called, which signals the same - only one
+method is needed.
 Note that C<eio_poll> might return after C<done_poll> and C<want_poll>
 have been called again, so watch out for races in your code.
+It is quite common to have an empty C<done_call> callback and only use
+the return value from C<eio_poll>, or, when C<eio_poll> is configured to
+handle all outstanding replies, it's enough to call C<eio_poll> once.
 As with C<want_poll>, this callback is called while locks are being held,
-so you I<must not call any libeio functions form within this callback>.
+so you I<must not call any libeio functions from within this callback>.
 =item int eio_poll ()
 This function has to be called whenever there are pending requests that
 need finishing. You usually call this after C<want_poll> has indicated
   {
     loop = EV_DEFAULT;
     ev_idle_init (&repeat_watcher, repeat);
     ev_async_init (&ready_watcher, ready);
-    ev_async_start (loop &watcher);
+    ev_async_start (loop, &watcher);
     eio_init (want_poll, 0);
   }
 For most other event loops, you would typically use a pipe - the event
 The C<void *data> member simply stores the value of the C<data> argument.
 =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
+Memory areas passed to libeio wrappers must stay valid as long as a
-executes, with the exception of paths, which are being copied
+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.
 For example, to open a file, you could do this:
 Cancel the request (and all its subrequests). If the request is currently
 executing it might still continue to execute, and in other cases it might
 still take a while till the request is cancelled.
-Even if cancelled, the finish callback will still be invoked - the
+When cancelled, the finish callback will not be invoked.
-callbacks of all cancellable requests need to check whether the request
-has been cancelled by calling C<EIO_CANCELLED (req)>:
-  static int
-  my_eio_cb (eio_req *req)
-  {
-    if (EIO_CANCELLED (req))
-      return 0;
-  }
-In addition, cancelled requests will I<either> have C<< req->result >>
-set to C<-1> and C<errno> to C<ECANCELED>, or I<otherwise> they were
-successfully executed, despite being cancelled (e.g. when they have
-already been executed at the time they were cancelled).
 C<EIO_CANCELLED> is still true for requests that have successfully
 executed, as long as C<eio_cancel> was called on them at some point.
 =back
 =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_mtouch (void *addr, size_t length, int flags, int pri, eio_cb cb, void *data)
-Reads (C<flags == 0>) or modifies (C<flags == EIO_MT_MODIFY) the given
+Reads (C<flags == 0>) or modifies (C<flags == EIO_MT_MODIFY>) the given
 memory area, page-wise, that is, it reads (or reads and writes back) the
 first octet of every page that spans the memory area.
 This can be used to page in some mmapped file, or dirty some pages. Note
 that dirtying is an unlocked read-write access, so races can ensue when
 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
+req->errorno >> to C<< grp->errorno >> and set C<< grp->result >> 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
+In the read 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
+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
 void eio_grp_limit     (eio_req *grp, int limit);
-=back
 =head1 LOW LEVEL REQUEST API
 #TODO
 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 (void *) * 4096> currently). If it is defined, but
+stack size (C<sizeof (void *) * 4096> currently). In all other cases, the
-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
+value must be an expression that evaluates to the desired stack size.
-stack size.
 =back
 =head1 PORTABILITY REQUIREMENTS

Diff Legend

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

Comparing libeio/eio.pod (file contents): Revision 1.25 by root, Thu Jul 14 19:34:39 2011 UTC vs. Revision 1.36 by root, Sun Jan 24 16:36:20 2016 UTC

Diff Legend

Comparing libeio/eio.pod (file contents):
Revision 1.25 by root, Thu Jul 14 19:34:39 2011 UTC vs.
Revision 1.36 by root, Sun Jan 24 16:36:20 2016 UTC