Class: Qpid::Proton::Link

Inherits:
Endpoint show all
Includes:
Util::Wrapper
Defined in:
lib/core/link.rb

Overview

The base for both Sender and Receiver, providing common functionality between both ends.

A Link has a single parent Qpid::Proton::Session instance.

Direct Known Subclasses

Receiver, Sender

Constant Summary collapse

PROTON_METHOD_PREFIX = 
"pn_link"
SND_UNSETTLED =

The sender will send all deliveries initially unsettled.

Cproton::PN_SND_UNSETTLED
SND_SETTLED =

The sender will send all deliveries settled to the receiver.

Cproton::PN_SND_SETTLED
SND_MIXED =

The sender may send a mixture of settled and unsettled deliveries.

Cproton::PN_SND_MIXED
RCV_FIRST =

The receiver will settle deliveries regardless of what the sender does.

Cproton::PN_RCV_FIRST
RCV_SECOND =

The receiver will only settle deliveries after the sender settles.

Cproton::PN_RCV_SECOND

Constants inherited from Endpoint

Endpoint::LOCAL_ACTIVE, Endpoint::LOCAL_CLOSED, Endpoint::LOCAL_MASK, Endpoint::LOCAL_UNINIT, Endpoint::REMOTE_ACTIVE, Endpoint::REMOTE_CLOSED, Endpoint::REMOTE_MASK, Endpoint::REMOTE_UNINIT

Constants included from Util::Deprecation

Util::Deprecation::DEPRECATE_FULL_TRACE, Util::Deprecation::MATCH_DIR

Instance Attribute Summary collapse

Attributes included from Util::Wrapper

#impl

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Util::Wrapper

included, #inspect, registry, #to_s

Methods inherited from Endpoint

#check_state, #closed?, #condition, #local_closed?, #local_condition, #local_open?, #local_uninit?, #open?, #remote_closed?, #remote_condition, #remote_open?, #remote_uninit?, #transport, #work_queue

Methods included from Util::Deprecation

deprecated, #deprecated, included

Constructor Details

#initialize(impl) ⇒ Link

Returns a new instance of Link.



207
208
209
210
 
# File 'lib/core/link.rb', line 207

def initialize(impl)
  @impl = impl
  self.class.store_instance(self, :pn_link_attachments)
end

Instance Attribute Details

#available ⇒ Integer (readonly)

Returns the available deliveries hint for a link.

The available count for a link provides a hint as to the number of deliveries that might be able to be sent if sufficient credit were issued by the receiving link endpoint.

Returns:

  • (Integer) —

    The available deliveries hint.

See Also:



138
 
# File 'lib/core/link.rb', line 138

proton_caller :available

#credit ⇒ Integer (readonly)

Returns the credit balance for a link.

Links use a credit based flow control scheme. Every receiver maintains a credit balance that corresponds to the number of deliveries that the receiver can accept at any given moment.

As more capacity becomes available at the receiver, it adds credit to this balance and communicates the new balance to the sender. Whenever a delivery is sent/received, the credit balance maintained by the link is decremented by one.

Once the credit balance at the sender reaches zero, the sender must pause sending until more credit is obtained from the receiver.

NOte that a sending link may still be used to send deliveries eve if credit reaches zero. However those deliveries will end up being buffer by the link until enough credit is obtained from the receiver to send them over the wire. In this case the balance reported will go negative.

Returns:

  • (Integer) —

    The credit balance.

See Also:

  • #flow


109
 
# File 'lib/core/link.rb', line 109

proton_caller :credit

#name ⇒ String (readonly)

Returns the name of the link.

Returns:

  • (String) —

    The name.



160
 
# File 'lib/core/link.rb', line 160

proton_caller :name

#queued ⇒ Integer (readonly)

Returns the number of queued deliveries for a link.

Links may queue deliveries for a number of reasons. For example, there may be insufficient credit to send them to the receiver, or they simply may not have yet had a chance to be written to the wire.

