You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by mc...@apache.org on 2015/05/18 17:34:44 UTC
[24/42] qpid-proton git commit: PROTON-799: Added the Transport class
to the Ruby engine APIs.
PROTON-799: Added the Transport class to the Ruby engine APIs.
Project: http://git-wip-us.apache.org/repos/asf/qpid-proton/repo
Commit: http://git-wip-us.apache.org/repos/asf/qpid-proton/commit/8e968fa9
Tree: http://git-wip-us.apache.org/repos/asf/qpid-proton/tree/8e968fa9
Diff: http://git-wip-us.apache.org/repos/asf/qpid-proton/diff/8e968fa9
Branch: refs/heads/ruby-engine-apis
Commit: 8e968fa9dc4b8e8986d65649ebf7ff9d188ff679
Parents: a3db56d
Author: Darryl L. Pierce <mc...@gmail.com>
Authored: Wed Jan 14 09:31:46 2015 -0500
Committer: Darryl L. Pierce <mc...@gmail.com>
Committed: Mon May 18 11:33:31 2015 -0400
----------------------------------------------------------------------
proton-c/bindings/ruby/lib/core/exceptions.rb | 5 +
proton-c/bindings/ruby/lib/core/transport.rb | 412 +++++++++++++++++++++
proton-c/bindings/ruby/lib/qpid_proton.rb | 1 +
proton-c/bindings/ruby/ruby.i | 14 +
4 files changed, 432 insertions(+)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/8e968fa9/proton-c/bindings/ruby/lib/core/exceptions.rb
----------------------------------------------------------------------
diff --git a/proton-c/bindings/ruby/lib/core/exceptions.rb b/proton-c/bindings/ruby/lib/core/exceptions.rb
index 2695709..94d2957 100644
--- a/proton-c/bindings/ruby/lib/core/exceptions.rb
+++ b/proton-c/bindings/ruby/lib/core/exceptions.rb
@@ -80,6 +80,11 @@ module Qpid
class InProgressError < ProtonError
end
+ # Raised by instances of Transport.
+ #
+ class TransportError < ProtonError
+ end
+
# Raised by instances of SASL
#
class SASLError < TransportError
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/8e968fa9/proton-c/bindings/ruby/lib/core/transport.rb
----------------------------------------------------------------------
diff --git a/proton-c/bindings/ruby/lib/core/transport.rb b/proton-c/bindings/ruby/lib/core/transport.rb
new file mode 100644
index 0000000..206f97d
--- /dev/null
+++ b/proton-c/bindings/ruby/lib/core/transport.rb
@@ -0,0 +1,412 @@
+#--
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+#++
+
+module Qpid::Proton
+
+ # 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
+ #
+ class Transport
+
+ # @private
+ include Util::Engine
+
+ # Turn logging off entirely.
+ TRACE_OFF = Cproton::PN_TRACE_OFF
+ # Log raw binary data into/out of the transport.
+ TRACE_RAW = Cproton::PN_TRACE_RAW
+ # Log frames into/out of the transport.
+ TRACE_FRM = Cproton::PN_TRACE_FRM
+ # Log driver related events; i.e., initialization, end of stream, etc.
+ TRACE_DRV = Cproton::PN_TRACE_DRV
+
+ # @private
+ CLIENT = 1
+ # @private
+ SERVER = 2
+
+ # @private
+ include Util::SwigHelper
+
+ # @private
+ PROTON_METHOD_PREFIX = "pn_transport"
+
+ # @!attribute channel_max
+ #
+ # @return [Fixnum] The maximum allowed channel.
+ #
+ proton_accessor :channel_max
+
+ # @!attribute [r] remote_channel_max
+ #
+ # @return [Fixnum] The maximum allowed channel of a transport's remote peer.
+ #
+ proton_caller :remote_channel_max
+
+ # @!attribute max_frame_size
+ #
+ # @return [Fixnum] The maximum frame size.
+ #
+ proton_accessor :max_frame_size
+
+ # @!attribute [r] remote_max_frame_size
+ #
+ # @return [Fixnum] The maximum frame size of the transport's remote peer.
+ #
+ proton_reader :remote_max_frame_size
+
+ # @!attribute idle_timeout
+ #
+ # @return [Fixnum] The idle timeout.
+ #
+ proton_accessor :idle_timeout
+
+ # @!attribute [r] remote_idle_timeout
+ #
+ # @return [Fixnum] The idle timeout for the transport's remote peer.
+ #
+ proton_accessor :remote_idle_timeout
+
+ # @!attribute [r] capacity
+ #
+ # 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
+ #
+ # @return [Fixnum] The amount of free space for input following the
+ # transport's tail pointer.
+ #
+ proton_caller :capacity
+
+ # @!attribute [r] head
+ #
+ # This referneces queued output data. It reports the bytes of output data.
+ #
+ # Calls to #pop may alter this attribute, and any data it references.
+ #
+ # @return [String] The transport's head pointer.
+ #
+ proton_caller :head
+
+ # @!attribute [r] tail
+ #
+ # The amount of free space following this data is reported by #capacity.
+ #
+ # Calls to #process may alter the value of this attribute.
+ #
+ # @return [String] The transport's tail pointer.
+ #
+ proton_caller :tail
+
+ # @!attribute [r] pending
+ #
+ # 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.
+ #
+ # @return [Fixnum] The number of pending output bytes following the header
+ # pointer.
+ #
+ # @raise [TransportError] If any error other than an end of stream occurs.
+ #
+ proton_caller :pending
+
+ # @!attribute [r] closed?
+ #
+ # 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.
+ #
+ # @return [Boolean] Returns true if the tranpsort is closed.
+ #
+ proton_caller :closed?
+
+ # @!attribute [r] frames_output
+ #
+ # @return [Fixnum] The number of frames output by a transport.
+ #
+ proton_reader :frames_output
+
+ # @!attribute [r] frames_input
+ #
+ # @return [Fixnum] The number of frames input by a transport.
+ #
+ proton_reader :frames_input
+
+ # @private
+ include Util::ErrorHandler
+
+ can_raise_error :process, :error_class => TransportError
+ can_raise_error :close_tail, :error_class => TransportError
+ can_raise_error :pending, :error_class => TransportError, :below => Error::EOS
+ can_raise_error :close_head, :error_class => TransportError
+
+ # @private
+ include Util::Wrapper
+
+ # @private
+ def self.wrap(impl)
+ return nil if impl.nil?
+
+ self.fetch_instance(impl, :pn_transport_attachments) || Transport.new(nil, impl)
+ end
+
+ # 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.
+ #
+ 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
+
+ # Returns whether the transport has any buffered data.
+ #
+ # @return [Boolean] True if the transport has no buffered data.
+ #
+ def quiesced?
+ Cproton.pn_transport_quiesced(@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.
+ #
+ def condition
+ condition_to_object Cproton.pn_transport_condition(@impl)
+ end
+
+ # Binds to the given connection.
+ #
+ # @param connection [Connection] The connection.
+ #
+ def bind(connection)
+ Cproton.pn_transport_bind(@impl, connection.impl)
+ end
+
+ # Unbinds from the previous connection.
+ #
+ def unbind
+ Cproton.pn_transport_unbind(@impl)
+ end
+
+ # Updates the transports trace flags.
+ #
+ # @param level [Fixnum] The trace level.
+ #
+ # @see TRACE_OFF
+ # @see TRACE_RAW
+ # @see TRACE_FRM
+ # @see TRACE_DRV
+ #
+ def trace(level)
+ Cproton.pn_transport_trace(@impl, level)
+ end
+
+ # Return the AMQP connection associated with the transport.
+ #
+ # @return [Connection, nil] The bound connection, or nil.
+ #
+ 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.
+ #
+ def log(message)
+ Cproton.pn_transport_log(@impl, message)
+ 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.
+ #
+ def push(data)
+ Cproton.pn_transport_push(@impl, data, data.length)
+ 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.
+ #
+ def process(size)
+ Cproton.pn_transport_process(@impl, size)
+ 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.
+ #
+ def close_tail
+ Cproton.pn_transport_close_tail(@impl)
+ 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.
+ #
+ 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.
+ #
+ def pop(size)
+ Cproton.pn_transport_pop(@impl, size)
+ end
+
+ # Indicate that the output has closed.
+ #
+ # Tells the transport that no more output will be popped.
+ #
+ # @raise [TransportError] If an error occurs.
+ #
+ def close_head
+ Cproton.pn_transport_close_head(@impl)
+ 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.
+ #
+ def tick(now)
+ Cproton.pn_transport_tick(@impl, now)
+ end
+
+ 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.
+ #
+ def ssl(domain = nil, session_details = nil)
+ self.ssl = SSL.create(self, domain, session_details) if self.ssl.nil?
+ self.ssl
+ end
+
+ # @private
+ def ssl?
+ self.respond_to?(:ssl) && !self.ssl.nil?
+ end
+
+ end
+
+end
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/8e968fa9/proton-c/bindings/ruby/lib/qpid_proton.rb
----------------------------------------------------------------------
diff --git a/proton-c/bindings/ruby/lib/qpid_proton.rb b/proton-c/bindings/ruby/lib/qpid_proton.rb
index 244e318..16394f9 100644
--- a/proton-c/bindings/ruby/lib/qpid_proton.rb
+++ b/proton-c/bindings/ruby/lib/qpid_proton.rb
@@ -67,6 +67,7 @@ require "core/sasl"
require "core/ssl_domain"
require "core/ssl_details"
require "core/ssl"
+require "core/transport"
# Messenger API classes
require "messenger/filters"
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/8e968fa9/proton-c/bindings/ruby/ruby.i
----------------------------------------------------------------------
diff --git a/proton-c/bindings/ruby/ruby.i b/proton-c/bindings/ruby/ruby.i
index 59d37e9..8e4b6a7 100644
--- a/proton-c/bindings/ruby/ruby.i
+++ b/proton-c/bindings/ruby/ruby.i
@@ -273,6 +273,20 @@ ssize_t pn_transport_input(pn_transport_t *transport, char *STRING, size_t LENGT
%}
%ignore pn_transport_output;
+%rename(pn_transport_peek) wrap_pn_transport_peek;
+%inline %{
+ ssize_t wrap_pn_transport_peek(pn_transport_t *transport, char *OUTPUT, size_t *OUTPUT_SIZE) {
+ ssize_t sz = pn_transport_peek(transport, OUTPUT, *OUTPUT_SIZE);
+ if (sz >= 0) {
+ *OUTPUT_SIZE = sz;
+ } else {
+ *OUTPUT_SIZE = 0;
+ }
+ return sz;
+ }
+ %}
+%ignore pn_transport_peek;
+
%rename(pn_delivery) wrap_pn_delivery;
%inline %{
pn_delivery_t *wrap_pn_delivery(pn_link_t *link, char *STRING, size_t LENGTH) {
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org