io-stream 0.6.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4b66a5f21e372373267bc26a249194d093a07c9af7a53066dcd151662c0abda1
-  data.tar.gz: '0944f1aafb0c79a93462d304e7e4ed722543609a2424f90ee2d045b70bf31751'
+  metadata.gz: 5f73e60fdaf4001c88fcfaa4ccb29bfc8ee90d2fc3ffc81408c8673b414038ae
+  data.tar.gz: 933183cda89e7d555239ba15a752dadccc938628d6197675b3bedb8cfeb60f43
 SHA512:
-  metadata.gz: 75ab72272639271db26f079d7d8098c5a191db8f0321ffc1b82aaffd424511f697da8d3751c4f3bd86c1f2315b52ba02ba5a7ab21f7c6b19c3c39fd649dfe3ae
-  data.tar.gz: e0a17ddca49522facbed0e91b46da1d185aa91c68364258c093c207780f1e7f320debac1f7583762757dfa45d0b79f7206f248911723c93fb8e23a962337ce16
+  metadata.gz: 732318c46b27af3ecabb0c99361b60de5ae3c2733013261ae3089fbaa0f4f2f542e70ee10c410227262a8d137a59d5f1e36ba9419307e801fefd0cfebb412ce5
+  data.tar.gz: 5ae80afa0d558011183648ce9d34c02dc52e2b8f0cf24bde53a319d1cba3dd188fa8705a477baa8c7fcd5afeb6ee487087e72c1a75d39c80566ea9c378d4e7b1

data/lib/io/stream/buffered.rb

@@ -6,7 +6,13 @@
 require_relative "generic"
 
 module IO::Stream
+	# A buffered stream implementation that wraps an underlying IO object to provide efficient buffered reading and writing.
 	class Buffered < Generic
+		# Open a file and wrap it in a buffered stream.
+		# @parameter path [String] The file path to open.
+		# @parameter mode [String] The file mode (e.g., "r+", "w", "a").
+		# @parameter options [Hash] Additional options passed to the stream constructor.
+		# @returns [IO::Stream::Buffered] A buffered stream wrapping the opened file.
 		def self.open(path, mode = "r+", **options)
 			stream = self.new(::File.open(path, mode), **options)
 			
@@ -19,6 +25,10 @@ module IO::Stream
 			end
 		end
 		
+		# Wrap an existing IO object in a buffered stream.
+		# @parameter io [IO] The IO object to wrap.
+		# @parameter options [Hash] Additional options passed to the stream constructor.
+		# @returns [IO::Stream::Buffered] A buffered stream wrapping the IO object.
 		def self.wrap(io, **options)
 			if io.respond_to?(:buffered=)
 				io.buffered = false
@@ -37,6 +47,8 @@ module IO::Stream
 			end
 		end
 		
+		# Initialize a new buffered stream.
+		# @parameter io [IO] The underlying IO object to wrap.
 		def initialize(io, ...)
 			super(...)
 			
@@ -47,27 +59,36 @@ module IO::Stream
 				@timeout = nil
 			end
 		end
-		
+
+		# @attribute [IO] The wrapped IO object.
 		attr :io
-		
+
+		# Get the underlying IO object.
+		# @returns [IO] The underlying IO object.
 		def to_io
 			@io.to_io
 		end
-		
+
+		# Check if the stream is closed.
+		# @returns [Boolean] True if the stream is closed.
 		def closed?
 			@io.closed?
 		end
-		
+
+		# Close the read end of the stream.
 		def close_read
 			@io.close_read
 		end
-		
+
+		# Close the write end of the stream.
 		def close_write
 			super
 		ensure
 			@io.close_write
 		end
-		
+
+		# Check if the stream is readable.
+		# @returns [Boolean] True if the stream is readable.
 		def readable?
 			super && @io.readable?
 		end
@@ -85,23 +106,26 @@ module IO::Stream
 			end
 		end
 		
-		def syswrite(buffer)
-			# This fails due to re-entrancy issues with a concurrent call to `sysclose`.
-			# return @io.write(buffer)
-			
-			while true
-				result = @io.write_nonblock(buffer, exception: false)
-				
-				case result
-				when :wait_readable
-					@io.wait_readable(@io.timeout) or raise ::IO::TimeoutError, "read timeout"
-				when :wait_writable
-					@io.wait_writable(@io.timeout) or raise ::IO::TimeoutError, "write timeout"
-				else
-					if result == buffer.bytesize
-						return
+		if RUBY_VERSION >= "3.3"
+			def syswrite(buffer)
+				return @io.write(buffer)
+			end
+		else
+			def syswrite(buffer)
+				while true
+					result = @io.write_nonblock(buffer, exception: false)
+					
+					case result
+					when :wait_readable
+						@io.wait_readable(@io.timeout) or raise ::IO::TimeoutError, "read timeout"
+					when :wait_writable
+						@io.wait_writable(@io.timeout) or raise ::IO::TimeoutError, "write timeout"
 					else
