KubeMQ
Client SDKsPythonHow-to guidesQueues

Delay Policy

Field-level reference for delay_in_seconds, the QueueMessage field that configures delivery delay in the Python SDK.

Which to use

For the task-oriented how-to, see Delayed Messages. This page focuses on the delay_in_seconds delay-policy field itself — its evaluation point and interaction with redelivery.

Overview

delay_in_seconds is the field on QueueMessage that defers when a queued message becomes visible to consumers — set it before sending, and the broker excludes the message from delivery until the countdown expires. It starts the moment the broker accepts the message, not when the client sends it, and is evaluated once, at send time.

Gotchas: the delay is a floor, not a guarantee — the message becomes eligible when the timer expires, but actual delivery still waits for a consumer to poll, so don't rely on it for precise scheduling. It's one-shot: there's no recurrence or cron-like behavior, so long or repeating delays need application logic on top. And it's independent of redelivery — a delayed message that's later nacked or times out after delivery follows normal visibility-timeout/retry rules, not the original send-time delay.

Prerequisites

  • KubeMQ server running on localhost:50000
  • Python SDK installed (pip install kubemq)

Code

delay_policy.py
"""Example: Delay policy — send a message with a delivery delay."""

from __future__ import annotations

import asyncio

from kubemq import AsyncQueuesClient
from kubemq import QueueMessage


async def main() -> None:
    async with AsyncQueuesClient(
        address="localhost:50000",
        client_id="python-queues-stream-delay-policy-client",
    ) as client:
        # Send a message with a 5-second delay
        result = await client.send_queue_message(
            QueueMessage(
                channel="python-queues-stream.delay-policy",
                body=b"delayed message",
                delay_in_seconds=5,
            )
        )
        print(f"Sent message with 5s delay: {result}")

        # Try to receive immediately — should get nothing
        response = await client.receive_queue_messages(
            channel="python-queues-stream.delay-policy",
            max_messages=1,
            wait_timeout_seconds=1,
            auto_ack=True,
        )
        print(f"Immediate: {len(response.messages)} messages (expected 0)")

        # Wait for the delay to expire
        print("Waiting 6 seconds for delay...")
        await asyncio.sleep(6)

        # Now the message should be available
        response = await client.receive_queue_messages(
            channel="python-queues-stream.delay-policy",
            max_messages=1,
            wait_timeout_seconds=5,
            auto_ack=True,
        )
        print(f"After delay: {len(response.messages)} messages (expected 1)")
        for msg in response.messages:
            print(f"  Received: {msg.body.decode('utf-8')}")


if __name__ == "__main__":
    asyncio.run(main())

How It Works

  • QueueMessage.delay_in_seconds=5 instructs the broker to hold the message for 5 seconds before making it visible to consumers.
  • The first poll with wait_timeout_seconds=1 returns zero messages, confirming the delay is in effect.
  • After a 6-second sleep the delay window has elapsed; the second poll successfully retrieves the delayed message with auto_ack=True.
  • Delay policy applies to individual messages at send time; it is independent of channel-level configuration.

Was this page helpful?

Dead Letter Queue

Route failed KubeMQ queue messages to a dead-letter queue using the Python SDK for safe handling.

Delayed Messages

Send KubeMQ queue messages with a delivery delay using the Python SDK to schedule future delivery.

On this page

OverviewPrerequisitesCodeHow It WorksRelated