Class: Bunny::Channel

Inherits:
Object
  • Object
show all
Defined in:
lib/bunny/channel.rb

Overview

Channels in RabbitMQ

To quote AMQP 0.9.1 specification:

AMQP 0.9.1 is a multi-channelled protocol. Channels provide a way to multiplex a heavyweight TCP/IP connection into several light weight connections. This makes the protocol more “firewall friendly” since port usage is predictable. It also means that traffic shaping and other network QoS features can be easily employed. Channels are independent of each other and can perform different functions simultaneously with other channels, the available bandwidth being shared between the concurrent activities.

Opening Channels

Channels can be opened either via Bunny::Session#create_channel (sufficient in the majority of cases) or by instantiating Bunny::Channel directly:

This will automatically allocate a channel id.

Closing Channels

Channels are closed via #close. Channels that get a channel-level exception are closed, too. Closed channels can no longer be used. Attempts to use them will raise ChannelAlreadyClosed.

Higher-level API

Bunny offers two sets of methods on Channel: known as higher-level and lower-level APIs, respectively. Higher-level API mimics amqp gem API where exchanges and queues are objects (instance of Exchange and Queue, respectively). Lower-level API is built around AMQP 0.9.1 methods (commands), where queues and exchanges are passed as strings (à la RabbitMQ Java client, Langohr and Pika).

Queue Operations In Higher-level API

  • #queue is used to declare queues. The rest of the API is in Queue.

Exchange Operations In Higher-level API

Channel Qos (Prefetch Level)

It is possible to control how many messages at most a consumer will be given (before it acknowledges or rejects previously consumed ones). This setting is per channel and controlled via #prefetch.

Channel IDs

Channels are identified by their ids which are integers. Bunny takes care of allocating and releasing them as channels are opened and closed. It is almost never necessary to specify channel ids explicitly.

There is a limit on the maximum number of channels per connection, usually 65536. Note that allocating channels is very cheap on both client and server so having tens, hundreds or even thousands of channels is not a problem.

Channels and Error Handling

Channel-level exceptions are more common than connection-level ones and often indicate issues applications can recover from (such as consuming from or trying to delete a queue that does not exist).

With Bunny, channel-level exceptions are raised as Ruby exceptions, for example, NotFound, that provide access to the underlying channel.close method information.

Examples:

conn = Bunny.new
conn.start

ch   = conn.create_channel

ch  = conn.create_channel
ch.close

Handling 404 NOT_FOUND

begin
  ch.queue_delete("queue_that_should_not_exist#{rand}")
rescue Bunny::NotFound => e
  puts "Channel-level exception! Code: #{e.channel_close.reply_code}, message: #{e.channel_close.reply_text}"
end

Handling 406 PRECONDITION_FAILED

begin
  ch2 = conn.create_channel
  q   = "bunny.examples.recovery.q#{rand}"

  ch2.queue_declare(q, :durable => false)
  ch2.queue_declare(q, :durable => true)
rescue Bunny::PreconditionFailed => e
  puts "Channel-level exception! Code: #{e.channel_close.reply_code}, message: #{e.channel_close.reply_text}"
ensure
  conn.create_channel.queue_delete(q)
end

See Also:

Constant Summary

DEFAULT_CONTENT_TYPE =
"application/octet-stream".freeze
SHORTSTR_LIMIT =
255

Instance Attribute Summary (collapse)

Backwards compatibility with 0.8.0 (collapse)

Higher-level API for exchange operations (collapse)

Higher-level API for queue operations (collapse)

QoS and Flow Control (collapse)

Message acknowledgements (collapse)

Consumer and Message operations (basic.*) (collapse)

Queue operations (queue.*) (collapse)

Exchange operations (exchange.*) (collapse)

Flow control (channel.*) (collapse)

Transactions (tx.*) (collapse)

Publisher Confirms (confirm.*) (collapse)

Misc (collapse)

Network Failure Recovery (collapse)

Instance Method Summary (collapse)

Constructor Details

- (Channel) initialize(connection = nil, id = nil, work_pool = ConsumerWorkPool.new(1))



169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
# File 'lib/bunny/channel.rb', line 169

def initialize(connection = nil, id = nil, work_pool = ConsumerWorkPool.new(1))
  @connection = connection
  @logger     = connection.logger
  @id         = id || @connection.next_channel_id
  @status     = :opening

  @connection.register_channel(self)

  @queues     = Hash.new
  @exchanges  = Hash.new
  @consumers  = Hash.new
  @work_pool  = work_pool

  # synchronizes frameset delivery. MK.
  @publishing_mutex = @connection.mutex_impl.new
  @consumer_mutex   = @connection.mutex_impl.new

  @unconfirmed_set_mutex = @connection.mutex_impl.new

  self.reset_continuations

  # threads awaiting on continuations. Used to unblock
  # them when network connection goes down so that busy loops
  # that perform synchronous operations can work. MK.
  @threads_waiting_on_continuations           = Set.new
  @threads_waiting_on_confirms_continuations  = Set.new
  @threads_waiting_on_basic_get_continuations = Set.new

  @next_publish_seq_no = 0
  @delivery_tag_offset = 0

  @recoveries_counter = Bunny::Concurrent::AtomicFixnum.new(0)
  @uncaught_exception_handler = Proc.new do |e, consumer|
    @logger.error "Uncaught exception from consumer #{consumer.to_s}: #{e.message}"
  end
end

Instance Attribute Details

- (Bunny::Session) connection (readonly)



142
143
144
# File 'lib/bunny/channel.rb', line 142

def connection
  @connection
end

- (Hash<String, Bunny::Consumer>) consumers (readonly)



158
159
160
# File 'lib/bunny/channel.rb', line 158

def consumers
  @consumers
end

- (Hash<String, Bunny::Exchange>) exchanges (readonly)



152
153
154
# File 'lib/bunny/channel.rb', line 152

def exchanges
  @exchanges
end

- (Integer) id



140
141
142
# File 'lib/bunny/channel.rb', line 140

