Class: Bunny::Queue

Inherits:
Qrack::Queue show all
Defined in:
lib/ext/bunny-0.6.0/lib/bunny/queue08.rb

Overview

DESCRIPTION:

Queues store and forward messages. Queues can be configured in the server or created at runtime. Queues must be attached to at least one exchange in order to receive messages from publishers.

Instance Attribute Summary

Attributes inherited from Qrack::Queue

#client, #delivery_tag, #name, #subscription

Instance Method Summary collapse

Methods inherited from Qrack::Queue

#consumer_count, #message_count, #publish

Constructor Details

#initialize(client, name, opts = {}) ⇒ Queue

Returns a new instance of Queue.

Raises:



14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
 
# File 'lib/ext/bunny-0.6.0/lib/bunny/queue08.rb', line 14

def initialize(client, name, opts = {})
# check connection to server
raise Bunny::ConnectionError, 'Not connected to server' if client.status == :not_connected

  @client = client
  @opts   = opts
   @delivery_tag = nil
   @subscription = nil

   # Queues without a given name are named by the server and are generally
   # bound to the process that created them.
   if !name
     opts = {
       :passive => false,
       :durable => false,
       :exclusive => true,
       :auto_delete => true
     }.merge(opts)
   end
	
# ignore the :nowait option if passed, otherwise program will hang waiting for a
# response that will not be sent by the server
opts.delete(:nowait)

  client.send_frame(
    Qrack::Protocol::Queue::Declare.new({ :queue => name || '', :nowait => false }.merge(opts))
  )
	
   method = client.next_method

client.check_response(method,	Qrack::Protocol::Queue::DeclareOk, "Error declaring queue #{name}")

   @name = method.queue
client.queues[@name] = self
end

Instance Method Details

#ack(opts = {}) ⇒ Object

DESCRIPTION:

Acknowledges one or more messages delivered via the Deliver or Get-Ok methods. The client can ask to confirm a single message or a set of messages up to and including a specific message.

OPTIONS:

  • :delivery_tag

  • :multiple => true or false (default) - If set to true, the delivery tag is treated as “up to and including”, so that the client can acknowledge multiple messages with a single method. If set to false, the delivery tag refers to a single message. If the multiple field is true, and the delivery tag is zero, tells the server to acknowledge all outstanding messages.



67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
 
# File 'lib/ext/bunny-0.6.0/lib/bunny/queue08.rb', line 67

def ack(opts={})
			# Set delivery tag
			if delivery_tag.nil? and opts[:delivery_tag].nil?
raise Bunny::AcknowledgementError, "No delivery tag received"
			else
self.delivery_tag = opts[:delivery_tag] if delivery_tag.nil?
			end
			
  client.send_frame(
    Qrack::Protocol::Basic::Ack.new({:delivery_tag => delivery_tag, :multiple => false}.merge(opts))
  )

			# reset delivery tag
			self.delivery_tag = nil
end

#bind(exchange, opts = {}) ⇒ Object

DESCRIPTION:

Binds a queue to an exchange. Until a queue is bound it will not receive any messages. Queues are bound to the direct exchange ” by default. If error occurs, a Bunny::ProtocolError is raised.

  • :key => 'routing key'* <tt>:key => 'routing_key' - Specifies the routing key for the binding. The routing key is used for routing messages depending on the exchange configuration.

  • :nowait => true or false (default) - Ignored by Bunny, always false.

RETURNS:

:bind_ok if successful.



100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
 
# File 'lib/ext/bunny-0.6.0/lib/bunny/queue08.rb', line 100

def bind(exchange, opts = {})
  exchange           = exchange.respond_to?(:name) ? exchange.name : exchange

# ignore the :nowait option if passed, otherwise program will hang waiting for a
# response that will not be sent by the server
opts.delete(:nowait)

  client.send_frame(
    Qrack::Protocol::Queue::Bind.new({ :queue => name,
																:exchange => exchange,
																:routing_key => opts.delete(:key),
																:nowait => false }.merge(opts))
  )
	
