splice.rb in io_splice-4.3.0

- old
+ new

@@ -1,11 +1,19 @@
 # -*- encoding: binary -*-
 require 'io_splice_ext'
 require 'io/wait'
 
 module IO::Splice
+  @warned = false
 
+  def self.__deprecated
+    return if @warned
+    warn("IO::Splice.{copy_stream,full} are deprecated " \
+         "and to be removed in io_splice 5.x")
+    @warned = true
+  end
+
   # The maximum default capacity of the pipe in bytes.
   # Under stock Linux, this is 65536 bytes as of 2.6.11, and 4096 before
   # We detect this at runtime as it is easy to recompile the kernel
   # and set a new value.
   # Starting with Linux 2.6.35, pipe capacity will be tunable
@@ -34,14 +42,23 @@
   # If +len+ is specified, then only +len+ bytes are copied and
   # +EOFError+ is raised if fewer than +len+ bytes could be copied.
   # Otherwise the copy will be until EOF is reached on the +src+.
   # +src+ and +dst+ must be IO objects or respond to +to_io+
   #
-  # This is nearly a drop-in replacement for IO.copy_stream (in Ruby 1.9)
-  # but does not take into account userspace I/O buffers nor IO-like
-  # objects with no underlying file descriptor (e.g. StringIO).
+  # Unlike IO.copy_stream, this does not take into account
+  # userspace I/O buffers nor IO-like objects with no underlying
+  # file descriptor (e.g. StringIO).
+  #
+  # This is unsafe for socket-to-socket copies unless there is an
+  # active (blocking) reader on the other end.
+  #
+  # This method is deprecated and will be removed in a future, as it is
+  # potentially unsafe for socket-to-socket operations and difficult-to-use.
+  # IO.copy_stream on Linux 2.6.33 and later allows using sendfile for
+  # file-to-file copies, so this offers no advantage.
   def self.copy_stream(src, dst, len = nil, src_offset = nil)
+    __deprecated
     close = []
     need_open?(src) and close << (src = File.open(src))
     need_open?(dst) and close << (dst = File.open(dst, "w"))
     rv = len
     src, dst = src.to_io, dst.to_io
@@ -88,9 +105,10 @@
   # unless there is another process or native thread doing a blocking
   # read on the other end of the +dst+ pipe.
   #
   # This method is safe for splicing a pipe +src+ into any type of +dst+ IO.
   def self.full(src, dst, len, src_offset)
+    __deprecated
     IO.splice(src, src_offset, dst, nil, len, F_MOVE | WAITALL)
   end
 
   # splice up to +len+ bytes from +src+ to +dst+.
   # Either +dst+ or +src+ must be a pipe.  +dst+ and +src+