Skip to main content

​
Overview

The QueuesClient is the Room API for simple room-scoped work queues. Use it when one participant or service needs to hand off JSON work items to another participant or service asynchronously.

​
Why use the Queues API?

  • Decouple producers and consumers when work should happen later.
  • Build lightweight background workflows without adding another queueing system.
  • Coordinate multi-agent jobs where one participant produces work and another consumes it.

​
How it works

A queue stores JSON messages until a consumer receives them. Senders and receivers can be different participants or services in the same room. SDKs can list, open, send, receive, drain, and close queues, while Python auto-creates queues during send or receive when create=True.

​
Permissions and grants

If a deployed service needs to use room queues, its participant token needs the appropriate queue-related Room API grants. These grants can be scoped to list/send/receive capabilities. See API Scopes and Packaging and Deploying Services.

​
CLI and SDK availability

  • CLI: send and receive messages, and inspect queue sizes, with meshagent room queue ....
  • SDKs: helper methods cover list, open, send, receive, drain, and close, with the Python open difference noted below.

​
API Methods

Below is an example of how you might use the QueuesClient in your code: 
meshagent room queue send \
  --room myroom \
  --queue my-queue \
  --json '{"payload":"Hello World!"}'

meshagent room queue receive \
  --room myroom \
  --queue my-queue

meshagent room queue size \
  --room myroom \
  --queue my-queue

​
Queue

A basic representation of a queue, holding a name and its current size. 
queue = Queue(name="my-queue", size=0)
  • name: string
    The name of the queue.
  • size: number
    The size (or length) of the queue at the time of retrieval.

​
QueuesClient

The QueuesClient is responsible for sending requests through a RoomClient to perform various operations on queues.
  • room: RoomClient
    An instance of RoomClient, which handles the low-level communication with the server or service.

​
list()

queues = await room.queues.list()
  • Returns
    An array of Queue objects containing the name and size of each queue found on the server.

​
open(name)

# Not available in Python (queues are auto-created via send/receive)
  • Parameters:
    • name – The name of the queue to open.
  • Description
    Creates (or reopens) the queue if it is not present. If the queue already exists and is open, the server will reject a duplicate open request.

​
drain(name)

await room.queues.drain(name="my-queue")
  • Parameters:
    • name – The name of the queue to drain.
  • Description
    Removes all messages from the specified queue, effectively resetting its size to zero.

​
close(name)

await room.queues.close(name="my-queue")
  • Parameters:
    • name – The name of the queue to close.
  • Description
    Closes the specified queue so that no further messages can be sent or received until it is reopened.

​
send(name, message, create)

meshagent room queue send \
  --room myroom \
  --queue my-queue \
  --json '{"foo":"bar"}'
  • Parameters:
    • name – The name of the queue to send a message to.
    • message – A JSON-serializable object containing the data you want to send.
    • create – (Optional) Whether to create the queue if it does not exist. Defaults to true.
  • Description
    Sends a message to the specified queue. If create is true, the queue will be created automatically if it doesn’t exist.

​
receive(name, create, wait)

meshagent room queue receive \
  --room myroom \
  --queue my-queue
  • Parameters:
    • name – The name of the queue to receive a message from.
    • create – (Optional) Whether to create the queue if it does not exist. Defaults to true.
    • wait – (Optional) Whether to wait (block) until a message is available. Defaults to true. Behavior may vary based on server-side configuration.
  • Returns
    A JSON-serializable object if a message is received, or null if the queue was empty (represented by an EmptyChunk).
  • Description
    Tries to receive one message from the specified queue. With wait=True, the call blocks until a message arrives. With wait=False, it returns immediately: null if empty or the next message if available.

​
Additional Notes

  • Error Handling
    When a request fails or the server returns an error response, the underlying RoomClient may throw errors. Make sure to wrap calls in try/catch if you need to handle them gracefully.
  • Concurrency and Performance
    • For high-throughput scenarios, ensure that your server and RoomClient configuration is optimized for concurrency.
    • The receive method’s wait parameter may affect your application’s design. If wait is true, the call might block until a message is available (depending on the server’s capabilities).
  • Extensibility
    You can add additional queue-related functionality (e.g., message peek, dead-letter queues, etc.) by extending QueuesClient or creating related classes that also use RoomClient.
  • SDK availability
    The server supports queues.open, but the Python SDK doesn’t expose an open helper today—queues are auto-created when create=True on send/receive. JS/TS/Dart/.NET expose open.