Returns:

  • (Integer) —

    The number of queued deliveries.

See Also:



152
 
# File 'lib/core/link.rb', line 152

proton_caller :queued

#receiver? ⇒ Boolean (readonly)

Returns if the link is a receiver.

Returns:

  • (Boolean) —

    True if the link is a receiver.



176
 
# File 'lib/core/link.rb', line 176

proton_is  :receiver

#remote_credit ⇒ Integer (readonly)

Returns the remote view of the credit.

The remote view of the credit for a link differs from the local view of credit for a link by the number of queued deliveries. In other words, remote credit is defined as credit - queued.

Returns:

  • (Integer) —

    The remove view of the credit.

See Also:



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

proton_caller :remote_credit

#sender? ⇒ Boolean (readonly)

Returns if the link is a sender.

Returns:

  • (Boolean) —

    True if the link is a sender.



168
 
# File 'lib/core/link.rb', line 168

proton_is  :sender

#state ⇒ Object (readonly)

Returns the endpoint state flags.



49
 
# File 'lib/core/link.rb', line 49

proton_caller :state

Class Method Details

.wrap(impl) ⇒ Object 



200
201
202
203
204
 
# File 'lib/core/link.rb', line 200

def self.wrap(impl)
  return unless impl
  return fetch_instance(impl, :pn_link_attachments) ||
    (Cproton.pn_link_is_sender(impl) ? Sender : Receiver).new(impl)
end

Instance Method Details

#==(other) ⇒ Object 



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

def ==(other)
  other.respond_to?(:impl) &&
  (Cproton.pni_address_of(other.impl) == Cproton.pni_address_of(@impl))
end

#_local_condition ⇒ Object 



346
347
348
 
# File 'lib/core/link.rb', line 346

def _local_condition
  Cproton.pn_link_condition(@impl)
end

#_remote_condition ⇒ Object 



351
352
353
 
# File 'lib/core/link.rb', line 351

def _remote_condition
  Cproton.pn_link_remote_condition(@impl)
end

#advance ⇒ Boolean

Advance the current delivery to the next on the link.

For sending links, this operation is used to finish sending message data for the current outgoing delivery and move on to the next outgoing delivery (if any).

For receiving links, this operatoin is used to finish accessing message data from the current incoming delivery and move on to the next incoming delivery (if any).

Returns:

  • (Boolean) —

    True if the current delivery was changed.

See Also:



80
 
# File 'lib/core/link.rb', line 80

proton_caller :advance

#close(error = nil) ⇒ Object

Close the local end of the link. The remote end may or may not be closed.

Parameters:

  • error (Condition) (defaults to: nil) —

    Optional error condition to send with the close.



56
57
58
59
 
# File 'lib/core/link.rb', line 56

def close(error=nil)
  Condition.assign(_local_condition, error)
  Cproton.pn_link_close(@impl)
end

#connection ⇒ Connection

Returns the parent connection.

Returns:



273
274
275
 
# File 'lib/core/link.rb', line 273

def connection
  self.session.connection
end

#current ⇒ Delivery

Returns the current delivery.

Each link maintains a sequence of deliveries in the order they were created, along with a reference to the current delivery. All send and receive operations on a link take place on the current delivery. If a link has no current delivery, the current delivery is automatically pointed to the next delivery created on the link.

Once initialized, the current delivery remains the same until it is changed by advancing, or until it is settled.

Returns:

See Also:



300
301
302
 
# File 'lib/core/link.rb', line 300

def current
  Delivery.wrap(Cproton.pn_link_current(@impl))
end

#delivery(tag) ⇒ Object

Deprecated.

use Sender#send



279
280
281
282
 
# File 'lib/core/link.rb', line 279

def delivery(tag)
  deprecated __method__, "Sender#send"
  Delivery.new(Cproton.pn_delivery(@impl, tag))