-						buffer = buffer.byteslice(result, buffer.bytesize)
+						if result == buffer.bytesize
+							return
+						else
+							buffer = buffer.byteslice(result, buffer.bytesize)
+						end
 					end
 				end
 			end

data/lib/io/stream/generic.rb

@@ -4,253 +4,38 @@
 # Copyright, 2023-2024, by Samuel Williams.
 
 require_relative "string_buffer"
+require_relative "readable"
+require_relative "writable"
 
 require_relative "shim/buffered"
 require_relative "shim/readable"
-require_relative "shim/timeout"
 
 require_relative "openssl"
 
 module IO::Stream
-	# The default block size for IO buffers. Defaults to 64KB (typical pipe buffer size).
-	BLOCK_SIZE = ENV.fetch("IO_STREAM_BLOCK_SIZE", 1024*64).to_i
-
-	# The maximum read size when appending to IO buffers. Defaults to 8MB.
-	MAXIMUM_READ_SIZE = ENV.fetch("IO_STREAM_MAXIMUM_READ_SIZE", BLOCK_SIZE * 128).to_i
-	
-	class LimitError < StandardError
-	end
-	
+	# Base class for stream implementations providing common functionality.
 	class Generic
-		def initialize(block_size: BLOCK_SIZE, maximum_read_size: MAXIMUM_READ_SIZE)
-			@eof = false
-			
-			@writing = ::Thread::Mutex.new
-			
-			@block_size = block_size
-			@maximum_read_size = maximum_read_size
-			
-			@read_buffer = StringBuffer.new
-			@write_buffer = StringBuffer.new
-			
-			# Used as destination buffer for underlying reads.
-			@input_buffer = StringBuffer.new
-		end
-		
-		attr_accessor :block_size
-		
-		# Reads `size` bytes from the stream. If size is not specified, read until end of file.
-		def read(size = nil)
-			return String.new(encoding: Encoding::BINARY) if size == 0
-			
-			if size
-				until @eof or @read_buffer.bytesize >= size
-					# Compute the amount of data we need to read from the underlying stream:
-					read_size = size - @read_buffer.bytesize
-					
-					# Don't read less than @block_size to avoid lots of small reads:
-					fill_read_buffer(read_size > @block_size ? read_size : @block_size)
-				end
-			else
-				until @eof
-					fill_read_buffer
-				end
-			end
-			
-			return consume_read_buffer(size)
-		end
-		
-		# Read at most `size` bytes from the stream. Will avoid reading from the underlying stream if possible.
-		def read_partial(size = nil)
-			return String.new(encoding: Encoding::BINARY) if size == 0
-		
-			if !@eof and @read_buffer.empty?
-				fill_read_buffer
-			end
-			
-			return consume_read_buffer(size)
-		end
-		
-		def read_exactly(size, exception: EOFError)
-			if buffer = read(size)
-				if buffer.bytesize != size
-					raise exception, "could not read enough data"
-				end
-				
-				return buffer
-			end
-			
-			raise exception, "encountered eof while reading data"
-		end
-		
-		# This is a compatibility shim for existing code that uses `readpartial`.
-		def readpartial(size = nil)
-			read_partial(size) or raise EOFError, "Encountered eof while reading data!"
-		end
-		
-		private def index_of(pattern, offset, limit)
-			# We don't want to split on the pattern, so we subtract the size of the pattern.
-			split_offset = pattern.bytesize - 1
-
-			until index = @read_buffer.index(pattern, offset)
-				offset = @read_buffer.bytesize - split_offset
-				
-				offset = 0 if offset < 0
-				
-				return nil if limit and offset >= limit
-				return nil unless fill_read_buffer
-			end
-			
-			return index
-		end
-		
-		# Efficiently read data from the stream until encountering pattern.
-		# @parameter pattern [String] The pattern to match.
-		# @parameter offset [Integer] The offset to start searching from.
-		# @parameter limit [Integer] The maximum number of bytes to read, including the pattern (even if chomped).
-		# @returns [String | Nil] The contents of the stream up until the pattern, which is consumed but not returned.
-		def read_until(pattern, offset = 0, limit: nil, chomp: true)
-			if index = index_of(pattern, offset, limit)
-				return nil if limit and index >= limit
-				
-				@read_buffer.freeze
-				matched = @read_buffer.byteslice(0, index+(chomp ? 0 : pattern.bytesize))
-				@read_buffer = @read_buffer.byteslice(index+pattern.bytesize, @read_buffer.bytesize)
-				
-				return matched
-			end
-		end
-		
-		def peek(size = nil)
-			if size
-				until @eof or @read_buffer.bytesize >= size
-					# Compute the amount of data we need to read from the underlying stream:
-					read_size = size - @read_buffer.bytesize
-					
-					# Don't read less than @block_size to avoid lots of small reads:
-					fill_read_buffer(read_size > @block_size ? read_size : @block_size)
-				end
-				return @read_buffer[..([size, @read_buffer.size].min - 1)]
-			end
-			until (block_given? && yield(@read_buffer)) or @eof
-				fill_read_buffer
-			end
-			return @read_buffer
-		end
-		
-		def gets(separator = $/, limit = nil, chomp: false)
-			# Compatibility with IO#gets:
-			if separator.is_a?(Integer)
-				limit = separator
-				separator = $/
-			end
-			
-			# We don't want to split in the middle of the separator, so we subtract the size of the separator from the start of the search:
-			split_offset = separator.bytesize - 1
-			
-			offset = 0
-			
-			until index = @read_buffer.index(separator, offset)
-				offset = @read_buffer.bytesize - split_offset
-				offset = 0 if offset < 0
-				
-				# If a limit was given, and the offset is beyond the limit, we should return up to the limit:
-				if limit and offset >= limit
-					# As we didn't find the separator, there is nothing to chomp either.
-					return consume_read_buffer(limit)
-				end
-				
-				# If we can't read any more data, we should return what we have:
-				return consume_read_buffer unless fill_read_buffer
-			end
-			
-			# If the index of the separator was beyond the limit:
-			if limit and index >= limit
-				# Return up to the limit:
-				return consume_read_buffer(limit)
-			end
-			
-			# Freeze the read buffer, as this enables us to use byteslice without generating a hidden copy:
-			@read_buffer.freeze
-			
-			line = @read_buffer.byteslice(0, index+(chomp ? 0 : separator.bytesize))
-			@read_buffer = @read_buffer.byteslice(index+separator.bytesize, @read_buffer.bytesize)
-			
-			return line
-		end
+		include Readable
+		include Writable
 		