method = client.next_method

client.check_response(method,	Qrack::Protocol::Queue::BindOk,
	"Error binding queue: #{name} to exchange: #{exchange}")

# return message
:bind_ok
end

#delete(opts = {}) ⇒ Object

DESCRIPTION:

Requests that a queue is deleted from broker/server. When a queue is deleted any pending messages are sent to a dead-letter queue if this is defined in the server configuration. Removes reference from queues if successful. If an error occurs raises Bunny::ProtocolError.

Options:

  • :if_unused => true or false (default) - If set to true, the server will only delete the queue if it has no consumers. If the queue has consumers the server does not delete it but raises a channel exception instead.

  • :if_empty => true or false (default) - If set to true, the server will only delete the queue if it has no messages. If the queue is not empty the server raises a channel exception.

  • :nowait => true or false (default) - Ignored by Bunny, always false.

Returns:

:delete_ok if successful



146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
 
# File 'lib/ext/bunny-0.6.0/lib/bunny/queue08.rb', line 146

def delete(opts = {})
# ignore the :nowait option if passed, otherwise program will hang waiting for a
# response that will not be sent by the server
opts.delete(:nowait)

  client.send_frame(
    Qrack::Protocol::Queue::Delete.new({ :queue => name, :nowait => false }.merge(opts))
  )
	
method = client.next_method

client.check_response(method,	Qrack::Protocol::Queue::DeleteOk, "Error deleting queue #{name}")

client.queues.delete(name)

# return confirmation
:delete_ok
end

#pop(opts = {}, &blk) ⇒ Object

DESCRIPTION:

Gets a message from a queue in a synchronous way. If error occurs, raises Bunny::ProtocolError.

OPTIONS:

  • :ack => false (default) or true - If set to false, the server does not expect an acknowledgement message from the client. If set to true, the server expects an acknowledgement message from the client and will re-queue the message if it does not receive one within a time specified by the server.

RETURNS:

Hash {:header, :payload, :delivery_details}. :delivery_details is a hash {:consumer_tag, :delivery_tag, :redelivered, :exchange, :routing_key}.

If the queue is empty the returned hash will contain the values -

:header => nil
:payload => :queue_empty
:delivery_details => nil

N.B. If a block is provided then the hash will be passed into the block and the return value will be nil.



194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
 
# File 'lib/ext/bunny-0.6.0/lib/bunny/queue08.rb', line 194

def pop(opts = {}, &blk)

# do we want to have to provide an acknowledgement?
ack = opts.delete(:ack)

  client.send_frame(
    Qrack::Protocol::Basic::Get.new({ :queue => name,
														 :consumer_tag => name,
														 :no_ack => !ack,
														 :nowait => true }.merge(opts))
  )
	
method = client.next_method

if method.is_a?(Qrack::Protocol::Basic::GetEmpty) then
	queue_empty = true
elsif	!method.is_a?(Qrack::Protocol::Basic::GetOk)
	raise Bunny::ProtocolError, "Error getting message from queue #{name}"
end

if !queue_empty
	# get delivery tag to use for acknowledge
	self.delivery_tag = method.delivery_tag if ack

   header = client.next_payload
	
   # If maximum frame size is smaller than message payload body then message
	# will have a message header and several message bodies
	msg = ''
	while msg.length < header.size
		msg += client.next_payload
	end
	
	msg_hash = {:header => header, :payload => msg, :delivery_details => method.arguments}
	
else
	msg_hash = {:header => nil, :payload => :queue_empty, :delivery_details => nil}
end

# Pass message hash to block or return message hash
blk ? blk.call(msg_hash) : msg_hash		

end

#purge(opts = {}) ⇒ Object

DESCRIPTION:

Removes all messages from a queue. It does not cancel consumers. Purged messages are deleted without any formal “undo” mechanism. If an error occurs raises Bunny::ProtocolError.

Options:

  • :nowait => true or false (default) - Ignored by Bunny, always false.