def id
  @id
end

- (Set<Integer>) nacked_set (readonly)



156
157
158
# File 'lib/bunny/channel.rb', line 156

def nacked_set
  @nacked_set
end

- (Integer) next_publish_seq_no (readonly)



148
149
150
# File 'lib/bunny/channel.rb', line 148

def next_publish_seq_no
  @next_publish_seq_no
end

- (Integer) prefetch_count (readonly)



161
162
163
# File 'lib/bunny/channel.rb', line 161

def prefetch_count
  @prefetch_count
end

- (Hash<String, Bunny::Queue>) queues (readonly)



150
151
152
# File 'lib/bunny/channel.rb', line 150

def queues
  @queues
end

- (Object) recoveries_counter (readonly)

Returns the value of attribute recoveries_counter



206
207
208
# File 'lib/bunny/channel.rb', line 206

def recoveries_counter
  @recoveries_counter
end

- (Symbol) status (readonly)



144
145
146
# File 'lib/bunny/channel.rb', line 144

def status
  @status
end

- (Set<Integer>) unconfirmed_set (readonly)



154
155
156
# File 'lib/bunny/channel.rb', line 154

def unconfirmed_set
  @unconfirmed_set
end

- (Bunny::ConsumerWorkPool) work_pool (readonly)



146
147
148
# File 'lib/bunny/channel.rb', line 146

def work_pool
  @work_pool
end

Instance Method Details

- (Object) ack(delivery_tag, multiple = false) Also known as: acknowledge

Acknowledges a message. Acknowledged messages are completely removed from the queue.



467
468
469
470
471
# File 'lib/bunny/channel.rb', line 467

def ack(delivery_tag, multiple = false)
  guarding_against_stale_delivery_tags(delivery_tag) do
    basic_ack(delivery_tag.to_i, multiple)
  end
end

- (Boolean) active



262
263
264
# File 'lib/bunny/channel.rb', line 262

def active
  open?
end

- (Boolean) any_consumers?

Returns true if there are consumers on this channel



942
943
944
# File 'lib/bunny/channel.rb', line 942

def any_consumers?
  @consumer_mutex.synchronize { @consumers.any? }
end

- (NilClass) basic_ack(delivery_tag, multiple)

Acknowledges a delivery (message).

Examples:

Ack a message

conn  = Bunny.new
conn.start

ch    = conn.create_channel
q.subscribe do |delivery_info, properties, payload|
  # requeue the message
  ch.basic_ack(delivery_info.delivery_tag)
end

Ack a message fetched via basic.get

conn  = Bunny.new
conn.start

ch    = conn.create_channel
# we assume the queue exists and has messages
delivery_info, properties, payload = ch.basic_get("bunny.examples.queue3", :manual_ack => true)
ch.basic_ack(delivery_info.delivery_tag)

Ack multiple messages fetched via basic.get

conn  = Bunny.new
conn.start

ch    = conn.create_channel
# we assume the queue exists and has messages
_, _, payload1 = ch.basic_get("bunny.examples.queue3", :manual_ack => true)
_, _, payload2 = ch.basic_get("bunny.examples.queue3", :manual_ack => true)
delivery_info, properties, payload3 = ch.basic_get("bunny.examples.queue3", :manual_ack => true)
# ack all fetched messages up to payload3
ch.basic_ack(delivery_info.delivery_tag, true)

See Also:



737
738
739
740
741
742
# File 'lib/bunny/channel.rb', line 737

def basic_ack(delivery_tag, multiple)
  raise_if_no_longer_open!
  @connection.send_frame(AMQ::Protocol::Basic::Ack.encode(@id, delivery_tag, multiple))

  nil
end

- (AMQ::Protocol::Basic::CancelOk) basic_cancel(consumer_tag)

Removes a consumer. Messages for this consumer will no longer be delivered. If the queue it was on is auto-deleted and this consumer was the last one, the queue will be deleted.



928
929
930
931
932
933
934
935
936
937
938
# File 'lib/bunny/channel.rb', line 928

def basic_cancel(consumer_tag)
  @connection.send_frame(AMQ::Protocol::Basic::Cancel.encode(@id, consumer_tag, false))

  Bunny::Timeout.timeout(read_write_timeout, ClientTimeout) do
    @last_basic_cancel_ok = wait_on_continuations
  end

  maybe_kill_consumer_work_pool! unless any_consumers?

  @last_basic_cancel_ok
end

- (AMQ::Protocol::Basic::ConsumeOk) basic_consume(queue, consumer_tag = generate_consumer_tag, no_ack = false, exclusive = false, arguments = nil, &block) Also known as: consume

Registers a consumer for queue. Delivered messages will be handled with the block provided to this method.



820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
# File 'lib/bunny/channel.rb', line 820

def basic_consume(queue, consumer_tag = generate_consumer_tag, no_ack = false, exclusive = false, arguments = nil, &block)
  raise_if_no_longer_open!
  maybe_start_consumer_work_pool!

  queue_name = if queue.respond_to?(:name)
                 queue.name
               else
                 queue
               end

  # helps avoid race condition between basic.consume-ok and basic.deliver if there are messages
  # in the queue already. MK.
  if consumer_tag && consumer_tag.strip != AMQ::Protocol::EMPTY_STRING
    add_consumer(queue_name, consumer_tag, no_ack, exclusive, arguments, &block)
  end

  @connection.send_frame(AMQ::Protocol::Basic::Consume.encode(@id,
      queue_name,
      consumer_tag,
      false,
      no_ack,
      exclusive,
      false,
      arguments))

  begin
    Bunny::Timeout.timeout(read_write_timeout, ClientTimeout) do
      @last_basic_consume_ok = wait_on_continuations
    end
  rescue Exception => e
    # if basic.consume-ok never arrives, unregister the proactively
    # registered consumer. MK.
    unregister_consumer(@last_basic_consume_ok.consumer_tag)

    raise e
  end

  # in case there is another exclusive consumer and we get a channel.close
  # response here. MK.
  raise_if_channel_close!(@last_basic_consume_ok)

  # covers server-generated consumer tags
  add_consumer(queue_name, @last_basic_consume_ok.consumer_tag, no_ack, exclusive, arguments, &block)

  @last_basic_consume_ok
