2. Usage

2.1 Production

Use the deliverAt method to specify an absolute timestamp, and use deliverAfter to specify a relative time, as shown in the following example code:

Producer<String> producer = client.newProducer(Schema.STRING)
        .topic("public/default/delayed-test").create();

// message to be delivered at the configured delay interval
producer.newMessage().deliverAfter(10, TimeUnit.SECONDS).value(sdf.format(new Date())).send();

// message to be delivered at the configure time
producer.newMessage().deliverAt(System.currentTimeMillis() + TimeUnit.SECONDS.toMillis(10)).send();

2.2 Consumption

Consumers of delayed messages can only use shared and key-shared subscription types. If the consumer uses exclusive or failover subscription modes, the broker will still immediately distribute the delayed messages, ignoring the delay time.

You may wonder why exclusive and failover subscription modes do not support delayed messages. Perhaps it's because these two subscription modes guarantee message order, and delayed messages would break this order. By the way, modifying this code is also quite difficult. For specific discussion, please see:

[fix][client] fix retry topic with exclusive mode. by thetumbled · Pull Request #23859 · apache/pulsarGitHub

2.3 Message Order

When using delayed messages, it is destined to be unable to guarantee strict order, as shown in the following diagram:

2.4 Time Precision and Duration

Precision

The default precision is 1s.

The delayedDeliveryTickTimeMillis configuration affects the precision of delayed delivery time. The scheduled task of the delay queue module checks every 1s whether the message has expired, so the default precision is 1s.

Although users can change this configuration to 1ms, it still cannot guarantee that the deviation between the message delivery time and the specified delay time is within 1ms precision. After all, Pulsar's end-to-end P99 latency only reaches a few milliseconds, and there are also special cases such as topic unload that can cause message reload time.

If millisecond level delay precision is required, you can implement an solution in client side. For example, if you need messages to be delayed by 1 day but with 10ms precision, you can use Pulsar's delay queue specifying a message delay of 23h59min59s, so that the message can be guaranteed to reach the consumer 1s before the target time, and high-precision delayed messages can be achieved through a loop wait on the client side.

Duration

Theoretically, there is no limit on the delay time duration, such as 7 days, one month, or even one year. However, due to Pulsar's TTL and other mechanisms, if the delay time exceeds the message retention time, it will be cleaned up, and the message cannot be read to distribute to consumers after the delay time is reached. Therefore, users must ensure that the delay time is less than the retention time, otherwise messages will be lost.

There are also some common questions:

• Can scheduled messages be withdrawn or have their scheduled time modified before the scheduled time arrives?

Not supported.

• What happens if a scheduled time is set to a time that has already passed?

The message will be delivered immediately.