doc: RDoc for new interfaces and changes

And yes, encourage them for non-blocking I/O users.

1 files changed, 39 insertions, 1 deletions

diff --git a/ext/io_splice/io_splice_ext.c b/ext/io_splice/io_splice_ext.c
index 14f7042..dc1e74d 100644
--- a/ext/io_splice/io_splice_ext.c
+++ b/ext/io_splice/io_splice_ext.c
@@ -148,6 +148,7 @@ static long do_splice(int argc, VALUE *argv, unsigned dflags)
 
 /*
  * call-seq:
+ *    IO.splice(fd_in, off_in, fd_out, off_out, len) => integer
  *    IO.splice(fd_in, off_in, fd_out, off_out, len, flags) => integer
  *
  * Splice +len+ bytes from/to a pipe.  Either +fd_in+ or +fd_out+
@@ -157,6 +158,7 @@ static long do_splice(int argc, VALUE *argv, unsigned dflags)
  * +off_in+ and +off_out+ if non-nil may be used to
  * specify an offset for the non-pipe file descriptor.
  *
+ * +flags+ defaults to zero if unspecified.
  * +flags+ may be a bitmask of the following flags:
  *
  * IO::Splice::F_MOVE, IO::Splice::F_NONBLOCK, IO::Splice::F_MORE
@@ -179,6 +181,10 @@ static long do_splice(int argc, VALUE *argv, unsigned dflags)
  * into account userspace buffering done by Ruby or stdio.  It is
  * also not subject to encoding/decoding filters under Ruby 1.9.
  *
+ * Consider using IO.trysplice if you are using non-blocking I/O on
+ * both descriptors as it avoids the cost of raising common Errno::EAGAIN
+ * exceptions.
+ *
  * See manpage for full documentation:
  * http://kernel.org/doc/man-pages/online/pages/man2/splice.2.html
  */
@@ -193,6 +199,19 @@ static VALUE my_splice(int argc, VALUE *argv, VALUE self)
         return LONG2NUM(n);
 }
 
+/*
+ * call-seq:
+ *    IO.trysplice(fd_in, off_in, fd_out, off_out, len) => integer
+ *    IO.trysplice(fd_in, off_in, fd_out, off_out, len, flags) => integer
+ *
+ * Exactly like IO.splice, except +:EAGAIN+ is returned when either
+ * the read or write end would block instead of raising Errno::EAGAIN.
+ *
+ * IO::Splice::F_NONBLOCK is always passed for the pipe descriptor,
+ * but this can still block if the non-pipe descriptor is blocking.
+ *
+ * See IO.splice documentation for more details.
+ */
 static VALUE trysplice(int argc, VALUE *argv, VALUE self)
 {
         long n = do_splice(argc, argv, SPLICE_F_NONBLOCK);
@@ -238,13 +257,14 @@ static long do_tee(int argc, VALUE *argv, unsigned dflags)
 
 /*
  * call-seq:
+ *   IO.tee(fd_in, fd_out, len) => integer
  *   IO.tee(fd_in, fd_out, len, flags) => integer
  *
  * Copies up to +len+ bytes of data from +fd_in+ to +fd_out+.  +fd_in+
  * and +fd_out+ must both refer to pipe descriptors.  +fd_in+ and +fd_out+
  * may not be endpoints of the same pipe.
  *
- * +flags+ may be zero or IO::Splice::F_NONBLOCK
+ * +flags+ may be zero (the default) or IO::Splice::F_NONBLOCK
  * Other IO::Splice flags are currently unimplemented or have no effect.
  *
  * Returns the number of bytes duplicated if successful.
@@ -252,6 +272,9 @@ static long do_tee(int argc, VALUE *argv, unsigned dflags)
  * Raises Errno::EAGAIN when +fd_in+ is empty and/or +fd_out+ is full
  * and +flags+ contains IO::Splice::F_NONBLOCK
  *
+ * Consider using IO.trytee if you are using IO::Splice::F_NONBLOCK
+ * as it avoids the cost of raising common Errno::EAGAIN exceptions.
+ *
  * See manpage for full documentation:
  * http://kernel.org/doc/man-pages/online/pages/man2/tee.2.html
  */
@@ -267,6 +290,19 @@ static VALUE my_tee(int argc, VALUE *argv, VALUE self)
         return LONG2NUM(n);
 }
 
+/*
+ * call-seq:
+ *    IO.trytee(fd_in, fd_out, len) => integer
+ *    IO.trytee(fd_in, fd_out, len, flags) => integer
+ *
+ * Exactly like IO.tee, except +:EAGAIN+ is returned when either
+ * the read or write end would block instead of raising Errno::EAGAIN.
+ *
+ * IO::Splice::F_NONBLOCK is always passed for the pipe descriptor,
+ * but this can still block if the non-pipe descriptor is blocking.
+ *
+ * See IO.tee documentation for more details.
+ */
 static VALUE trytee(int argc, VALUE *argv, VALUE self)
 {
         long n = do_tee(argc, argv, SPLICE_F_NONBLOCK);
@@ -349,7 +385,9 @@ static void advance_vmsplice_args(struct vmsplice_args *a, long n)
 
 /*
  * call-seq:
+ *   IO.vmsplice(fd, string_array) => integer
  *   IO.vmsplice(fd, string_array, flags) => integer
+ *   IO.vmsplice(fd, string) => integer
  *   IO.vmsplice(fd, string, flags) => integer
  *
  * Transfers an array of strings into the pipe descriptor given by fd.