-		private def drain(buffer)
-			begin
-				syswrite(buffer)
-			ensure
-				# If the write operation fails, we still need to clear this buffer, and the data is essentially lost.
-				buffer.clear
-			end
-		end
-		
-		# Flushes buffered data to the stream.
-		def flush
-			return if @write_buffer.empty?
-			
-			@writing.synchronize do
-				self.drain(@write_buffer)
-			end
-		end
-		
-		# Writes `string` to the buffer. When the buffer is full or #sync is true the
-		# buffer is flushed to the underlying `io`.
-		# @parameter string [String] the string to write to the buffer.
-		# @returns [Integer] the number of bytes appended to the buffer.
-		def write(string, flush: false)
-			@writing.synchronize do
-				@write_buffer << string
-				
-				flush |= (@write_buffer.bytesize >= @block_size)
-				
-				if flush
-					self.drain(@write_buffer)
-				end
-			end
-			
-			return string.bytesize
-		end
-		
-		# Writes `string` to the stream and returns self.
-		def <<(string)
-			write(string)
-			
-			return self
-		end
-		
-		def puts(*arguments, separator: $/)
-			return if arguments.empty?
-			
-			@writing.synchronize do
-				arguments.each do |argument|
-					@write_buffer << argument << separator
-				end
-				
-				self.drain(@write_buffer)
-			end
+		# Initialize a new generic stream.
+		# @parameter options [Hash] Options passed to included modules.
+		def initialize(**options)
+			super(**options)
 		end
 		
+		# Check if the stream is closed.
+		# @returns [Boolean] False by default, should be overridden by subclasses.
 		def closed?
 			false
 		end
 		
-		def close_read
-		end
-		
-		def close_write
-			flush
-		end
-		
 		# Best effort to flush any unwritten data, and then close the underling IO.
 		def close
 			return if closed?
 			
 			begin
-				flush
+				self.flush
 			rescue
 				# We really can't do anything here unless we want #close to raise exceptions.
 			ensure
@@ -258,115 +43,26 @@ module IO::Stream
 			end
 		end
 		
-		# Determins if the stream has consumed all available data. May block if the stream is not readable.
-		# See {readable?} for a non-blocking alternative.
-		#
-		# @returns [Boolean] If the stream is at file which means there is no more data to be read.
-		def eof?
-			if !@read_buffer.empty?
-				return false
-			elsif @eof
-				return true
-			else
-				return !self.fill_read_buffer
-			end
-		end
-		
-		def eof!
-			@read_buffer.clear
-			@eof = true
-			
-			raise EOFError
-		end
-		
-		# Whether there is a chance that a read operation will succeed or not.
-		# @returns [Boolean] If the stream is readable, i.e. a `read` operation has a chance of success.
-		def readable?
-			# If we are at the end of the file, we can't read any more data:
-			if @eof
-				return false
-			end
-			
-			# If the read buffer is not empty, we can read more data:
-			if !@read_buffer.empty?
-				return true
-			end
-			
-			# If the underlying stream is readable, we can read more data:
-			return !closed?
-		end
-		
 		protected
 		
