[PATCH 1/2] io/splice: deprecated potentially unsafe methods

[Eric Wong <normalperson@yhbt.net>]

In retrospect, these methods are too infrequently useful and
causes problems too easily to be worth supporting.
---
 lib/io/splice.rb | 24 +++++++++++++++++++++---
 1 file changed, 21 insertions(+), 3 deletions(-)

diff --git a/lib/io/splice.rb b/lib/io/splice.rb
index 65d8ed4..9b17aa3 100644
--- a/lib/io/splice.rb
+++ b/lib/io/splice.rb
@@ -3,6 +3,14 @@
 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
@@ -36,10 +44,19 @@ def self.need_open?(obj) # :nodoc:
   # 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"))
@@ -90,6 +107,7 @@ def self.copy_stream(src, dst, len = nil, src_offset = nil)
   #
   # 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
 
-- 
1.8.2.1.367.gc875ca7