It turns out that the difference is pretty straightforward. If you publish a message with the :mandatory option set to true like so –
my_exchange.publish('Test message', :mandatory => true)
Then your message will be returned unless it can be routed to a queue.
However, if you publish a message with the :immediate option set to true, as in this example –
my_exchange.publish('Test message', :immediate => true)
Then your message will be returned unless it can be consumed immediately.
IMPORTANT: If you use either of these options with Exchange#publish in Bunny, you must check whether or not your message has been returned after you make the publish call, otherwise return messages will build up and problems will ensue. With Bunny you can check for returned messages by placing something similar to the following after your publish call –
returned_msg = my_client.returned_message
The Client#returned_message method takes an optional :timeout argument (default value is 0.1 seconds). This allows you to specify how long the method will wait to receive a returned message should the default value prove to be problematic.
If there is a returned message the method returns a hash containing :header, :payload and :return_details. The payload contains the message contents. If there is no returned message the method returns the symbol :no_return.