Class: Qpid::Proton::Transport

Inherits:
Object
  • Object
show all
Defined in:
lib/core/transport.rb

Overview

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.

Tracing can also be enabled from the command line by defining the similarly named environment variable before starting a Proton application:

Examples:


# 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

# enable tracing from the command line
PN_TRACE_FRM=1 ruby my_proton_app.rb

Constant Summary collapse

TRACE_OFF =

Turn logging off entirely.

Cproton::PN_TRACE_OFF
TRACE_RAW =

Log raw binary data into/out of the transport.

Cproton::PN_TRACE_RAW
TRACE_FRM =

Log frames into/out of the transport.

Cproton::PN_TRACE_FRM
TRACE_DRV =

Log driver related events; i.e., initialization, end of stream, etc.

Cproton::PN_TRACE_DRV

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(mode = nil, impl = Cproton.pn_transport) ⇒ Transport

Creates a new transport instance.

Parameters:

  • mode (Fixnum) (defaults to: nil) —

    The transport mode, either CLIENT or SERVER

  • impl (pn_transport_t) (defaults to: Cproton.pn_transport) —

    Should not be used.

Raises:



226
227
228
229
230
231
232
233
234
 
# 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

Instance Attribute Details

#capacity ⇒ Fixnum (readonly)

If the engine is in an exception state such as encountering an error condition or reaching the end of stream state, a negative value will be returned indicating the condition.

If an error is indicated, further deteails can be obtained from #error.

Calls to #process may alter the value of this value. See #process for more details

transport’s tail pointer.

Returns:

  • (Fixnum) —

    The amount of free space for input following the



141
 
# File 'lib/core/transport.rb', line 141

proton_caller :capacity

#channel_max ⇒ Fixnum

Returns The maximum allowed channel.

Returns:

  • (Fixnum) —

    The maximum allowed channel.



94
 
# File 'lib/core/transport.rb', line 94

proton_accessor :channel_max

#closed? ⇒ Boolean (readonly)

A transport is defined to be closed when both the tail and the head are closed. In other words, when both #capacity < 0 and #pending < 0.

Returns:

  • (Boolean) —

    Returns true if the tranpsort is closed.



187
 
# File 'lib/core/transport.rb', line 187

proton_caller :closed?

#frames_input ⇒ Fixnum (readonly)

Returns The number of frames input by a transport.

Returns:

  • (Fixnum) —

    The number of frames input by a transport.



199
 
# File 'lib/core/transport.rb', line 199

proton_reader :frames_input

#frames_output ⇒ Fixnum (readonly)

Returns The number of frames output by a transport.

Returns:

  • (Fixnum) —

    The number of frames output by a transport.



193
 
# File 'lib/core/transport.rb', line 193

proton_reader :frames_output

#head ⇒ String (readonly)

This referneces queued output data. It reports the bytes of output data.

Calls to #pop may alter this attribute, and any data it references.

Returns:

  • (String) —

    The transport’s head pointer.



151
 
# File 'lib/core/transport.rb', line 151

proton_caller :head

#idle_timeout ⇒ Fixnum

Returns The idle timeout.

Returns:

  • (Fixnum) —

    The idle timeout.



118
 
# File 'lib/core/transport.rb', line 118

proton_accessor :idle_timeout

#max_frame_size ⇒ Fixnum

Returns The maximum frame size.

Returns:

  • (Fixnum) —

    The maximum frame size.



106
 
# File 'lib/core/transport.rb', line 106

proton_accessor :max_frame_size

#pending ⇒ Fixnum (readonly)

If the ending is in an exceptional state, such as encountering an error condition or reachign the end of the stream state, a negative value will be returned indicating the condition.

If an error is indicated, further details can be obtained from #error.

Calls to #pop may alter the value of this pointer as well.

pointer.

Returns:

  • (Fixnum) —

    The number of pending output bytes following the header

Raises:

  • (TransportError) —

    If any error other than an end of stream occurs.



178
 
# File 'lib/core/transport.rb', line 178

proton_caller :pending

#remote_channel_max ⇒ Fixnum (readonly)

Returns The maximum allowed channel of a transport’s remote peer.

Returns:

  • (Fixnum) —

    The maximum allowed channel of a transport’s remote peer.



100
 
# File 'lib/core/transport.rb', line 100

proton_caller :remote_channel_max

#remote_idle_timeout ⇒ Fixnum (readonly)

Returns The idle timeout for the transport’s remote peer.

Returns:

  • (Fixnum) —

    The idle timeout for the transport’s remote peer.



124
 
# File 'lib/core/transport.rb', line 124

proton_accessor :remote_idle_timeout

#remote_max_frame_size ⇒ Fixnum (readonly)

Returns The maximum frame size of the transport’s remote peer.

