Queue

​

Overview

• List queues with their current size.
• Open/create queues (or auto-create via send/receive when create=True).
• Send messages, receive messages (optionally waiting), and drain/close queues.

​

API Methods

# List existing Queues
queues = await room.queues.list()
print("Queues:", queues)

# Send a messages
await room.queues.send("my-queue", {"payload": "Hello World!"})

# Receive a message
message = await room.queues.receive("my-queue")
print("Received message:", message)

# Drain a queue
await room.queues.drain("my-queue")

# Close the queue
await room.queues.close("my-queue")

​

Queue

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

• 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("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("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)

await room.queues.send("my-queue", {"foo": "bar"}, create=True)

• 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)

message = await room.queues.receive("my-queue", create=True, wait=True)

• 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 EmptyResponse).
• 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.