end

#detach ⇒ Object

Detaches the link.



64
 
# File 'lib/core/link.rb', line 64

proton_caller :detach

#drained ⇒ Integer

Drains excess credit.

When a link is in drain mode, the sender must use all excess credit immediately and release any excess credit back to the receiver if there are no deliveries available to send.

When invoked on a Sender that is in drain mode, this operation will release all excess credit back to the receiver and return the number of credits released back to the sender. If the link is not in drain mode, this operation is a noop.

When invoked on a Receiver, this operation will return and reset the number of credits the sender has released back to it.

Returns:

  • (Integer) —

    The number of credits drained.



197
 
# File 'lib/core/link.rb', line 197

proton_caller :drained

#error ⇒ Error

Returns additional error information.

Whenever a link operation fails (i.e., returns an error code) additional error details can be obtained from this method. Ther error object that is returned may also be used to clear the error condition.

Returns:



220
221
222
 
# File 'lib/core/link.rb', line 220

def error
  Cproton.pn_link_error(@impl)
end

#next(state_mask) ⇒ Object

Deprecated.

use Connection#each_link



225
226
227
228
 
# File 'lib/core/link.rb', line 225

def next(state_mask)
  deprecated __method__, "Session#each_link, Connection#each_link"
  return Link.wrap(Cproton.pn_link_next(@impl, state_mask))
end

#rcv_settle_mode ⇒ Integer

Returns the local receiver settle mode.

Returns:

  • (Integer) —

    The local receiver settle mode.



341
342
343
 
# File 'lib/core/link.rb', line 341

def rcv_settle_mode
  Cproton.pn_link_rcv_settle_mode(@impl)
end

#rcv_settle_mode=(mode) ⇒ Object

Sets the local receiver settle mode.

Parameters:

  • mode (Integer) —

    The settle mode.

See Also:

  • #RCV_FIRST
  • #RCV_SECOND


333
334
335
 
# File 'lib/core/link.rb', line 333

def rcv_settle_mode=(mode)
  Cproton.pn_link_set_rcv_settle_mode(@impl, mode)
end

#remote_source ⇒ Terminus

Returns a representation of the remotely defined source terminus.

Returns:



249
250
251
 
# File 'lib/core/link.rb', line 249

def remote_source
  Terminus.new(Cproton.pn_link_remote_source(@impl))
end

#remote_target ⇒ Terminus

Returns a representation of the remotely defined target terminus.

Returns:



257
258
259
 
# File 'lib/core/link.rb', line 257

def remote_target
  Terminus.new(Cproton.pn_link_remote_target(@impl))
end

#session ⇒ Session

Returns the parent session.

Returns:



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

def session
  Session.wrap(Cproton.pn_link_session(@impl))
end

#snd_settle_mode ⇒ Integer

Returns the local sender settle mode.

Returns:

  • (Integer) —

    The local sender settle mode.

See Also:



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

def snd_settle_mode
  Cproton.pn_link_snd_settle_mode(@impl)
end

#snd_settle_mode=(mode) ⇒ Object

Sets the local sender settle mode.

Parameters:

  • mode (Integer) —

    The settle mode.

See Also:

  • #SND_UNSETTLED
  • #SND_SETTLED
  • #SND_MIXED


312
313
314
 
# File 'lib/core/link.rb', line 312

def snd_settle_mode=(mode)
  Cproton.pn_link_set_snd_settle_mode(@impl, mode)
end

#source ⇒ Terminus

Returns the locally defined source terminus.

Returns:



233
234
235
 
# File 'lib/core/link.rb', line 233

def source
  Terminus.new(Cproton.pn_link_source(@impl))
end

#target ⇒ Terminus

Returns the locally defined target terminus.

Returns:



241
242
243
 
# File 'lib/core/link.rb', line 241

def target
  Terminus.new(Cproton.pn_link_target(@impl))
end