Queues are distributed, FIFO data structures for coordinating work across Modal Functions and external processes.
Creating queues
FromName
References a Queue by its name, optionally creating it if it doesn’t exist.
queue, err := mc.Queues.FromName(ctx, "my-queue", &modal.QueueFromNameParams{
CreateIfMissing: true,
})
if err != nil {
// Handle error
}
Context for the operation
Optional parametersEnvironment name. Defaults to client’s environment.
If true, creates the Queue if it doesn’t exist. Defaults to false.
*Queue - The Queue instanceerror - NotFoundError if the Queue doesn’t exist and CreateIfMissing is false
Ephemeral
Creates a temporary, nameless Queue that persists until CloseEphemeral() is called.
queue, err := mc.Queues.Ephemeral(ctx, nil)
if err != nil {
// Handle error
}
defer queue.CloseEphemeral()
Context for the operation
*Queue - The ephemeral Queue instanceerror - Error if creation fails
Queue methods
Put
Adds a single item to the end of the Queue.
err := queue.Put(ctx, "Hello, Queue!", &modal.QueuePutParams{
Partition: "partition-1",
})
if err != nil {
// Handle error
}
Context for the operation
The item to add (will be serialized with pickle)
Optional parametersMaximum wait time if Queue is full. nil = wait indefinitely.
Partition key (1-64 bytes). Empty string uses default partition.
Time-to-live for the partition. Defaults to 24 hours.
error - QueueFullError if the Queue is full after timeout
PutMany
Adds multiple items to the end of the Queue.
err := queue.PutMany(ctx, []any{"item1", "item2", "item3"}, nil)
if err != nil {
// Handle error
}
Context for the operation
error - QueueFullError if the Queue is full after timeout
Get
Removes and returns one item from the Queue.
item, err := queue.Get(ctx, &modal.QueueGetParams{
Timeout: ptr(5 * time.Second),
Partition: "partition-1",
})
if err != nil {
// Handle QueueEmptyError
}
fmt.Printf("Item: %v\n", item)
Context for the operation
Optional parametersMaximum wait time for an item. nil = wait indefinitely.
Partition key to get from
any - The dequeued itemerror - QueueEmptyError if no items available within timeout
GetMany
Removes and returns up to n items from the Queue.
items, err := queue.GetMany(ctx, 10, &modal.QueueGetManyParams{
QueueGetParams: modal.QueueGetParams{
Timeout: ptr(5 * time.Second),
},
})
if err != nil {
// Handle error
}
fmt.Printf("Got %d items\n", len(items))
Context for the operation
Maximum number of items to retrieve
[]any - The dequeued items (may be fewer than n)error - QueueEmptyError if no items available within timeout
Len
Returns the number of items in the Queue.
length, err := queue.Len(ctx, &modal.QueueLenParams{
Partition: "partition-1",
})
if err != nil {
// Handle error
}
fmt.Printf("Queue length: %d\n", length)
Context for the operation
Optional parametersPartition to check. Empty for default partition.
If true, returns total across all partitions (mutually exclusive with Partition)
int - The number of itemserror - Error if the request fails
Clear
Removes all items from a Queue partition.
err := queue.Clear(ctx, &modal.QueueClearParams{
Partition: "partition-1",
})
if err != nil {
// Handle error
}
Context for the operation
Optional parametersPartition to clear. Empty for default partition.
If true, clears all partitions (mutually exclusive with Partition)
error - Error if the operation fails
Iterate
Yields items from the Queue until it is empty.
for item, err := range queue.Iterate(ctx, &modal.QueueIterateParams{
ItemPollTimeout: 10 * time.Second,
}) {
if err != nil {
// Handle error
break
}
fmt.Printf("Item: %v\n", item)
}
Context for the operation
Optional parametersExit iteration if no new items appear within this timeout
Partition to iterate over
iter.Seq2[any, error] - Iterator over Queue items
CloseEphemeral
Deletes an ephemeral Queue.
This method panics if called on a non-ephemeral Queue.
Managing queues
Delete
Deletes a named Queue.
err := mc.Queues.Delete(ctx, "my-queue", &modal.QueueDeleteParams{
AllowMissing: false,
})
if err != nil {
// Handle error
}
Context for the operation
The name of the Queue to delete
Optional parametersIf true, don’t error if the Queue doesn’t exist
error - Error if deletion fails
Deletion is irreversible and will affect any Apps currently using the Queue.
Queue type
The unique identifier for the Queue
The name of the Queue (empty for ephemeral Queues)
Example usage
package main
import (
"context"
"fmt"
"time"
"github.com/modal-labs/modal-client/go"
)
func main() {
ctx := context.Background()
mc, _ := modal.NewClient()
defer mc.Close()
// Create a Queue
queue, err := mc.Queues.FromName(ctx, "my-queue", &modal.QueueFromNameParams{
CreateIfMissing: true,
})
if err != nil {
panic(err)
}
// Put items
queue.Put(ctx, "task-1", nil)
queue.Put(ctx, "task-2", nil)
queue.PutMany(ctx, []any{"task-3", "task-4", "task-5"}, nil)
// Check length
length, _ := queue.Len(ctx, nil)
fmt.Printf("Queue has %d items\n", length)
// Get items
timeout := 5 * time.Second
item, err := queue.Get(ctx, &modal.QueueGetParams{
Timeout: &timeout,
})
if err != nil {
fmt.Printf("Queue empty: %v\n", err)
} else {
fmt.Printf("Got item: %v\n", item)
}
// Get multiple items
items, _ := queue.GetMany(ctx, 10, nil)
fmt.Printf("Got %d items\n", len(items))
// Iterate over items
for item, err := range queue.Iterate(ctx, nil) {
if err != nil {
break
}
fmt.Printf("Processing: %v\n", item)
}
// Use partitions
queue.Put(ctx, "data-1", &modal.QueuePutParams{
Partition: "batch-1",
})
item2, _ := queue.Get(ctx, &modal.QueueGetParams{
Partition: "batch-1",
})
fmt.Printf("From partition: %v\n", item2)
}