Class: Qpid::Proton::Link

Inherits:
Endpoint show all
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

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

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods inherited from Endpoint

#check_state, #handler, #handler=, #local_active?, #local_closed?, #local_uninit?, #remote_active?, #remote_closed?, #remote_uninit?, #transport

Instance Attribute Details

#availableFixnum (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:

  • (Fixnum)

    The available deliveries hint.

See Also:



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

proton_caller :available

#creditFixnum (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:

  • (Fixnum)

    The credit balance.

See Also:

  • #flow


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

proton_caller :credit

#nameString (readonly)

Returns the name of the link.

Returns:

  • (String)

    The name.



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

proton_caller :name

#queuedFixnum (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:

  • (Fixnum)

    The number of queued deliveries.

See Also:



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

proton_caller :queued

#receiver?Boolean (readonly)

Returns if the link is a receiver.

Returns:

  • (Boolean)

    True if the link is a receiver.



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

proton_reader  :receiver, :is_or_get => :is

#remote_creditFixnum (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:

  • (Fixnum)

    The remove view of the credit.

See Also:



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

proton_caller :remote_credit

#sender?Boolean (readonly)

Returns if the link is a sender.

Returns:

  • (Boolean)

    True if the link is a sender.



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

proton_reader  :sender, :is_or_get => :is

#stateObject (readonly)

Returns the endpoint state flags.



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

proton_caller :state

Instance Method Details

#==(other) ⇒ Object



380
381
382
383
# File 'lib/core/link.rb', line 380

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

#advanceBoolean

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:



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

proton_caller :advance

#closeObject

Closes the link.

Once this operation has completed, the state flag will be set. This may be called without first calling #open, which is the equivalent to calling #open and then #close.



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

proton_caller :close

#connectionConnection

Returns the parent connection.

Returns:



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

def connection
  self.session.connection
end

#currentDelivery

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:



325
326
327
# File 'lib/core/link.rb', line 325

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

#delivery(tag) ⇒ Delivery

Returns the parent delivery.

Returns:



305
306
307
# File 'lib/core/link.rb', line 305

def delivery(tag)
  Delivery.new(Cproton.pn_delivery(@impl, tag))
end

#detachObject

Detaches the link.



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

proton_caller :detach

#drainedFixnum

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:

  • (Fixnum)

    The number of credits drained.



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

proton_caller :drained

#errorError

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:



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

def error
  Cproton.pn_link_error(@impl)
end

#next(state_mask) ⇒ Sender, Receiver

Returns the next link that matches the given state mask.

Parameters:

  • state_mask (Fixnum)

    The state mask.

Returns:



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

def next(state_mask)
  return Link.wrap(Cproton.pn_link_next(@impl, state_mask))
end

#openObject

Opens the link. Once this operation has completed, the state flag will be set.



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

proton_caller :open

#rcv_settle_modeFixnum

Returns the local receiver settle mode.

Returns:

  • (Fixnum)

    The local receiver settle mode.



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

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 (Fixnum)

    The settle mode.

See Also:

  • #RCV_FIRST
  • #RCV_SECOND


358
359
360
# File 'lib/core/link.rb', line 358

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

#remote_sourceTerminus

Returns a representation of the remotely defined source terminus.

Returns:



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

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

#remote_targetTerminus

Returns a representation of the remotely defined target terminus.

Returns:



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

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

#sessionSession

Returns the parent session.

Returns:



289
290
291
# File 'lib/core/link.rb', line 289

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

#snd_settle_modeFixnum

Returns the local sender settle mode.

Returns:

  • (Fixnum)

    The local sender settle mode.

See Also:



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

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 (Fixnum)

    The settle mode.

See Also:

  • #SND_UNSETTLED
  • #SND_SETTLED
  • #SND_MIXED


337
338
339
# File 'lib/core/link.rb', line 337

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

#sourceTerminus

Returns the locally defined source terminus.

Returns:



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

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

#targetTerminus

Returns the locally defined target terminus.

Returns:



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

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