class Qpid::Proton::Transport
A transport is used by a connection to interface with the network.
A transport is associated with, at most, one Connection.
Client And Server Mode¶ ↑
Initially, a transport is configured to be a client tranpsort. It can be configured to act as a server when it is created.
A client transport initiates outgoing connections.
A client transport must be configured with the protocol layers to use and cannot configure itself automatically.
A server transport accepts incoming connections. It can automatically configure itself to include the various protocol layers depending on the incoming protocol headers.
Tracing Data¶ ↑
Data can be traced into and out of the transport programmatically by setting the trace level to one of the defined trace values (TRACE_RAW, TRACE_FRM or TRACE_DRV). Tracing can also be turned off programmatically by setting the trace level to TRACE_OFF.
@example
# turns on frame tracing @transport.trace = Qpid::Proton::Transport::TRACE_FRM # ... do something where the frames are of interest, such as debugging # turn tracing off again @transport.trace = Qpid::Proton::Transport::TRACE_NONE
Tracing can also be enabled from the command line by defining the similarly named environment variable before starting a Proton application:
@example
# enable tracing from the command line PN_TRACE_FRM=1 ruby my_proton_app.rb
Constants
- CLIENT
@private
- PROTON_METHOD_PREFIX
@private
- SERVER
@private
- TRACE_DRV
Log driver related events; i.e., initialization, end of stream, etc.
- TRACE_FRM
Log frames into/out of the transport.
- TRACE_OFF
Turn logging off entirely.
- TRACE_RAW
Log raw binary data into/out of the transport.
Public Class Methods
Creates a new transport instance.
@param mode [Fixnum] The transport mode, either CLIENT or SERVER @param impl [pn_transport_t] Should not be used.
@raise [TransportError] If the mode is invalid.
# File lib/core/transport.rb, line 226 def initialize(mode = nil, impl = Cproton.pn_transport) @impl = impl if mode == SERVER Cproton.pn_transport_set_server(@impl) elsif (!mode.nil? && mode != CLIENT) raise TransportError.new("cannot create transport for mode: #{mode}") end self.class.store_instance(self, :pn_transport_attachments) end
@private
# File lib/core/transport.rb, line 213 def self.wrap(impl) return nil if impl.nil? self.fetch_instance(impl, :pn_transport_attachments) || Transport.new(nil, impl) end
Public Instance Methods
Binds to the given connection.
@param connection [Connection] The connection.
# File lib/core/transport.rb, line 259 def bind(connection) Cproton.pn_transport_bind(@impl, connection.impl) end
Indicate that the output has closed.
Tells the transport that no more output will be popped.
@raise [TransportError] If an error occurs.
# File lib/core/transport.rb, line 366 def close_head Cproton.pn_transport_close_head(@impl) end
Indicate that the input has reached EOS (end of stream).
This tells the transport that no more input will be forthcoming.
@raise [TransportError] If an error occurs.
# File lib/core/transport.rb, line 332 def close_tail Cproton.pn_transport_close_tail(@impl) end
Returns additional information about the condition of the transport.
When a TRANSPORT_ERROR event occurs, this operaiton can be used to access the details of the error condition.
The object returned is valid until the Transport is discarded.
# File lib/core/transport.rb, line 251 def condition condition_to_object Cproton.pn_transport_condition(@impl) end
Return the AMQP connection associated with the transport.
@return [Connection, nil] The bound connection, or nil.
# File lib/core/transport.rb, line 286 def connection Connection.wrap(Cproton.pn_transport_connection(@impl)) end
Log a message to the transport's logging mechanism.
This can be using in a debugging scenario as the message will be prepended with the transport's identifier.
@param message [String] The message to be logged.
# File lib/core/transport.rb, line 297 def log(message) Cproton.pn_transport_log(@impl, message) end
Returns the specified number of bytes from the transport's buffers.
@param size [Fixnum] The number of bytes to return.
@return [String] The data peeked.
@raise [TransportError] If an error occurs.
# File lib/core/transport.rb, line 344 def peek(size) cd, out = Cproton.pn_transport_peek(@impl, size) return nil if cd == Qpid::Proton::Error::EOS raise TransportError.new if cd < -1 out end
Removes the specified number of bytes from the pending output queue following the transport's head pointer.
@param size [Fixnum] The number of bytes to remove.
# File lib/core/transport.rb, line 356 def pop(size) Cproton.pn_transport_pop(@impl, size) end
Process input data following the tail pointer.
Calling this function will cause the transport to consume the specified number of bytes of input occupying the free space following the tail pointer. It may also change the value for tail, as well as the amount of free space reported by capacity.
@param size [Fixnum] The number of bytes to process.
@raise [TransportError] If an error occurs.
# File lib/core/transport.rb, line 322 def process(size) Cproton.pn_transport_process(@impl, size) end
Pushes the supplied bytes into the tail of the transport.
@param data [String] The bytes to be pushed.
@return [Fixnum] The number of bytes pushed.
# File lib/core/transport.rb, line 307 def push(data) Cproton.pn_transport_push(@impl, data, data.length) end
Returns whether the transport has any buffered data.
@return [Boolean] True if the transport has no buffered data.
# File lib/core/transport.rb, line 240 def quiesced? Cproton.pn_transport_quiesced(@impl) end
# File lib/core/transport.rb, line 389 def sasl SASL.new(self) end
Creates, or returns an existing, SSL object for the transport.
@param domain [SSLDomain] The SSL domain. @param session_details [SSLDetails] The SSL session details.
@return [SSL] The SSL object.
# File lib/core/transport.rb, line 400 def ssl(domain = nil, session_details = nil) @ssl ||= SSL.create(self, domain, session_details) if @ssl.nil? end
@private
# File lib/core/transport.rb, line 405 def ssl? !@ssl.nil? end
Process any pending transport timer events.
This method should be called after all pending input has been processed by the transport (see input), and before generating output (see output).
It returns the deadline for the next pending timer event, if any art present.
@param now [Time] The timestamp.
@return [Fixnum] If non-zero, the expiration time of the next pending
timer event for the transport. The caller must invoke #tick again at least once at or before this deadline occurs.
# File lib/core/transport.rb, line 385 def tick(now) Cproton.pn_transport_tick(@impl, now) end
Unbinds from the previous connection.
# File lib/core/transport.rb, line 265 def unbind Cproton.pn_transport_unbind(@impl) end