end

- (AMQ::Protocol::Basic::ConsumeOk) basic_consume_with(consumer) Also known as: consume_with

Registers a consumer for queue as Bunny::Consumer instance.



876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
# File 'lib/bunny/channel.rb', line 876

def basic_consume_with(consumer)
  raise_if_no_longer_open!
  maybe_start_consumer_work_pool!

  # helps avoid race condition between basic.consume-ok and basic.deliver if there are messages
  # in the queue already. MK.
  if consumer.consumer_tag && consumer.consumer_tag.strip != AMQ::Protocol::EMPTY_STRING
    register_consumer(consumer.consumer_tag, consumer)
  end

  @connection.send_frame(AMQ::Protocol::Basic::Consume.encode(@id,
      consumer.queue_name,
      consumer.consumer_tag,
      false,
      consumer.no_ack,
      consumer.exclusive,
      false,
      consumer.arguments))

  begin
    Bunny::Timeout.timeout(read_write_timeout, ClientTimeout) do
      @last_basic_consume_ok = wait_on_continuations
    end
  rescue Exception => e
    # if basic.consume-ok never arrives, unregister the proactively
    # registered consumer. MK.
    unregister_consumer(@last_basic_consume_ok.consumer_tag)

    raise e
  end

  # in case there is another exclusive consumer and we get a channel.close
  # response here. MK.
  raise_if_channel_close!(@last_basic_consume_ok)

  # covers server-generated consumer tags
  register_consumer(@last_basic_consume_ok.consumer_tag, consumer)

  raise_if_continuation_resulted_in_a_channel_error!

  @last_basic_consume_ok
end

- (Array) basic_get(queue, opts = {:manual_ack => true})

Synchronously fetches a message from the queue, if there are any. This method is for cases when the convenience of synchronous operations is more important than throughput.

Examples:

Using Bunny::Channel#basic_get with manual acknowledgements

conn = Bunny.new
conn.start
ch   = conn.create_channel
# here we assume the queue already exists and has messages
delivery_info, properties, payload = ch.basic_get("bunny.examples.queue1", :manual_ack => true)
ch.acknowledge(delivery_info.delivery_tag)

Options Hash (opts):

  • :ack (Boolean) — default: true

    [DEPRECATED] Use :manual_ack instead

  • :manual_ack (Boolean) — default: true

    Will this message be acknowledged manually?

See Also:



584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
# File 'lib/bunny/channel.rb', line 584

def basic_get(queue, opts = {:manual_ack => true})
  raise_if_no_longer_open!

  unless opts[:ack].nil?
    warn "[DEPRECATION] `:ack` is deprecated.  Please use `:manual_ack` instead."
    opts[:manual_ack] = opts[:ack]
  end

  @connection.send_frame(AMQ::Protocol::Basic::Get.encode(@id, queue, !(opts[:manual_ack])))
  # this is a workaround for the edge case when basic_get is called in a tight loop
  # and network goes down we need to perform recovery. The problem is, basic_get will
  # keep blocking the thread that calls it without clear way to constantly unblock it
  # from the network activity loop (where recovery happens) with the current continuations
  # implementation (and even more correct and convenient ones, such as wait/notify, should
  # we implement them). So we return a triple of nils immediately which apps should be
  # able to handle anyway as "got no message, no need to act". MK.
  @last_basic_get_response = if @connection.open?
                               wait_on_basic_get_continuations
                             else
                               [nil, nil, nil]
                             end

  raise_if_continuation_resulted_in_a_channel_error!
  @last_basic_get_response
end

- (NilClass) basic_nack(delivery_tag, multiple = false, requeue = false)

Rejects or requeues messages just like #basic_reject but can do so with multiple messages at once.

Examples:

Requeue a message

conn  = Bunny.new
conn.start

ch    = conn.create_channel
q.subscribe do |delivery_info, properties, payload|
  # requeue the message
  ch.basic_nack(delivery_info.delivery_tag, false, true)
end

Reject a message

conn  = Bunny.new
conn.start

ch    = conn.create_channel
q.subscribe do |delivery_info, properties, payload|
  # requeue the message
  ch.basic_nack(delivery_info.delivery_tag)
end

Requeue a message fetched via basic.get

conn  = Bunny.new
conn.start

ch    = conn.create_channel
# we assume the queue exists and has messages
delivery_info, properties, payload = ch.basic_get("bunny.examples.queue3", :manual_ack => true)
ch.basic_nack(delivery_info.delivery_tag, false, true)

Requeue multiple messages fetched via basic.get

conn  = Bunny.new
conn.start

ch    = conn.create_channel
# we assume the queue exists and has messages
_, _, payload1 = ch.basic_get("bunny.examples.queue3", :manual_ack => true)
_, _, payload2 = ch.basic_get("bunny.examples.queue3", :manual_ack => true)
delivery_info, properties, payload3 = ch.basic_get("bunny.examples.queue3", :manual_ack => true)
# requeue all fetched messages up to payload3
ch.basic_nack(delivery_info.delivery_tag, true, true)

See Also:



797
798
799
800
801
802
803
804
805
# File 'lib/bunny/channel.rb', line 797

def basic_nack(delivery_tag, multiple = false, requeue = false)
  raise_if_no_longer_open!
  @connection.send_frame(AMQ::Protocol::Basic::Nack.encode(@id,
      delivery_tag,
      multiple,
      requeue))

  nil
end

- (Bunny::Channel) basic_publish(payload, exchange, routing_key, opts = {})

Publishes a message using basic.publish AMQP 0.9.1 method.

