Implementation Principles of RocketMQ Scheduled/Delayed Messages and Extending to Arbitrary Time Precision

Scheduled and delayed messages are widely used in business development for scenarios such as distributed task scheduling and order timeout handling, where a message must become consumable only after a specified interval.

RocketMQ provides an advanced message type that becomes visible to consumers after a configured delay. Prior to version 5.0, RocketMQ supports only 18 fixed delay levels (e.g., "1s 5s 10s 30s 1m 2m ... 2h").

private String messageDelayLevel = "1s 5s 10s 30s 1m 2m 3m 4m 5m 6m 7m 8m 9m 10m 20m 30m 1h 2h";

The message flow is as follows: the producer sends a message to a broker based on topic routing information; the broker stores the message in a CommitLog file rather than directly in a queue; the DefaultMessageStore runs a background thread that periodically reads the CommitLog, indexes it, and writes entries to consumer‑visible queues.

private ReputMessageService reputMessageService;

this.reputMessageService.start();

org.apache.rocketmq.store.DefaultMessageStore.ReputMessageService#run

When a message is identified as delayed, RocketMQ rewrites its topic to SCHEDULE_TOPIC_XXXX and routes it to the corresponding delay queue before persisting it to the CommitLog.

Implementation steps:

1. The producer sets the delay level on the Message object, e.g., Message#setDelayTimeLevel , Message#setDelayTimeSec , Message#setDelayTimeMs , or Message#setDeliverTimeMs .

org.apache.rocketmq.common.message.Message#setDelayTimeLevel

org.apache.rocketmq.common.message.Message#setDelayTimeSec

org.apache.rocketmq.common.message.Message#setDelayTimeMs

org.apache.rocketmq.common.message.Message#setDeliverTimeMs

2. DefaultMessageStore rewrites the message’s topic and queue information before writing it to the CommitLog.

3. A background thread in DefaultMessageStore reads the CommitLog and writes delayed messages into the 18 queues of SCHEDULE_TOPIC_XXXX .

4. The broker creates a ScheduleMessageService ; each delay queue has a scheduled task that, when the delay expires, re‑sends the message to its original topic, making it visible to consumers.

To break the limitation of the fixed 18 delay levels, developers can store delayed messages in a third‑party store such as RocksDB, poll them, and re‑inject them into RocketMQ. An open‑source example is DDMQ from DiDi.

Reference implementation: DDMQ MqPushService

public static final String RMQ_SYS_SCHEDULE_TOPIC = "SCHEDULE_TOPIC_XXXX";

In summary, RocketMQ’s scheduled/delayed message mechanism is built on a fixed set of delay levels, but it can be extended with RocksDB or similar storage to achieve arbitrary time precision for delayed delivery.