Returns:

  • (Fixnum) —

    The maximum frame size of the transport’s remote peer.



112
 
# File 'lib/core/transport.rb', line 112

proton_reader :remote_max_frame_size

#tail ⇒ String (readonly)

The amount of free space following this data is reported by #capacity.

Calls to #process may alter the value of this attribute.

Returns:

  • (String) —

    The transport’s tail pointer.



161
 
# File 'lib/core/transport.rb', line 161

proton_caller :tail

Instance Method Details

#bind(connection) ⇒ Object

Binds to the given connection.

Parameters:



259
260
261
 
# File 'lib/core/transport.rb', line 259

def bind(connection)
  Cproton.pn_transport_bind(@impl, connection.impl)
end

#close_head ⇒ Object

Indicate that the output has closed.

Tells the transport that no more output will be popped.

Raises:



366
367
368
 
# File 'lib/core/transport.rb', line 366

def close_head
  Cproton.pn_transport_close_head(@impl)
end

#close_tail ⇒ Object

Indicate that the input has reached EOS (end of stream).

This tells the transport that no more input will be forthcoming.

Raises:



332
333
334
 
# File 'lib/core/transport.rb', line 332

def close_tail
  Cproton.pn_transport_close_tail(@impl)
end

#condition ⇒ Object

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.



251
252
253
 
# File 'lib/core/transport.rb', line 251

def condition
  condition_to_object Cproton.pn_transport_condition(@impl)
end

#connection ⇒ Connection?

Return the AMQP connection associated with the transport.

Returns:

  • (Connection, nil) —

    The bound connection, or nil.



286
287
288
 
# File 'lib/core/transport.rb', line 286

def connection
  Connection.wrap(Cproton.pn_transport_connection(@impl))
end

#log(message) ⇒ Object

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.

Parameters:

  • message (String) —

    The message to be logged.



297
298
299
 
# File 'lib/core/transport.rb', line 297

def log(message)
  Cproton.pn_transport_log(@impl, message)
end

#peek(size) ⇒ String

Returns the specified number of bytes from the transport’s buffers.

Parameters:

  • size (Fixnum) —

    The number of bytes to return.

Returns:

  • (String) —

    The data peeked.

Raises:



344
345
346
347
348
349
 
# 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

#pop(size) ⇒ Object

Removes the specified number of bytes from the pending output queue following the transport’s head pointer.

Parameters:

  • size (Fixnum) —

    The number of bytes to remove.



356
357
358
 
# File 'lib/core/transport.rb', line 356

def pop(size)
  Cproton.pn_transport_pop(@impl, size)
end

#process(size) ⇒ Object

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.

Parameters:

  • size (Fixnum) —

    The number of bytes to process.

Raises:



322
323
324
 
# File 'lib/core/transport.rb', line 322

def process(size)
  Cproton.pn_transport_process(@impl, size)
end

#push(data) ⇒ Fixnum

Pushes the supplied bytes into the tail of the transport.

Parameters:

  • data (String) —

    The bytes to be pushed.

Returns:

  • (Fixnum) —

    The number of bytes pushed.



307
308
309
 
# File 'lib/core/transport.rb', line 307

def push(data)
  Cproton.pn_transport_push(@impl, data, data.length)
end

#quiesced? ⇒ Boolean

Returns whether the transport has any buffered data.

Returns:

  • (Boolean) —

    True if the transport has no buffered data.



240
241
242
 
# File 'lib/core/transport.rb', line 240

def quiesced?
  Cproton.pn_transport_quiesced(@impl)
end

#sasl ⇒ Object 



389
390
391
 
# File 'lib/core/transport.rb', line 389

def sasl
  SASL.new(self)
end

#ssl(domain = nil, session_details = nil) ⇒ SSL

Creates, or returns an existing, SSL object for the transport.

Parameters:

  • domain (SSLDomain) (defaults to: nil) —

    The SSL domain.

  • session_details (SSLDetails) (defaults to: nil) —

    The SSL session details.

Returns:

  • (SSL) —

    The SSL object.



400
401
402
 
# 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

#tick(now) ⇒ Fixnum

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.

Parameters:

  • now (Time) —

    The timestamp.

Returns:

  • (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.



385
386
387
 
# File 'lib/core/transport.rb', line 385

def tick(now)
  Cproton.pn_transport_tick(@impl, now)
end

#trace(level) ⇒ Object

Updates the transports trace flags.

Parameters:

  • level (Fixnum) —

    The trace level.

See Also:



278
279
280
 
# File 'lib/core/transport.rb', line 278

def trace(level)
  Cproton.pn_transport_trace(@impl, level)
end

#unbind ⇒ Object

Unbinds from the previous connection.



265
266
267
 
# File 'lib/core/transport.rb', line 265

def unbind
  Cproton.pn_transport_unbind(@impl)
end