Module: Qup::QueueAPI

Included in:
Adapter::Kestrel::Queue, Adapter::Maildir::Queue, Adapter::Redis::Queue
Defined in:
lib/qup/queue_api.rb

Overview

Public: A QueueAPI for use in a point-to-point messaging pattern.

The Queue guarantees that each Message that is on the Queue is delivered and acknowledged only once.

A very common pattern for Queue usage is a worker pattern where you have a Producer putting job Messages on the Queue and a collection of Consumers which work on those job Messages.

This is the API that MUST be implemented in the adapter.

Example:

session = Session.new( uri )
queue = session.queue( 'my_queue' )

queue.producer  # => Producer
queue.consumer  # => Consumer
queue.depth     # => 4

Instance Method Summary collapse

Instance Method Details

#acknowledge(message) ⇒ Object

Internal: Acknowledge that message is completed and remove it from the Queue.

Returns nothing

Raises:

  • (NotImplementedError) 


119
120
121
 
# File 'lib/qup/queue_api.rb', line 119

def acknowledge( message )
  raise NotImplementedError, "please implement 'acknowledge'"
end

#consume(&block) ⇒ Object

Internal: Retrieve an item from the Queue

options - a Hash of options determining how long to wait for a Message

:block   - should we block until a Message is available
           (default: true )
:timeout - how long to wait for a Message, only valid if
           :block is false

A user of the Qup API should use a Consumer instance to retrieve items from the Queue.

Returns a Message

Raises:

  • (NotImplementedError) 


110
111
112
 
# File 'lib/qup/queue_api.rb', line 110

def consume(&block)
  raise NotImplementedError, "please implement 'consume'"
end

#consumer ⇒ Object

Public: create a Consumer for this Queue

Returns a new Consumer



37
38
39
 
# File 'lib/qup/queue_api.rb', line 37

def consumer
  Consumer.new( self )
end

#depth ⇒ Object

Public: return the number of Messages on the Queue

Returns an integer of the Queue depth

Raises:

  • (NotImplementedError) 


59
60
61
 
# File 'lib/qup/queue_api.rb', line 59

def depth
  raise NotImplementedError, "please implement 'depth'"
end

#destroy ⇒ Object

Public: destroy the Queue if possible

This will clear the Queue and remove it from the system if possible

Returns nothing.



78
79
80
81
82
 
# File 'lib/qup/queue_api.rb', line 78

def destroy
  super
rescue NoMethodError
  raise NotImplementedError, "please implement 'destroy'"
end

#flush ⇒ Object

Public: empty all the messages from the Queue, this does not consume them, this removes the from the Queue

Returns nothing

Raises:

  • (NotImplementedError) 


68
69
70
 
# File 'lib/qup/queue_api.rb', line 68

def flush
  raise NotImplementedError, "please implement 'flush'"
end

#name ⇒ Object

Public: the name of the Queue

Returns the String name



49
50
51
52
53
 
# File 'lib/qup/queue_api.rb', line 49

def name
  super
rescue NoMethodError
  raise NotImplementedError, "please implement 'name'"
end

#produce(message) ⇒ Object

Internal: Put an item onto the Queue

message - the data to put onto the queue

A user of the Qup API should use a Producer instance to put items onto the queue.

Returns the Message that was put onto the Queue

Raises:

  • (NotImplementedError) 


93
94
95
 
# File 'lib/qup/queue_api.rb', line 93

def produce( message )
  raise NotImplementedError, "please implement 'produce'"
end

#producer ⇒ Object

Public: create a Producer for this Queue

Returns a new Producer



30
31
32
 
# File 'lib/qup/queue_api.rb', line 30

def producer
  Producer.new( self )
end