Use short and long polling to receive messages from a queue - Simple Message Queue (formerly MNS)

Simple Message Queue (SMQ, formerly MNS) supports two methods for consuming messages from a queue: short polling and long polling. Choose between them based on your latency and cost requirements.

Short polling returns a response immediately, whether or not a message is available. This minimizes per-request latency but can produce a high volume of empty responses.
Long polling holds the connection open until a message arrives or the wait period expires. This reduces empty responses and lowers costs, making it the recommended method for most workloads.

How short polling works

With short polling, the SMQ cluster responds to each receive request immediately. If no message is available, the response indicates an empty result.

To enable short polling, meet either of the following conditions:

Set the long polling period to 0 when you create the queue.
Set the waitSeconds parameter to 0 when you call the API operation to receive messages.

Either condition triggers short polling. Because the server responds instantly regardless of message availability, frequent requests to an empty queue generate unnecessary API calls and increase costs.

How long polling works

With long polling, the server holds the connection open and responds only when a message arrives or the wait period expires. This eliminates empty responses during the wait window and reduces the total number of API calls.

To enable long polling, meet either of the following conditions:

Set the long polling period to a value greater than 0 (up to 30 seconds) when you create the queue.
Set the waitSeconds parameter to a value greater than 0 when you call the API operation to receive messages.

If both the queue-level long polling period and the request-level waitSeconds parameter are set, the waitSeconds value takes precedence.

Benefits of long polling

Immediate delivery: Messages are returned as soon as they arrive, without waiting for the next polling cycle.
Fewer empty responses: The server holds the request until a message is available, so idle queues no longer generate constant empty responses.
Lower costs: Fewer API requests mean lower messaging costs.

Configuration reference

Parameter	Level	Short polling value	Long polling value	Maximum
Long polling period	Queue (set at creation)	`0`	Greater than `0`	30 seconds
`waitSeconds`	API request (receive message)	`0`	Greater than `0`	30 seconds

Precedence rule: The waitSeconds value in an API request overrides the long polling period configured for the queue.

Best practices

Prefer long polling for most workloads. Short polling is only appropriate when your application requires sub-second response times from the receive call itself, regardless of whether a message is available.
Increase the long polling period if you see frequent empty responses. If your consumer sends a high volume of receive requests but most return empty, increase the long polling period to reduce unnecessary API calls and lower costs.