Returns:

:purge_ok if successful



254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
 
# File 'lib/ext/bunny-0.6.0/lib/bunny/queue08.rb', line 254

def purge(opts = {})
# ignore the :nowait option if passed, otherwise program will hang waiting for a
# response that will not be sent by the server
opts.delete(:nowait)

  client.send_frame(
    Qrack::Protocol::Queue::Purge.new({ :queue => name, :nowait => false }.merge(opts))
  )
	
method = client.next_method

client.check_response(method,	Qrack::Protocol::Queue::PurgeOk, "Error purging queue #{name}")

# return confirmation
:purge_ok

end

#status ⇒ Object

DESCRIPTION:

Returns hash :consumer_count.



280
281
282
283
284
285
286
 
# File 'lib/ext/bunny-0.6.0/lib/bunny/queue08.rb', line 280

def status
  client.send_frame(
    Qrack::Protocol::Queue::Declare.new({ :queue => name, :passive => true })
  )
  method = client.next_method
  {:message_count => method.message_count, :consumer_count => method.consumer_count}
end

#subscribe(opts = {}, &blk) ⇒ Object 



289
290
291
292
293
294
295
296
 
# File 'lib/ext/bunny-0.6.0/lib/bunny/queue08.rb', line 289

def subscribe(opts = {}, &blk)
	# Create subscription
	s = Bunny::Subscription.new(client, self, opts)
	s.start(&blk)
	
	# Reset when subscription finished
	@subscription = nil
end

#unbind(exchange, opts = {}) ⇒ Object

DESCRIPTION:

Removes a queue binding from an exchange. If error occurs, a Bunny::ProtocolError is raised.

OPTIONS:

  • :key => 'routing key'* <tt>:key => 'routing_key' - Specifies the routing key for the binding.

  • :nowait => true or false (default) - Ignored by Bunny, always false.

RETURNS:

:unbind_ok if successful.



358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
 
# File 'lib/ext/bunny-0.6.0/lib/bunny/queue08.rb', line 358

def unbind(exchange, opts = {})
  exchange = exchange.respond_to?(:name) ? exchange.name : exchange
	
# ignore the :nowait option if passed, otherwise program will hang waiting for a
# response that will not be sent by the server
opts.delete(:nowait)

  client.send_frame(
    Qrack::Protocol::Queue::Unbind.new({ :queue => name,
																	:exchange => exchange,
																	:routing_key => opts.delete(:key),
																	:nowait => false }.merge(opts)
    )
  )
	
method = client.next_method

client.check_response(method,	Qrack::Protocol::Queue::UnbindOk, "Error unbinding queue #{name}")
	
# return message
:unbind_ok
end

#unsubscribe(opts = {}) ⇒ Object

DESCRIPTION:

Cancels a consumer. This does not affect already delivered messages, but it does mean the server will not send any more messages for that consumer.

OPTIONS:

  • :consumer_tag => 'tag' - Specifies the identifier for the consumer.

  • :nowait => true or false (default) - Ignored by Bunny, always false.

Returns:

:unsubscribe_ok if successful

Raises:



316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
 
# File 'lib/ext/bunny-0.6.0/lib/bunny/queue08.rb', line 316

def unsubscribe(opts = {})
			# Default consumer_tag from subscription if not passed in
			consumer_tag = subscription ? subscription.consumer_tag : opts[:consumer_tag]
			
			# Must have consumer tag to tell server what to unsubscribe
			raise Bunny::UnsubscribeError,
"No consumer tag received" if !consumer_tag
			
  # Cancel consumer
  client.send_frame( Qrack::Protocol::Basic::Cancel.new(:consumer_tag => consumer_tag,
																										:nowait => false))
																										
			method = client.next_method

			client.check_response(method,	Qrack::Protocol::Basic::CancelOk,
"Error unsubscribing from queue #{name}")

			# Reset subscription
			@subscription = nil

			# Return confirmation
			:unsubscribe_ok
			
end