From: Eric Wong Date: Fri, 13 May 2011 02:28:41 +0000 (-0700) Subject: fix up documentation for fd vs IO objects X-Git-Tag: v4.0.0~1 X-Git-Url: https://repo.or.cz/w/ruby_io_splice.git/commitdiff_plain/48bfb5ce0706334fc8ba42e2f517623fbe90d8b4 fix up documentation for fd vs IO objects We support both, but IO objects are easier to use so refer to those in the documentation. --- diff --git a/ext/io_splice/io_splice_ext.c b/ext/io_splice/io_splice_ext.c index 80c8cde..ffccef1 100644 --- a/ext/io_splice/io_splice_ext.c +++ b/ext/io_splice/io_splice_ext.c @@ -137,14 +137,14 @@ static VALUE nogvl_splice(void *ptr) static ssize_t do_splice(int argc, VALUE *argv, unsigned dflags) { off_t i = 0, o = 0; - VALUE fd_in, off_in, fd_out, off_out, len, flags; + VALUE io_in, off_in, io_out, off_out, len, flags; struct splice_args a; ssize_t bytes; ssize_t total = 0; unsigned waitall; rb_scan_args(argc, argv, "51", - &fd_in, &off_in, &fd_out, &off_out, &len, &flags); + &io_in, &off_in, &io_out, &off_out, &len, &flags); a.off_in = NIL_P(off_in) ? NULL : (i = NUM2OFFT(off_in), &i); a.off_out = NIL_P(off_out) ? NULL : (o = NUM2OFFT(off_out), &o); @@ -155,16 +155,16 @@ static ssize_t do_splice(int argc, VALUE *argv, unsigned dflags) a.flags ^= WAITALL; for (;;) { - a.fd_in = check_fileno(fd_in); - a.fd_out = check_fileno(fd_out); + a.fd_in = check_fileno(io_in); + a.fd_out = check_fileno(io_out); bytes = (ssize_t)io_run(nogvl_splice, &a); if (bytes == -1) { if (errno == EINTR) continue; if (waitall && errno == EAGAIN) { - rb_io_wait_readable(check_fileno(fd_in)); + rb_io_wait_readable(check_fileno(io_in)); errno = EAGAIN; - rb_io_wait_writable(check_fileno(fd_out)); + rb_io_wait_writable(check_fileno(io_out)); continue; } if (total > 0) @@ -188,11 +188,11 @@ static ssize_t 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 + * IO.splice(io_in, off_in, io_out, off_out, len) => integer + * IO.splice(io_in, off_in, io_out, off_out, len, flags) => integer * - * Splice +len+ bytes from/to a pipe. Either +fd_in+ or +fd_out+ - * MUST be a pipe. +fd_in+ and +fd_out+ may BOTH be pipes as of + * Splice +len+ bytes from/to a pipe. Either +io_in+ or +io_out+ + * MUST be a pipe. +io_in+ and +io_out+ may BOTH be pipes as of * Linux 2.6.31 or later. * * +off_in+ and +off_out+ if non-nil may be used to @@ -201,22 +201,18 @@ static ssize_t do_splice(int argc, VALUE *argv, unsigned dflags) * +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 + * * IO::Splice::F_MOVE + * * IO::Splice::F_NONBLOCK + * * IO::Splice::F_MORE + * * IO::Splice::WAITALL * * Returns the number of bytes spliced. - * Raises EOFError when +fd_in+ has reached end of file. + * Raises EOFError when +io_in+ has reached end of file. * Raises Errno::EAGAIN if the IO::Splice::F_NONBLOCK flag is set * and the pipe has no data to read from or space to write to. May * also raise Errno::EAGAIN if the non-pipe descriptor has no data * to read from or space to write to. * - * rd, wr = (pipe = IO.pipe).map { |io| io.fileno } - * src_io, dst_io = File.open("/path/to/src"), File.open("/path/to/dst") - * src, dst = src_io.fileno, dst_io.fileno - * - * nr = IO.splice(src, nil, wr, nil, IO::Splice::PIPE_CAPA, 0) - * IO.splice(rd, nil, dst, nil, nr, 0) - * * As splice never exposes buffers to userspace, it will not take * into account userspace buffering done by Ruby or stdio. It is * also not subject to encoding/decoding filters under Ruby 1.9. @@ -241,8 +237,8 @@ static VALUE my_splice(int argc, VALUE *argv, VALUE self) /* * 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 + * IO.trysplice(io_in, off_in, io_out, off_out, len) => integer + * IO.trysplice(io_in, off_in, io_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. @@ -283,13 +279,13 @@ static VALUE nogvl_tee(void *ptr) static ssize_t do_tee(int argc, VALUE *argv, unsigned dflags) { - VALUE fd_in, fd_out, len, flags; + VALUE io_in, io_out, len, flags; struct tee_args a; ssize_t bytes; ssize_t total = 0; unsigned waitall; - rb_scan_args(argc, argv, "31", &fd_in, &fd_out, &len, &flags); + rb_scan_args(argc, argv, "31", &io_in, &io_out, &len, &flags); a.len = (size_t)NUM2SIZET(len); a.flags = NIL_P(flags) ? dflags : NUM2UINT(flags) | dflags; waitall = a.flags & WAITALL; @@ -297,16 +293,16 @@ static ssize_t do_tee(int argc, VALUE *argv, unsigned dflags) a.flags ^= WAITALL; for (;;) { - a.fd_in = check_fileno(fd_in); - a.fd_out = check_fileno(fd_out); + a.fd_in = check_fileno(io_in); + a.fd_out = check_fileno(io_out); bytes = (ssize_t)io_run(nogvl_tee, &a); if (bytes == -1) { if (errno == EINTR) continue; if (waitall && errno == EAGAIN) { - rb_io_wait_readable(check_fileno(fd_in)); + rb_io_wait_readable(check_fileno(io_in)); errno = EAGAIN; - rb_io_wait_writable(check_fileno(fd_out)); + rb_io_wait_writable(check_fileno(io_out)); continue; } if (total > 0) @@ -328,19 +324,22 @@ static ssize_t 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 + * IO.tee(io_in, io_out, len) => integer + * IO.tee(io_in, io_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+ + * Copies up to +len+ bytes of data from +io_in+ to +io_out+. +io_in+ + * and +io_out+ must both refer to pipe descriptors. +io_in+ and +io_out+ * may not be endpoints of the same pipe. * - * +flags+ may be zero (the default) or IO::Splice::F_NONBLOCK + * +flags+ may be zero (the default) or a combination of: + * * IO::Splice::F_NONBLOCK + * * IO::Splice::WAITALL + * * Other IO::Splice flags are currently unimplemented or have no effect. * * Returns the number of bytes duplicated if successful. - * Raises EOFError when +fd_in+ is closed and emptied. - * Raises Errno::EAGAIN when +fd_in+ is empty and/or +fd_out+ is full + * Raises EOFError when +io_in+ is closed and emptied. + * Raises Errno::EAGAIN when +io_in+ is empty and/or +io_out+ is full * and +flags+ contains IO::Splice::F_NONBLOCK * * Consider using IO.trytee if you are using IO::Splice::F_NONBLOCK @@ -363,8 +362,8 @@ static VALUE my_tee(int argc, VALUE *argv, VALUE self) /* * call-seq: - * IO.trytee(fd_in, fd_out, len) => integer - * IO.trytee(fd_in, fd_out, len, flags) => integer + * IO.trytee(io_in, io_out, len) => integer + * IO.trytee(io_in, io_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. @@ -456,13 +455,13 @@ 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 + * IO.vmsplice(io, string_array) => integer + * IO.vmsplice(io, string_array, flags) => integer + * IO.vmsplice(io, string) => integer + * IO.vmsplice(io, string, flags) => integer * - * Transfers an array of strings into the pipe descriptor given by fd. - * +fd+ must be the writable end of a pipe. + * Transfers an array of strings into the pipe descriptor given by io. + * +io+ must be the writable end of a pipe. * * This may allow the kernel to avoid data copies in some cases. * but is (probably) of limited usefulness in Ruby. If you have @@ -482,9 +481,9 @@ static VALUE my_vmsplice(int argc, VALUE * argv, VALUE self) ssize_t rv = 0; ssize_t left; struct vmsplice_args a; - VALUE fd, data, flags; + VALUE io, data, flags; - rb_scan_args(argc, argv, "21", &fd, &data, &flags); + rb_scan_args(argc, argv, "21", &io, &data, &flags); switch (TYPE(data)) { case T_STRING: { @@ -504,7 +503,7 @@ static VALUE my_vmsplice(int argc, VALUE * argv, VALUE self) "(expected a String or Array of strings)", rb_obj_classname(data)); } - a.fd = my_fileno(fd); + a.fd = my_fileno(io); a.flags = NIL_P(flags) ? 0 : NUM2UINT(flags); for (;;) { @@ -515,7 +514,7 @@ static VALUE my_vmsplice(int argc, VALUE * argv, VALUE self) if (a.flags & SPLICE_F_NONBLOCK) { rb_sys_fail("vmsplice"); } else { - a.fd = check_fileno(fd); + a.fd = check_fileno(io); if (rb_io_wait_writable(a.fd)) continue; } @@ -529,7 +528,7 @@ static VALUE my_vmsplice(int argc, VALUE * argv, VALUE self) if (rv > 0) break; if (errno == EINTR) { - a.fd = check_fileno(fd); + a.fd = check_fileno(io); continue; } rb_sys_fail("vmsplice");