tencent cloud

TDMQ for Apache Pulsar

Release Notes and Announcements
Release Notes
Cluster Version Updates
Product Announcements
Product Introduction
Introduction and Selection of the TDMQ Product Series
What Is TDMQ for Apache Pulsar
Strengths
Scenarios
How It Works
Product Series
Version Support Instructions for Open-Source Apache Pulsar
Comparison with Open-Source Apache Pulsar
High Availability
Quotas and Limits
Basic Concepts
Billing
Billing Overview
Pricing
Billing Examples
Renewal
Viewing Consumption Details
Overdue Payments
Refund
Getting Started
Getting Started Guide
Preparations
Using the SDK to Send and Receive General Messages
Using the SDK to Send and Receive Advanced Feature Messages
User Guide
Usage Process Guide
Configuring the Account Permission
Creating a Cluster
Configuring the Namespace
Configuring the Topic
Connecting to a Cluster
Managing the Cluster
Querying Messages and Traces
Cross-Region Replication
Viewing Monitoring Data and Configuring Alarm Rules
Use Cases
Client Usage
Abnormal Consumer Isolation
Traffic Throttling Mechanisms
Transaction Reconciliation
Message Idempotence
Message Compression
Migration Guide
Single-Write Multiple-Read Cluster Migration Solutions
Hitless Migration from Virtual Cluster to Pro Cluster
SDK Reference
API Overview
SDK Reference
SDK Overview
Recommended SDK Configuration Parameters
TCP Protocol (Apache Pulsar)
Security and Compliance
Permission Management
Deletion Protection
CloudAudit
FAQs
Monitoring
Clients
Agreements
Service Level Agreement
TDMQ Policy
Contact Us
Glossary

Scheduled Message and Delayed Message

PDF
Focus Mode
Font Size
Last updated: 2025-12-24 15:03:03

Relevant Concepts

Scheduled messages: After a message is sent to the server, the business does not want the consumer to receive this message immediately, but rather at a later specified time. Messages of this type are collectively called scheduled messages.
Delayed messages: After a message is sent to the server, the business does not want the consumer to receive this message immediately, but rather after a specific period of time. Messages of this type are collectively called delayed messages.
In fact, scheduled messages can be seen as a special usage of delayed messages, and their ultimate implementation effects are the same.

Scenarios

If the system is a monolithic architecture, implementing delay through business code or using third-party components makes little difference. However, if the architecture is complex, forming a large-scale distributed system with dozens or even hundreds of microservices, implementing the scheduled logic within the application can lead to various issues. Once a node running the delay program encounters a problem, the entire delay logic will be affected.
To address these issues, the delayed messages feature can be used to deliver messages to a message queue. It is a good solution for unified calculation of the delayed time, and the retry and dead letter mechanisms ensure that messages are not lost.
The examples in specific scenarios are as follows:
After a WeChat red packet is sent, the producer sends a message delayed by 24 hours. When the consumer program receives the message after 24 hours, it checks whether the user has claimed the red packet. If not, it returns the red packet to the original account.
After an order is placed for a certain item on a mini-program, the backend stores a message delayed by 30 minutes. When the consumer receives the message after the specified time, a check on the payment status is triggered. If payment has not been made, the order is canceled, implementing the logic of canceling orders if payment is not completed within 30 minutes.
After a user sets a message as a to-do item on WeChat, the user can also send a scheduled message. The server actively consumes this scheduled message to remind the user of the to-do item.

Usage Method

The TDMQ for Apache Pulsar SDK provides dedicated APIs to implement scheduled messages and delayed messages.
For scheduled messages, you need to provide the moment when the messages should be sent.
For delayed messages, you need to provide a time period as the delayed duration.

Scheduled Messages

Scheduled messages are implemented using the deliverAt() method of the producer. Sample code is as follows:
String value = "message content";
try {
//It is necessary to explicitly convert the desired time to a timestamp.
long timeStamp = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss").parse("2020-11-11 00:00:00").getTime();
//Call the deliverAt method of the producer to implement scheduled messages.
MessageId msgId = producer.newMessage()
.value(value.getBytes())
.deliverAt(timeStamp)
.send();
} catch (ParseException e) {
//To-do: Add a method to handle timestamp parsing failures.
e.printStackTrace();
}
Note
The time range for scheduled messages is calculated from the current time, allowing for any moment within the next 864,000 seconds (10 days). For example, if it starts at 12:00 on October 1st, it can be scheduled for up to 12:00 on October 11th.
Scheduled messages cannot be sent in batch mode. Set the enableBatch parameter to false when you create the producer.
Scheduled messages can only be consumed in Shared mode (excluding the Key-Shared mode). Otherwise, the scheduled effect is lost.

Delayed Messages

Delayed messages are implemented using the deliverAfter() method of the producer. Sample code is as follows:
String value = "message content";

//You need to specify the delayed duration.
long delayTime = 10L;
//Call the deliverAfter method of the producer to implement scheduled messages.
MessageId msgId = producer.newMessage()
.value(value.getBytes())
.deliverAfter(delayTime, TimeUnit.SECONDS) //The unit can be selected freely.
.send();
Note
The duration range for delayed messages is from 0 to 864,000 seconds (0 seconds to 10 days). For example, if it starts at 12:00 on October 1, it can be delayed for a maximum of 864,000 seconds.
When a message is delayed for more than 10 days in the Go SDK, duplicate messages may occur.
Delayed messages cannot be sent in batch mode. Set the enableBatching parameter to false when you create the producer.
Delayed messages can only be consumed in Shared mode (excluding the Key-Shared mode). Otherwise, the delayed effect is lost.

Usage Instructions and Limitations

It is recommended that a topic different from that used for general messages be used to manage scheduled messages or delayed messages. That is, scheduled and delayed messages are sent to a fixed topic, and general messages are sent to another topic. This facilitates subsequent management and maintenance and increases stability.
When you use scheduled and delayed messages, ensure that the clocks on the clients and servers are the same (all regions use UTC+8) to avoid time differences.
Scheduled and delayed messages have a time deviation of approximately 1 second.
Scheduled and delayed messages do not support the batch mode (batch sending). Batch sending may lead to a message backlog. As a precaution, set the enableBatching parameter to false when you create the producer.
Scheduled and delayed messages can only be consumed in Shared mode (excluding the Key-Shared mode). Otherwise, the scheduled or delayed effect is lost.
The maximum time range for scheduled and delayed messages is 10 days.
For scheduled messages, the scheduled time should be a future time. If it is earlier than the current time, the messages are delivered to consumers immediately.
After a scheduled time is set, the Time to Live (TTL), the maximum message retention time, is still calculated from the time when a message is sent. For example, if a message is scheduled to be sent in 2 days, and the TTL of the message is set to 1 day, the message is deleted after 1 day. Therefore, ensure that the TTL is greater than the scheduled time. That is, the TTL is set to be greater than or equal to 2 days. Otherwise, the message is deleted when the TTL expires. The same applies to delayed messages.
Standard topics support sending and receiving scheduled/delayed messages. You can send scheduled/delayed messages by calling the APIs in Usage Method.

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback