Module: Net::SSH::BufferedIo

Includes:
Loggable
Included in:
Transport::PacketStream
Defined in:
lib/net/ssh/buffered_io.rb

Overview

This module is used to extend sockets and other IO objects, to allow them to be buffered for both read and write. This abstraction makes it quite easy to write a select-based event loop (see Net::SSH::Connection::Session#listen_to).

The general idea is that instead of calling #read directly on an IO that has been extended with this module, you call #fill (to add pending input to the internal read buffer), and then #read_available (to read from that buffer). Likewise, you don’t call #write directly, you call #enqueue to add data to the write buffer, and then #send_pending or #wait_for_pending_sends to actually send the data across the wire.

In this way you can easily use the object as an argument to IO.select, calling #fill when it is available for read, or #send_pending when it is available for write, and then call #enqueue and #read_available during the idle times.

socket = TCPSocket.new(address, port)
socket.extend(Net::SSH::BufferedIo)

ssh.listen_to(socket)

ssh.loop do
  if socket.available > 0
    puts socket.read_available
    socket.enqueue("response\n")
  end
end

Note that this module must be used to extend an instance, and should not be included in a class. If you do want to use it via an include, then you must make sure to invoke the private #initialize_buffered_io method in your class’ #initialize method:

class Foo < IO
  include Net::SSH::BufferedIo

  def initialize
    initialize_buffered_io
    # ...
  end
end

Instance Attribute Summary

Attributes included from Loggable

#logger

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Loggable

#debug, #error, #fatal, #info, #lwarn

Class Method Details

.extended(object) ⇒ Object

Called when the #extend is called on an object, with this module as the argument. It ensures that the modules instance variables are all properly initialized.



55
56
57
58
 
# File 'lib/net/ssh/buffered_io.rb', line 55

def self.extended(object) #:nodoc:
  # need to use __send__ because #send is overridden in Socket
  object.__send__(:initialize_buffered_io)
end

Instance Method Details

#available ⇒ Object

Returns the number of bytes available to be read from the input buffer. (See #read_available.)



79
80
81
 
# File 'lib/net/ssh/buffered_io.rb', line 79

def available
  input.available
end

#enqueue(data) ⇒ Object

Enqueues data in the output buffer, to be written when #send_pending is called. Note that the data is not sent immediately by this method!



85
86
87
 
# File 'lib/net/ssh/buffered_io.rb', line 85

def enqueue(data)
  output.append(data)
end

#fill(n = 8192) ⇒ Object

Tries to read up to n bytes of data from the remote end, and appends the data to the input buffer. It returns the number of bytes read, or 0 if no data was available to be read.



63
64
65
66
67
68
69
 
# File 'lib/net/ssh/buffered_io.rb', line 63

def fill(n=8192)
  input.consume!
  data = recv(n)
  debug { "read #{data.length} bytes" }
  input.append(data)
  return data.length
end

#pending_write? ⇒ Boolean

Returns true if there is data waiting in the output buffer, and false otherwise.

Returns:

  • (Boolean) 


91
92
93
 
# File 'lib/net/ssh/buffered_io.rb', line 91

def pending_write?
  output.length > 0
end

#read_available(length = nil) ⇒ Object

Read up to length bytes from the input buffer. If length is nil, all available data is read from the buffer. (See #available.)



73
74
75
 
# File 'lib/net/ssh/buffered_io.rb', line 73

def read_available(length=nil)
  input.read(length || available)
end

#read_buffer ⇒ Object

:nodoc:



125
126
127
 
# File 'lib/net/ssh/buffered_io.rb', line 125

def read_buffer #:nodoc:
  input.to_s
end

#send_pending ⇒ Object

Sends as much of the pending output as possible. Returns true if any data was sent, and false otherwise.



97
98
99
100
101
102
103
104
105
106
 
# File 'lib/net/ssh/buffered_io.rb', line 97

def send_pending
  if output.length > 0
    sent = send(output.to_s, 0)
    debug { "sent #{sent} bytes" }
    output.consume!(sent)
    return sent > 0
  else
    return false
  end
end

#wait_for_pending_sends ⇒ Object

Calls #send_pending repeatedly, if necessary, blocking until the output buffer is empty.



110
111
112
113
114
115
116
117
 
# File 'lib/net/ssh/buffered_io.rb', line 110

def wait_for_pending_sends
  send_pending
  while output.length > 0
    result = Net::SSH::Compat.io_select(nil, [self]) or next
    next unless result[1].any?
    send_pending
  end
end

#write_buffer ⇒ Object

:nodoc:



121
122
123
 
# File 'lib/net/ssh/buffered_io.rb', line 121

def write_buffer #:nodoc:
  output.to_s
end