+		# Closes the underlying IO stream.
+		# This method should be implemented by subclasses to handle the specific closing logic.
 		def sysclose
 			raise NotImplementedError
 		end
 		
+		# Writes data to the underlying stream.
+		# This method should be implemented by subclasses to handle the specific writing logic.
+		# @parameter buffer [String] The data to write.
+		# @returns [Integer] The number of bytes written.
 		def syswrite(buffer)
 			raise NotImplementedError
 		end
 		
 		# Reads data from the underlying stream as efficiently as possible.
+		# This method should be implemented by subclasses to handle the specific reading logic.
 		def sysread(size, buffer)
 			raise NotImplementedError
 		end
-		
-		private
-		
-		# Fills the buffer from the underlying stream.
-		def fill_read_buffer(size = @block_size)
-			# We impose a limit because the underlying `read` system call can fail if we request too much data in one go.
-			if size > @maximum_read_size
-				size = @maximum_read_size
-			end
-			
-			# This effectively ties the input and output stream together.
-			flush
-			
-			if @read_buffer.empty?
-				if sysread(size, @read_buffer)
-					# Console.info(self, name: "read") {@read_buffer.inspect}
-					return true
-				end
-			else
-				if chunk = sysread(size, @input_buffer)
-					@read_buffer << chunk
-					# Console.info(self, name: "read") {@read_buffer.inspect}
-					
-					return true
-				end
-			end
-			
-			# else for both cases above:
-			@eof = true
-			return false
-		end
-		
-		# Consumes at most `size` bytes from the buffer.
-		# @parameter size [Integer|nil] The amount of data to consume. If nil, consume entire buffer.
-		def consume_read_buffer(size = nil)
-			# If we are at eof, and the read buffer is empty, we can't consume anything.
-			return nil if @eof && @read_buffer.empty?
-			
-			result = nil
-			
-			if size.nil? or size >= @read_buffer.bytesize
-				# Consume the entire read buffer:
-				result = @read_buffer
-				@read_buffer = StringBuffer.new
-			else
-				# This approach uses more memory.
-				# result = @read_buffer.slice!(0, size)
-				
-				# We know that we are not going to reuse the original buffer.
-				# But byteslice will generate a hidden copy. So let's freeze it first:
-				@read_buffer.freeze
-				
-				result = @read_buffer.byteslice(0, size)
-				@read_buffer = @read_buffer.byteslice(size, @read_buffer.bytesize)
-			end
-			
-			return result
-		end
 	end
 end

data/lib/io/stream/openssl.rb

@@ -5,52 +5,67 @@
 
 require "openssl"
 
+# @namespace
 module OpenSSL
+	# @namespace
 	module SSL
+		# SSL socket extensions for stream compatibility.
 		class SSLSocket
 			unless method_defined?(:close_read)
+				# Close the read end of the SSL socket.
 				def close_read
 					# Ignored.
 				end
 			end
 			
 			unless method_defined?(:close_write)
+				# Close the write end of the SSL socket.
 				def close_write
 					self.stop
 				end
 			end
 			
 			unless method_defined?(:wait_readable)
+				# Wait for the SSL socket to become readable.
 				def wait_readable(...)
 					to_io.wait_readable(...)
 				end
 			end
 			
 			unless method_defined?(:wait_writable)
+				# Wait for the SSL socket to become writable.
 				def wait_writable(...)
 					to_io.wait_writable(...)
 				end
 			end
 			
 			unless method_defined?(:timeout)
+				# Get the timeout for SSL socket operations.
+				# @returns [Numeric | Nil] The timeout value.
 				def timeout
 					to_io.timeout
 				end
 			end
 			
 			unless method_defined?(:timeout=)
+				# Set the timeout for SSL socket operations.
+				# @parameter value [Numeric | Nil] The timeout value.
 				def timeout=(value)
 					to_io.timeout = value
 				end
 			end
 			
 			unless method_defined?(:buffered?)
+				# Check if the SSL socket is buffered.
+				# @returns [Boolean] True if the SSL socket is buffered.
 				def buffered?
 					return to_io.buffered?
 				end
 			end
 			
 			unless method_defined?(:buffered=)
+				# Set the buffered state of the SSL socket.
+				# @parameter value [Boolean] True to enable buffering, false to disable.
 				def buffered=(value)
 					to_io.buffered = value
 				end