Options Hash (opts):

  • :persistent (Boolean)

    Should the message be persisted to disk?

  • :mandatory (Boolean)

    Should the message be returned if it cannot be routed to any queue?

  • :timestamp (Integer)

    A timestamp associated with this message

  • :expiration (Integer)

    Expiration time after which the message will be deleted

  • :type (String)

    Message type, e.g. what type of event or command this message represents. Can be any string

  • :reply_to (String)

    Queue name other apps should send the response to

  • :content_type (String)

    Message content type (e.g. application/json)

  • :content_encoding (String)

    Message content encoding (e.g. gzip)

  • :correlation_id (String)

    Message correlated to this one, e.g. what request this message is a reply for

  • :priority (Integer)

    Message priority, 0 to 9. Not used by RabbitMQ, only applications

  • :message_id (String)

    Any message identifier

  • :user_id (String)

    Optional user ID. Verified by RabbitMQ against the actual connection username

  • :app_id (String)

    Optional application ID

Raises:

  • (ArgumentError)


522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
# File 'lib/bunny/channel.rb', line 522

def basic_publish(payload, exchange, routing_key, opts = {})
  raise_if_no_longer_open!
  raise ArgumentError, "routing key cannot be longer than #{SHORTSTR_LIMIT} characters" if routing_key && routing_key.size > SHORTSTR_LIMIT

  exchange_name = if exchange.respond_to?(:name)
                    exchange.name
                  else
                    exchange
                  end

  mode = if opts.fetch(:persistent, true)
           2
         else
           1
         end

  opts[:delivery_mode] ||= mode
  opts[:content_type]  ||= DEFAULT_CONTENT_TYPE
  opts[:priority]      ||= 0

  if @next_publish_seq_no > 0
    @unconfirmed_set_mutex.synchronize do
      @unconfirmed_set.add(@next_publish_seq_no)
      @next_publish_seq_no += 1
    end
  end

  frames = AMQ::Protocol::Basic::Publish.encode(@id,
    payload,
    opts,
    exchange_name,
    routing_key,
    opts[:mandatory],
    false,
    @connection.frame_max)
  @connection.send_frameset_without_timeout(frames, self)

  self
end

- (AMQ::Protocol::Basic::QosOk) basic_qos(count, global = false)

Controls message delivery rate using basic.qos AMQP 0.9.1 method.

Raises:

  • (ArgumentError)

See Also:



619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
# File 'lib/bunny/channel.rb', line 619

def basic_qos(count, global = false)
  raise ArgumentError.new("prefetch count must be a positive integer, given: #{prefetch_count}") if count < 0
  raise_if_no_longer_open!

  @connection.send_frame(AMQ::Protocol::Basic::Qos.encode(@id, 0, count, global))

  Bunny::Timeout.timeout(read_write_timeout, ClientTimeout) do
    @last_basic_qos_ok = wait_on_continuations
  end
  raise_if_continuation_resulted_in_a_channel_error!

  @prefetch_count = count

  @last_basic_qos_ok
end

- (AMQ::Protocol::Basic::RecoverOk) basic_recover(requeue)

Redeliver unacknowledged messages



640
641
642
643
644
645
646
647
648
649
650
# File 'lib/bunny/channel.rb', line 640

def basic_recover(requeue)
  raise_if_no_longer_open!

  @connection.send_frame(AMQ::Protocol::Basic::Recover.encode(@id, requeue))
  Bunny::Timeout.timeout(read_write_timeout, ClientTimeout) do
    @last_basic_recover_ok = wait_on_continuations
  end
  raise_if_continuation_resulted_in_a_channel_error!

  @last_basic_recover_ok
end

- (NilClass) basic_reject(delivery_tag, requeue)

Rejects or requeues a message.

Examples:

Requeue a message

conn  = Bunny.new
conn.start

ch    = conn.create_channel
q.subscribe do |delivery_info, properties, payload|
  # requeue the message
  ch.basic_reject(delivery_info.delivery_tag, true)
end

Reject a message

conn  = Bunny.new
conn.start

ch    = conn.create_channel
q.subscribe do |delivery_info, properties, payload|
  # requeue the message
  ch.basic_reject(delivery_info.delivery_tag, false)
end

Requeue a message fetched via basic.get

conn  = Bunny.new
conn.start

ch    = conn.create_channel
# we assume the queue exists and has messages
delivery_info, properties, payload = ch.basic_get("bunny.examples.queue3", :manual_ack => true)
ch.basic_reject(delivery_info.delivery_tag, true)

See Also:



690
691
692
693
694
695
# File 'lib/bunny/channel.rb', line 690

def basic_reject(delivery_tag, requeue)
  raise_if_no_longer_open!
  @connection.send_frame(AMQ::Protocol::Basic::Reject.encode(@id, delivery_tag, requeue))

  nil
end

- (AMQ::Protocol::Channel::FlowOk) channel_flow(active)

Note:

Recent (e.g. 2.8.x., 3.x) RabbitMQ will employ TCP/IP-level back pressure on publishers if it detects that consumers do not keep up with them.

Enables or disables message flow for the channel. When message flow is disabled, no new messages will be delivered to consumers on this channel. This is typically used by consumers that cannot keep up with the influx of messages.



1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
# File 'lib/bunny/channel.rb', line 1272

def channel_flow(active)
  raise_if_no_longer_open!

  @connection.send_frame(AMQ::Protocol::Channel::Flow.encode(@id, active))
  Bunny::Timeout.timeout(read_write_timeout, ClientTimeout) do
    @last_channel_flow_ok = wait_on_continuations
  end
  raise_if_continuation_resulted_in_a_channel_error!

  @last_channel_flow_ok
end

- (Bunny::Session) client



267
268
269
# File 'lib/bunny/channel.rb', line 267

def client
  @connection
end

- (Object) close

