 | Feedback |  |
When a consuming component in your system receives and processes a message from the queue, the message remains in the queue. To prevent other consuming components from receiving and processing the same message, Amazon SQS blocks them with a visibility timeout. See the figure and discussion below.
Once a message is returned to a consuming component, it isn't available to other receive requests for the duration of the visibility timeout period. Once the timeout period expires, the message returns to a subsequent receive request unless you delete it from the queue first.
If a message should only be received once, you should delete it within the duration of the visibility timeout.
Each queue starts with a default setting of 30 seconds for the visibility timeout. You can change that setting for the entire queue. Typically, you'll set the visibility timeout to the average time it takes to process and delete a message from the queue. When receiving messages, you can set a special visibility timeout for the returned messages without changing the overall queue timeout.
If you want to receive a particular message regardless of its visibility timeout, you can peek in on the message. Peeking does not affect the state of the visibility timeout for the message.
When you receive a message from the queue, you might find the visibility timeout for the queue is insufficient to fully process and delete that message. SQS allows you to extend the visibility timeout for that particular message.
For example, let's say the timeout for the queue is 30 seconds, and you receive a message. Once you're 20 seconds into the timeout for that message, you extend it by 60 seconds (to do this, you call ChangeMessageVisibility with VisibilityTimeout=60 seconds). At that moment, you then have 60 seconds for your timeout (not 10+60 = 70 seconds; the extension isn't additive).
The extension you request is not stored in memory for that message. If for some reason you don't delete the message and the message is received again, the visibility timeout for the message the next time it's received is the overall value for the queue and not the extended value you previously set.
When you receive a message from the queue, you might find that you actually don't want to process and delete that message. SQS allows you to terminate the visibility timeout for a specific message, which immediately makes the message visible to other components in the system to process. To do this, you call ChangeMessageVisibility with VisibilityTimeout=0 seconds.
If you request to change the visibility timeout for a message before the message has been received, instead of changing the visibility timeout to your requested value, the message immediately becomes invisible (it is locked) for the duration of the timeout you've requested. No consuming components of your system can receive the message during that period.
For example, if you call ChangeMessageVisibility with VisibilityTimeout = 3600 seconds, that message will be hidden from consuming components of your system for one hour. However, once the message lock expires and the message is received, the visibility timeout used for the message will be the overall value assigned to the queue and not the 3600 seconds you previously set.
The table below lists the API actions discussed in this section.
| To do this... | Use this action for Query or SOAP | Use this action for REST |
|---|---|---|
|
Setting the visibility timeout for a queue | ||
|
Getting the visibility timeout for a queue | ||
|
Peeking in on a message | ||
|
Extending or terminating a message's visibility timeout, or locking a message |
Currently not supported. Use the Query action. |
