Mastering RocketMQ Timed Messages: Precise, Scalable Scheduling for Distributed Systems

Introduction

Apache RocketMQ has been refined for over a decade, serving 100% of Alibaba Group’s internal services and countless Alibaba Cloud customers. As a financially‑grade reliable messaging solution, RocketMQ focuses on asynchronous communication for business integration.

What Is a Timed Message?

In business messaging, a timed (or delay) message is sent by a producer but is not consumed until a specified future time. Unlike ordinary messages that become immediately available after being placed on a topic, timed messages are first stored in a system‑level topic and only moved to the user topic when the scheduled time arrives.

Why Use Timed Messages?

Distributed scheduling, task timeout handling, and similar scenarios require precise, reliable triggers that can scale horizontally. Traditional database‑based scheduling suffers from duplicate scans, inaccurate intervals, and poor horizontal scalability.

High‑throughput: supports massive event triggers without bottlenecks.

High reliability and retry: no loss of scheduled events.

Distributed scalability: works across multiple service instances.

Advantages of RocketMQ Timed Messages

RocketMQ’s timed messages simplify development logic, offering high precision, low entry barrier, and native horizontal scalability. They eliminate the need for business‑level deduplication and avoid the performance penalties of frequent database scans.

Use Case: Financial Payment Timeout

A typical scenario is an order system that must cancel an order if payment is not completed within 30 minutes. After a user places an order, the producer sends a timed message scheduled for 30 minutes later, using the order ID as the MessageKey. When the message is delivered, the consumer checks the order status and cancels the order if it remains unpaid.

Implementation Principle

TimerWheel Algorithm

RocketMQ uses a classic time‑wheel where each slot represents a second (or configurable interval). A pointer advances each tick, and messages are placed into the slot corresponding to their target time. If the desired delay exceeds one full rotation, the message remains in the same slot and is re‑evaluated on subsequent rotations.

TimerWheel & TimerLog

Each slot (a "tick") holds a linked list of TimerLog records. Important fields include firstPos, lastPos, and prevPos, which together form a chain of scheduled messages for that slot.

The workflow for a timed message consists of two phases: entering the time wheel and exiting it.

Enter phase : TimerEnqueueGetService pulls messages from the system timed topic into enqueuePutQueue. TimerEnqueuePutService creates a TimerLog entry and places it into the appropriate wheel slot.

Exit phase : TimerDequeueGetService rotates the wheel and moves all TimerLog records of the current slot to dequeueGetQueue. TimerDequeueGetMessageService reads the original message from the CommitLog. TimerDequeuePutMessageService checks whether the scheduled time has arrived; if so, it forwards the message to the user topic, otherwise it re‑queues it for the next rotation.

Practical Steps to Use Timed Messages

1. Create a topic of type "timed/delay" via the console or CLI.

2. When producing a message, set the desired delivery timestamp (or delay level) and optionally assign a MessageKey (e.g., order ID).

3. Consumers treat the delivered timed message exactly like a normal message; no special handling is required.

4. Avoid scheduling a massive number of messages for the exact same timestamp, as this can cause a sudden processing surge.

Conclusion

RocketMQ’s second‑level timed messages, powered by the TimerWheel and TimerLog mechanisms, provide a precise, scalable, and reliable way to implement distributed scheduling without the drawbacks of traditional database‑driven approaches.