Amazon Simple Queue Service
Developer Guide (API Version 2012-11-05)
« PreviousNext »
View the PDF for this guide.Go to the AWS Discussion Forum for this product.Go to the Kindle Store to download this guide in Kindle format.Did this page help you?  Yes | No |  Tell us about it...

Amazon SQS Long Polling

The API Version 2012-11-05 of Amazon SQS provides support for long polling.

One benefit of long polling with Amazon SQS is the reduction of the number of empty responses, when there are no messages available to return, in reply to a ReceiveMessage request sent to an Amazon SQS queue. Long polling allows the Amazon SQS service to wait until a message is available in the queue before sending a response. So unless the connection times out, the response to the ReceiveMessage request will contain at least one of the available messages (if any) and up to the maximum number requested in the ReceiveMessage call.

Another benefit is helping to eliminate false empty responses, where messages are available in the queue but are not included in the response. This happens when Amazon SQS uses short (standard) polling, the default behavior, where only a subset of the servers (based on a weighted random distribution) are queried to see if any messages are available to include in the response. On the other hand, when long polling in enabled, Amazon SQS queries all of the servers.

Reducing the number of empty responses and false empty responses also helps reduce your cost of using Amazon SQS.

Short polling occurs when the WaitTimeSeconds parameter of a ReceiveMessage call is set to 0. This happens in one of two ways – either the ReceiveMessage call sets WaitTimeSeconds to 0, or the ReceiveMessage call doesn’t set WaitTimeSeconds and the queue attribute ReceiveMessageWaitTimeSeconds is 0.

Note

A value set between 1 to 20 for the WaitTimeSeconds parameter for ReceiveMessage has priority over any value set for the queue attribute ReceiveMessageWaitTimeSeconds.

There are three different API action calls you can use to enable long polling in Amazon SQS, ReceiveMessage, CreateQueue, and SetQueueAttributes. For ReceiveMessage, you configure the WaitTimeSeconds parameter, and for CreateQueue and SetQueueAttributes, you configure the ReceiveMessageWaitTimeSeconds attribute.

Important

If you decide to implement long polling with multiple queues then it is recommended that you use one thread for each queue, instead of trying to use one single thread for polling all of the queues. When using one thread for each queue your application is able to process the messages in each of the queues as they become available, as opposed to one single thread for multiple queues where your application could be blocked from processing available messages in the other queues while waiting (up to 20 seconds) on a queue that does not have any available messages.

For most use cases when using long polling, you should set the timeout value to the maximum of 20 seconds. If the 20 second maximum does not work for your application, you can choose a shorter long poll timeout, down to as low as 1 second. If you are not using an AWS SDK to access Amazon SQS, or if you’ve specially configured your AWS SDK to have a shorter timeout, you may need to modify your Amazon SQS client to allow for longer requests or use a shorter long poll timeout.

Enabling Long Polling with the AWS Management Console

You can enable long polling using the AWS Management Console by setting a Receive Message Wait Time value that is greater than 0.

To enable long polling with the AWS Management Console for a new queue

  1. Sign in to the AWS Management Console and open the Amazon SQS console at https://console.aws.amazon.com/sqs/.

  2. Click Create New Queue.

    AWS Management Console Create New Queue button
  3. In the Create New Queue dialog box, enter a name for your queue (e.g., MyQueue) in the Queue Name field.

    AWS Management Console Create New Queue Dialog box
  4. Enter a positive integer value, from 1 to 20 seconds, for Receive Message Wait Time.

    You can leave the default value settings for the remaining fields or enter new values.

    AWS Management Console Create New Queue dialog box with Receive Message Wait Time highlighted.
  5. Click Create Queue.

You can use the AWS Management Console to change the Receive Message Wait Time setting for an existing queue by selecting the Configure Queue action with an existing queue highlighted.

To set a new Receive Message Wait Time value for an existing queue

  1. Select the Configure Queue action with an existing queue highlighted.

    AWS Management Console Amazon SQS Queue Actions drop-down list with Configure Queue highlighted.
  2. Change the value of Receive Message Wait Time to a positive integer value.

    AWS Management Console Amazon SQS Configure Queue dialog box with Receive Message Wait Time highlighted.
  3. Click Save Changes.

Enabling Long Polling with the Query API

The following Query API example enables long polling by calling the ReceiveMessage action with the WaitTimeSeconds parameter set to 10 seconds. For more information, go to ReceiveMessage in the Amazon Simple Queue Service API Reference.

How you structure the AUTHPARAMS depends on how you are signing your API request. For information on AUTHPARAMS in Signature Version 4, go to Examples of Signed Signature Version 4 Requests.

http://sqs.us-east-1.amazonaws.com/123456789012/testQueue/
?Action=ReceiveMessage
&WaitTimeSeconds=10
&MaxNumberOfMessages=5
&VisibilityTimeout=15
&AttributeName=All;
&Version=2012-11-05
&Expires=2013-10-25T22%3A52%3A43PST
&AUTHPARAMS

The following example shows another option for enabling long polling. Here, the ReceiveMessageWaitTimeSeconds attribute for the SetQueueAttributes action is set to 20 seconds. For more information, go to SetQueueAttributes in the Amazon Simple Queue Service API Reference.

http://sqs.us-east-1.amazonaws.com/123456789012/testQueue/
?Action=SetQueueAttributes
&Attribute.Name=ReceiveMessageWaitTimeSeconds
&Attribute.Value=20
&Version=2012-11-05
&Expires=2013-10-25T22%3A52%3A43PST
&AUTHPARAMS