Closes the channel. Closed channels can no longer be used (this includes associated Queue, Exchange and Bunny::Consumer instances.



233
234
235
236
237
# File 'lib/bunny/channel.rb', line 233

def close
  @connection.close_channel(self)
  closed!
  maybe_kill_consumer_work_pool!
end

- (Boolean) closed?

Returns true if this channel is closed (manually or because of an exception), false otherwise



247
248
249
# File 'lib/bunny/channel.rb', line 247

def closed?
  @status == :closed
end

- (AMQ::Protocol::Confirm::SelectOk) confirm_select(callback = nil)

Enables publisher confirms for the channel.



1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
# File 'lib/bunny/channel.rb', line 1361

def confirm_select(callback=nil)
  raise_if_no_longer_open!

  if @next_publish_seq_no == 0
    @confirms_continuations = new_continuation
    @unconfirmed_set        = Set.new
    @nacked_set             = Set.new
    @next_publish_seq_no    = 1
    @only_acks_received = true
  end

  @confirms_callback = callback

  @connection.send_frame(AMQ::Protocol::Confirm::Select.encode(@id, false))
  Bunny::Timeout.timeout(read_write_timeout, ClientTimeout) do
    @last_confirm_select_ok = wait_on_continuations
  end
  @confirm_mode = true
  raise_if_continuation_resulted_in_a_channel_error!
  @last_confirm_select_ok
end

- (Object) default_exchange

Provides access to the default exchange



360
361
362
# File 'lib/bunny/channel.rb', line 360

def default_exchange
  self.direct(AMQ::Protocol::EMPTY_STRING, :no_declare => true)
end

- (Bunny::Exchange) direct(name, opts = {})

Declares a direct exchange or looks it up in the cache of previously declared exchanges.

Options Hash (opts):

  • :durable (Boolean) — default: false

    Should the exchange be durable?

  • :auto_delete (Boolean) — default: false

    Should the exchange be automatically deleted when no longer in use?

  • :arguments (Hash) — default: {}

    Optional exchange arguments (used by RabbitMQ extensions)

See Also:



317
318
319
# File 'lib/bunny/channel.rb', line 317

def direct(name, opts = {})
  Exchange.new(self, :direct, name, opts)
end

- (Bunny::Exchange) exchange(name, opts = {})

Declares a headers exchange or looks it up in the cache of previously declared exchanges.

Options Hash (opts):

  • :type (String, Symbol) — default: :direct

    Exchange type, e.g. :fanout or "x-consistent-hash"

  • :durable (Boolean) — default: false

    Should the exchange be durable?

  • :auto_delete (Boolean) — default: false

    Should the exchange be automatically deleted when no longer in use?

  • :arguments (Hash) — default: {}

    Optional exchange arguments

See Also:



378
379
380
# File 'lib/bunny/channel.rb', line 378

def exchange(name, opts = {})
  Exchange.new(self, opts.fetch(:type, :direct), name, opts)
end

- (AMQ::Protocol::Exchange::BindOk) exchange_bind(source, destination, opts = {})

Binds an exchange to another exchange using exchange.bind AMQP 0.9.1 extension that RabbitMQ provides.

Options Hash (opts):

  • routing_key (String) — default: nil

    Routing key used for binding

  • arguments (Hash) — default: {}

    Optional arguments

See Also:



1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
# File 'lib/bunny/channel.rb', line 1183

def exchange_bind(source, destination, opts = {})
  raise_if_no_longer_open!

  source_name = if source.respond_to?(:name)
                  source.name
                else
                  source
                end

  destination_name = if destination.respond_to?(:name)
                       destination.name
                     else
                       destination
                     end

  @connection.send_frame(AMQ::Protocol::Exchange::Bind.encode(@id,
      destination_name,
      source_name,
      opts[:routing_key],
      false,
      opts[:arguments]))
  Bunny::Timeout.timeout(read_write_timeout, ClientTimeout) do
    @last_exchange_bind_ok = wait_on_continuations
  end

  raise_if_continuation_resulted_in_a_channel_error!
  @last_exchange_bind_ok
end

- (AMQ::Protocol::Exchange::DeclareOk) exchange_declare(name, type, opts = {})

Declares a echange using echange.declare AMQP 0.9.1 method.

Options Hash (opts):

  • durable (Boolean) — default: false

    Should information about this echange be persisted to disk so that it can survive broker restarts? Typically set to true for long-lived exchanges.

  • auto_delete (Boolean) — default: false

    Should this echange be deleted when it is no longer used?

  • passive (Boolean) — default: false

    If true, exchange will be checked for existence. If it does not exist, NotFound will be raised.

See Also:



1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
# File 'lib/bunny/channel.rb', line 1123

def exchange_declare(name, type, opts = {})
  raise_if_no_longer_open!

  @connection.send_frame(AMQ::Protocol::Exchange::Declare.encode(@id,
      name,
      type.to_s,
      opts.fetch(:passive, false),
      opts.fetch(:durable, false),
      opts.fetch(:auto_delete, false),
      opts.fetch(:internal, false),
      false, # nowait
      opts[:arguments]))
  Bunny::Timeout.timeout(read_write_timeout, ClientTimeout) do
    @last_exchange_declare_ok = wait_on_continuations
  end

  raise_if_continuation_resulted_in_a_channel_error!
  @last_exchange_declare_ok
end

- (AMQ::Protocol::Exchange::DeleteOk) exchange_delete(name, opts = {})

Deletes a exchange using exchange.delete AMQP 0.9.1 method

Options Hash (opts):

  • if_unused (Boolean) — default: false

    Should this exchange be deleted only if it is no longer used

See Also:



1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
# File 'lib/bunny/channel.rb', line 1153

def exchange_delete(name, opts = {})
  raise_if_no_longer_open!

  @connection.send_frame(AMQ::Protocol::Exchange::Delete.encode(@id,
      name,
      opts[:if_unused],
      false))
  Bunny::Timeout.timeout(read_write_timeout, ClientTimeout) do
    @last_exchange_delete_ok = wait_on_continuations
  end

  raise_if_continuation_resulted_in_a_channel_error!
  @last_exchange_delete_ok
end

- (AMQ::Protocol::Exchange::UnbindOk) exchange_unbind(source, destination, opts = {})

Unbinds an exchange from another exchange using exchange.unbind AMQP 0.9.1 extension that RabbitMQ provides.

Options Hash (opts):

  • routing_key (String) — default: nil

    Routing key used for binding

  • arguments (Hash) — default: {}

    Optional arguments

See Also:



1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
# File 'lib/bunny/channel.rb', line 1227

def exchange_unbind(source, destination, opts = {})
  raise_if_no_longer_open!

  source_name = if source.respond_to?(:name)
                  source.name
                else
                  source
                end

  destination_name = if destination.respond_to?(:name)
                       destination.name
                     else
                       destination
                     end

  @connection.send_frame(AMQ::Protocol::Exchange::Unbind.encode(@id,
      destination_name,
      source_name,
      opts[:routing_key],
      false,
      opts[:arguments]))
  Bunny::Timeout.timeout(read_write_timeout, ClientTimeout) do
    @last_exchange_unbind_ok = wait_on_continuations
  end

  raise_if_continuation_resulted_in_a_channel_error!
  @last_exchange_unbind_ok
end

- (Bunny::Exchange) fanout(name, opts = {})

Declares a fanout exchange or looks it up in the cache of previously declared exchanges.

Options Hash (opts):

  • :durable (Boolean) — default: false

    Should the exchange be durable?

  • :auto_delete (Boolean) — default: false

    Should the exchange be automatically deleted when no longer in use?

  • :arguments (Hash) — default: {}

    Optional exchange arguments (used by RabbitMQ extensions)

See Also:



299
300
301
# File 'lib/bunny/channel.rb', line 299

def fanout(name, opts = {})
  Exchange.new(self, :fanout, name, opts)
end

- (Object) flow(active)

Flow control. When set to false, RabbitMQ will stop delivering messages on this channel.



428
429
430
# File 'lib/bunny/channel.rb', line 428

def flow(active)
  channel_flow(active)
end

- (String) generate_consumer_tag(name = "bunny")

Unique string supposed to be used as a consumer tag.



1413
1414
1415
# File 'lib/bunny/channel.rb', line 1413

def generate_consumer_tag(name = "bunny")
  "#{name}-#{Time.now.to_i * 1000}-#{Kernel.rand(999_999_999_999)}"
end

- (Bunny::Exchange) headers(name, opts = {})

Declares a headers exchange or looks it up in the cache of previously declared exchanges.

Options Hash (opts):

  • :durable (Boolean) — default: false

    Should the exchange be durable?

  • :auto_delete (Boolean) — default: false

    Should the exchange be automatically deleted when no longer in use?

  • :arguments (Hash) — default: {}

    Optional exchange arguments

See Also:



353
354
355
# File 'lib/bunny/channel.rb', line 353

def headers(name, opts = {})
  Exchange.new(self, :headers, name, opts)
end

- (Object) nack(delivery_tag, multiple = false, requeue = false)

Rejects a message. A rejected message can be requeued or dropped by RabbitMQ. This method is similar to #reject but supports rejecting multiple messages at once, and is usually preferred.



484
485
486
487
488
# File 'lib/bunny/channel.rb', line 484

def nack(delivery_tag, multiple = false, requeue = false)
  guarding_against_stale_delivery_tags(delivery_tag) do
    basic_nack(delivery_tag.to_i, multiple, requeue)
  end
end

- (Integer) number



257
258
259
# File 'lib/bunny/channel.rb', line 257

def number
  self.id
end

- (Object) on_error(&block)

Defines a handler for errors that are not responses to a particular operations (e.g. basic.ack, basic.reject, basic.nack).



1428
1429
1430
# File 'lib/bunny/channel.rb', line 1428

def on_error(&block)
  @on_error = block
end

- (Object) on_uncaught_exception(&block)

Defines a handler for uncaught exceptions in consumers (e.g. delivered message handlers).



1436
1437
1438
# File 'lib/bunny/channel.rb', line 1436

def on_uncaught_exception(&block)
  @uncaught_exception_handler = block
end

- (Bunny::Channel) open

Opens the channel and resets its internal state



216
217
218
219
220
221
222
223
224
225
226
227
228
# File 'lib/bunny/channel.rb', line 216

def open
  @threads_waiting_on_continuations           = Set.new
  @threads_waiting_on_confirms_continuations  = Set.new
  @threads_waiting_on_basic_get_continuations = Set.new

  @connection.open_channel(self)
  # clear last channel error
  @last_channel_error = nil

  @status = :open

  self
end

- (Boolean) open?

Returns true if this channel is open, false otherwise



241
242
243
# File 'lib/bunny/channel.rb', line 241

def open?
  @status == :open
end

- (Object) prefetch(count)

Sets how many messages will be given to consumers on this channel before they have to acknowledge or reject one of the previously consumed messages



419
420
421
# File 'lib/bunny/channel.rb', line 419

def prefetch(count)
  self.basic_qos(count, false)
end

- (Bunny::Queue) queue(name = AMQ::Protocol::EMPTY_STRING, opts = {})

Declares a queue or looks it up in the per-channel cache.

Options Hash (opts):

  • :durable (Boolean) — default: false

    Should this queue be durable?

  • :auto-delete (Boolean) — default: false

    Should this queue be automatically deleted when the last consumer disconnects?

  • :exclusive (Boolean) — default: false

    Should this queue be exclusive (only can be used by this connection, removed when the connection is closed)?

  • :arguments (Boolean) — default: {}

    Additional optional arguments (typically used by RabbitMQ extensions and plugins)

See Also:



401
402
403
404
405
# File 'lib/bunny/channel.rb', line 401

def queue(name = AMQ::Protocol::EMPTY_STRING, opts = {})
  q = find_queue(name) || Bunny::Queue.new(self, name, opts)

  register_queue(q)
end

- (AMQ::Protocol::Queue::BindOk) queue_bind(name, exchange, opts = {})

Binds a queue to an exchange using queue.bind AMQP 0.9.1 method

Options Hash (opts):

  • routing_key (String) — default: nil

    Routing key used for binding

  • arguments (Hash) — default: {}

    Optional arguments

See Also:



1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
# File 'lib/bunny/channel.rb', line 1046

def queue_bind(name, exchange, opts = {})
  raise_if_no_longer_open!

  exchange_name = if exchange.respond_to?(:name)
                    exchange.name
                  else
                    exchange
                  end

  @connection.send_frame(AMQ::Protocol::Queue::Bind.encode(@id,
      name,
      exchange_name,
      (opts[:routing_key] || opts[:key]),
      false,
      opts[:arguments]))
  Bunny::Timeout.timeout(read_write_timeout, ClientTimeout) do
    @last_queue_bind_ok = wait_on_continuations
  end

  raise_if_continuation_resulted_in_a_channel_error!
  @last_queue_bind_ok
end

- (AMQ::Protocol::Queue::DeclareOk) queue_declare(name, opts = {})

Declares a queue using queue.declare AMQP 0.9.1 method.

Options Hash (opts):

  • durable (Boolean) — default: false

    Should information about this queue be persisted to disk so that it can survive broker restarts? Typically set to true for long-lived queues.

  • auto_delete (Boolean) — default: false

    Should this queue be deleted when the last consumer is cancelled?

  • exclusive (Boolean) — default: false

    Should only this connection be able to use this queue? If true, the queue will be automatically deleted when this connection is closed

  • passive (Boolean) — default: false

    If true, queue will be checked for existence. If it does not exist, NotFound will be raised.

See Also:



968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
# File 'lib/bunny/channel.rb', line 968

def queue_declare(name, opts = {})
  raise_if_no_longer_open!

  @connection.send_frame(AMQ::Protocol::Queue::Declare.encode(@id,
      name,
      opts.fetch(:passive, false),
      opts.fetch(:durable, false),
      opts.fetch(:exclusive, false),
      opts.fetch(:auto_delete, false),
      false,
      opts[:arguments]))
  @last_queue_declare_ok = wait_on_continuations

  raise_if_continuation_resulted_in_a_channel_error!

  @last_queue_declare_ok
end

- (AMQ::Protocol::Queue::DeleteOk) queue_delete(name, opts = {})

Deletes a queue using queue.delete AMQP 0.9.1 method

Options Hash (opts):

  • if_unused (Boolean) — default: false

    Should this queue be deleted only if it has no consumers?

  • if_empty (Boolean) — default: false

    Should this queue be deleted only if it has no messages?

See Also:



997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
# File 'lib/bunny/channel.rb', line 997

def queue_delete(name, opts = {})
  raise_if_no_longer_open!

  @connection.send_frame(AMQ::Protocol::Queue::Delete.encode(@id,
      name,
      opts[:if_unused],
      opts[:if_empty],
      false))
  Bunny::Timeout.timeout(read_write_timeout, ClientTimeout) do
    @last_queue_delete_ok = wait_on_continuations
  end
  raise_if_continuation_resulted_in_a_channel_error!

  @last_queue_delete_ok
end

- (AMQ::Protocol::Queue::PurgeOk) queue_purge(name, opts = {})

Purges a queue (removes all messages from it) using queue.purge AMQP 0.9.1 method.



1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
# File 'lib/bunny/channel.rb', line 1020

def queue_purge(name, opts = {})
  raise_if_no_longer_open!

  @connection.send_frame(AMQ::Protocol::Queue::Purge.encode(@id, name, false))

  Bunny::Timeout.timeout(read_write_timeout, ClientTimeout) do
    @last_queue_purge_ok = wait_on_continuations
  end
  raise_if_continuation_resulted_in_a_channel_error!

  @last_queue_purge_ok
end

- (AMQ::Protocol::Queue::UnbindOk) queue_unbind(name, exchange, opts = {})

Unbinds a queue from an exchange using queue.unbind AMQP 0.9.1 method

Options Hash (opts):

  • routing_key (String) — default: nil

    Routing key used for binding

  • arguments (Hash) — default: {}

    Optional arguments

See Also:



1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
# File 'lib/bunny/channel.rb', line 1082

def queue_unbind(name, exchange, opts = {})
  raise_if_no_longer_open!

  exchange_name = if exchange.respond_to?(:name)
                    exchange.name
                  else
                    exchange
                  end

  @connection.send_frame(AMQ::Protocol::Queue::Unbind.encode(@id,
      name,
      exchange_name,
      opts[:routing_key],
      opts[:arguments]))
  Bunny::Timeout.timeout(read_write_timeout, ClientTimeout) do
    @last_queue_unbind_ok = wait_on_continuations
  end

  raise_if_continuation_resulted_in_a_channel_error!
  @last_queue_unbind_ok
end

- (Object) recover(ignored = true)

Tells RabbitMQ to redeliver unacknowledged messages



434
435
436
437
# File 'lib/bunny/channel.rb', line 434

def recover(ignored = true)
  # RabbitMQ only supports basic.recover with requeue = true
  basic_recover(true)
end

- (Object) recover_cancelled_consumers!



1532
1533
1534
# File 'lib/bunny/channel.rb', line 1532

def recover_cancelled_consumers!
  @recover_cancelled_consumers = true
end

- (Object) recover_confirm_mode

Recovers publisher confirms mode. Used by the Automatic Network Failure Recovery feature.



1476
1477
1478
1479
1480
1481
# File 'lib/bunny/channel.rb', line 1476

def recover_confirm_mode
  if using_publisher_confirmations?
    @delivery_tag_offset = @next_publish_seq_no - 1
    confirm_select(@confirms_callback)
  end
end

- (Object) recover_consumers

Recovers consumers. Used by the Automatic Network Failure Recovery feature.



1516
1517
1518
1519
1520
1521
1522
1523
1524
# File 'lib/bunny/channel.rb', line 1516

def recover_consumers
  unless @consumers.empty?
    @work_pool = ConsumerWorkPool.new(@work_pool.size)
    @work_pool.start
  end
  @consumers.values.dup.each do |c|
    c.recover_from_network_failure
  end
end

- (Object) recover_exchanges

Recovers exchanges. Used by the Automatic Network Failure Recovery feature.



1495
1496
1497
1498
1499
# File 'lib/bunny/channel.rb', line 1495

def recover_exchanges
  @exchanges.values.dup.each do |x|
    x.recover_from_network_failure
  end
end

- (Object) recover_from_network_failure

Recovers basic.qos setting, exchanges, queues and consumers. Used by the Automatic Network Failure Recovery feature.



1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
# File 'lib/bunny/channel.rb', line 1450

def recover_from_network_failure
  @logger.debug "Recovering channel #{@id} after network failure"
  release_all_continuations

  recover_prefetch_setting
  recover_confirm_mode
  recover_tx_mode
  recover_exchanges
  # this includes recovering bindings
  recover_queues
  recover_consumers
  increment_recoveries_counter
end

- (Object) recover_prefetch_setting

Recovers basic.qos setting. Used by the Automatic Network Failure Recovery feature.



1468
1469
1470
# File 'lib/bunny/channel.rb', line 1468

def recover_prefetch_setting
  basic_qos(@prefetch_count) if @prefetch_count
end

- (Object) recover_queues

Recovers queues and bindings. Used by the Automatic Network Failure Recovery feature.



1505
1506
1507
1508
1509
1510
# File 'lib/bunny/channel.rb', line 1505

def recover_queues
  @queues.values.dup.each do |q|
    @logger.debug "Recovering queue #{q.name}"
    q.recover_from_network_failure
  end
end

- (Object) recover_tx_mode

Recovers transaction mode. Used by the Automatic Network Failure Recovery feature.



1487
1488
1489
# File 'lib/bunny/channel.rb', line 1487

def recover_tx_mode
  tx_select if @tx_mode
end

- (Boolean) recovers_cancelled_consumers?



1537
1538
1539
# File 'lib/bunny/channel.rb', line 1537

def recovers_cancelled_consumers?
  !!@recover_cancelled_consumers
end

- (Object) reject(delivery_tag, requeue = false)

Rejects a message. A rejected message can be requeued or dropped by RabbitMQ.



454
455
456
457
458
# File 'lib/bunny/channel.rb', line 454

def reject(delivery_tag, requeue = false)
  guarding_against_stale_delivery_tags(delivery_tag) do
    basic_reject(delivery_tag.to_i, requeue)
  end
end

- (Object) synchronize(&block)

Synchronizes given block using this channel's mutex.



1405
1406
1407
# File 'lib/bunny/channel.rb', line 1405

def synchronize(&block)
  @publishing_mutex.synchronize(&block)
end

- (String) to_s



1545
1546
1547
# File 'lib/bunny/channel.rb', line 1545

def to_s
  "#<#{self.class.name}:#{object_id} @id=#{self.number} @connection=#{@connection.to_s}>"
end

- (Bunny::Exchange) topic(name, opts = {})

Declares a topic exchange or looks it up in the cache of previously declared exchanges.

Options Hash (opts):

  • :durable (Boolean) — default: false

    Should the exchange be durable?

  • :auto_delete (Boolean) — default: false

    Should the exchange be automatically deleted when no longer in use?

  • :arguments (Hash) — default: {}

    Optional exchange arguments (used by RabbitMQ extensions)

See Also:



335
336
337
# File 'lib/bunny/channel.rb', line 335

def topic(name, opts = {})
  Exchange.new(self, :topic, name, opts)
end

- (AMQ::Protocol::Tx::CommitOk) tx_commit

Commits current transaction



1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
# File 'lib/bunny/channel.rb', line 1309

def tx_commit
  raise_if_no_longer_open!

  @connection.send_frame(AMQ::Protocol::Tx::Commit.encode(@id))
  Bunny::Timeout.timeout(read_write_timeout, ClientTimeout) do
    @last_tx_commit_ok = wait_on_continuations
  end
  raise_if_continuation_resulted_in_a_channel_error!

  @last_tx_commit_ok
end

- (AMQ::Protocol::Tx::RollbackOk) tx_rollback

Rolls back current transaction



1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
# File 'lib/bunny/channel.rb', line 1324

def tx_rollback
  raise_if_no_longer_open!

  @connection.send_frame(AMQ::Protocol::Tx::Rollback.encode(@id))
  Bunny::Timeout.timeout(read_write_timeout, ClientTimeout) do
    @last_tx_rollback_ok = wait_on_continuations
  end
  raise_if_continuation_resulted_in_a_channel_error!

  @last_tx_rollback_ok
end

- (AMQ::Protocol::Tx::SelectOk) tx_select

Puts the channel into transaction mode (starts a transaction)



1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
# File 'lib/bunny/channel.rb', line 1293

def tx_select
  raise_if_no_longer_open!

  @connection.send_frame(AMQ::Protocol::Tx::Select.encode(@id))
  Bunny::Timeout.timeout(read_write_timeout, ClientTimeout) do
    @last_tx_select_ok = wait_on_continuations
  end
  raise_if_continuation_resulted_in_a_channel_error!
  @tx_mode = true

  @last_tx_select_ok
end

- (Boolean) using_publisher_confirmations? Also known as: using_publisher_confirms?

Returns true if this channel has Publisher Confirms enabled, false otherwise



1349
1350
1351
# File 'lib/bunny/channel.rb', line 1349

def using_publisher_confirmations?
  @next_publish_seq_no > 0
end

- (Boolean) using_tx?



1337
1338
1339
# File 'lib/bunny/channel.rb', line 1337

def using_tx?
  !!@tx_mode
end

- (Boolean) wait_for_confirms

Blocks calling thread until confirms are received for all currently unacknowledged published messages. Returns immediately if there are no outstanding confirms.



1393
1394
1395
1396
# File 'lib/bunny/channel.rb', line 1393

def wait_for_confirms
  wait_on_confirms_continuations
  read_and_reset_only_acks_received
end