A queue is the transmission channel for a message. Developers create and use different queues to transmit messages of different logical types. All queues created by developers are located in their own namespace. A queue has several attributes. Developers can set these attributes to better suit different message transmission requirements. Developers can also add user-defined attributes for the queue and save related information, such as the description of the queue. The developer can share the data in the queue with other developers by setting the ACL. The developer can query the approximate number of messages in various states in the queue through the SDK interface at any time to understand the operating status of the queue.
The developer implements the transmission of a queue message through the send/receive operation. Each message contains a string type message body and can set its own attributes. If the developer does not set the message attributes, the corresponding attributes in the queue is used by default. In addition, messages can also be supplied with user-defined attributes of String or byte [] type.
If sender succeeds in a send message to queue, EMQ will return a unique id for each successful message, which is the identity of this Queue.
Each successfully received message, in addition to the message body and message id, will also contain a globally unique receipt handle. After the receiver has correctly handled this message, you need to use receipt handle to delete this message from the queue. Otherwise, this message will become visible again after a certain period of time and will be received again by receiver. If this happens, the receipt handle of the received message will be different from the previous one.
After a message in the queue is received by the receiver, it will become invisible for a period of time and wait for receiver's deletion confirmation. This time is called Invisibility Time. If EMQ has not received a confirmation of deletion during this time, this message will become visible again and will eventually be received by receiver again. If the receiver receiving the message finds that the processing of the message cannot be completed during this time, the Invisibility Time can be extended through the SDK; the extended time starts from when the server receives the extension request. If the receiver is not willing to handle this message, the Invisibility Time can be set to 0 via the SDK, making the message immediately visible and eventually read again.
When the Invisibility Time expires, the corresponding receiverHandle becomes invalid. In order to simplify the user's program logic, EMQ will not throw an exception when using a failed receiptHandle to delete the message, etc., but it does not guarantee the result of the related operation.
Developers sometimes need to use deferred queues, which can be done by setting the delay time of the queue or message. When the delay time is greater than 0, the message entering the queue cannot be read immediately by the receiver. Only after the delay time the message become visible and finally read.
By default, after EMQ receives a receive request, it will query a part of the distributed system and immediately return this part of the query to receiver. If there is no message in the part being queried, it will return no message. If the receiver wants to reduce the empty response, the Wait Time of the receive operation can be set to a value greater than 0 through the SDK, namely Long Polling. In this way, EMQ will block receive request and query the entire distributed system. When some messages are got in the queue, it will immediately return to receiver. If there is no visible message in the queue, EMQ will return no messages to the user after the Wait Time expires.
In order to reduce the number of network interactions and increase throughput, users can include multiple messages in one request, and use batch operations to send messages, delete messages, or change the visible time of messages. When using a batch operation, EMQ will return a list to identify if each message was processed successfully.
By default, the batch operation that sends a message has atomicity, that is, multiple messages sent, either succeeding or failing at the same time. Batch operations that delete messages and change the visible time of messages do not have atomicity and may partially succeed and partially fail.
So-called "multiple receivers" refers to a queue logic of multiple message receivers. Each receiver is completely independent and is to receive a full message in the queue.
For specific explanations and use of multiple receivers, refer to Tag-related Operations in this chapter.
Other queues (source queues) can send messages that have not been successfully processed for whatever reasons to the "dead-letter queue." The main benefit of using a dead-letter queue is to quarantine messages that cannot be processed successfully. In addition, the user can read out the message from the dead-letter queue and analyze why it failed to process successfully. For a detailed description of the dead-letter queue, please refer to the Dead Letter Queue section.