modal.Queue

Distributed, FIFO queue for data flow in Modal apps.

The queue can contain any object serializable by cloudpickle, including Modal objects.

By default, the Queue object acts as a single FIFO queue which supports puts and gets (blocking and non-blocking).

Usage

For more examples, see the guide.

Queue partitions

Specifying partition keys gives access to other independent FIFO partitions within the same Queue object. Across any two partitions, puts and gets are completely independent. For example, a put in one partition does not affect a get in any other partition.

When no partition key is specified (by default), puts and gets will operate on a default partition. This default partition is also isolated from all other partitions. Please see the Usage section below for an example using partitions.

Lifetime of a queue and its partitions

By default, each partition is cleared 24 hours after the last put operation. A lower TTL can be specified by the partition_ttl argument in the put or put_many methods. Each partition’s expiry is handled independently.

As such, Queues are best used for communication between active functions and not relied on for persistent storage.

On app completion or after stopping an app any associated Queue objects are cleaned up. All its partitions will be cleared.

Limits

A single Queue can contain up to 100,000 partitions, each with up to 5,000 items. Each item can be up to 1 MiB.

Partition keys must be non-empty and must not exceed 64 bytes.

hydrate 

Synchronize the local object with its identity on the Modal server.

It is rarely necessary to call this method explicitly, as most operations will lazily hydrate when needed. The main use case is when you need to access object metadata, such as its ID.

Added in v0.72.39: This method replaces the deprecated .resolve() method.

objects 

Namespace with methods for managing named Queue objects.

create 

Create a new Queue object.

Examples:

Queues will be created in the active environment, or another one can be specified:

By default, an error will be raised if the Queue already exists, but passing allow_existing=True will make the creation attempt a no-op in this case.

Note that this method does not return a local instance of the Queue. You can use modal.Queue.from_name to perform a lookup after creation.

Added in v1.1.2.

list 

Return a list of hydrated Queue objects.

Examples:

Queues will be retreived from the active environment, or another one can be specified:

By default, all named Queues are returned, newest to oldest. It’s also possible to limit the number of results and to filter by creation date:

Added in v1.1.2.

delete 

Delete a named Queue.

Warning: This deletes an entire Queue, not just a specific entry or partition. Deletion is irreversible and will affect any Apps currently using the Queue.

Examples:

Queues will be deleted from the active environment, or another one can be specified:

Added in v1.1.2.

name 

validate_partition_key 

ephemeral 

Creates a new ephemeral queue within a context manager:

Usage:

from_name 

Reference a named Queue, creating if necessary.

This is a lazy method the defers hydrating the local object with metadata from Modal servers until the first time it is actually used.

from_id 

Construct a Queue from an id and look up the Queue metadata.

This is a lazy method that defers hydrating the local object with metadata from Modal servers until the first time it is actually used.

The ID of a Queue object can be accessed using .object_id.

Example:

info 

Return information about the Queue object.

clear 

Clear the contents of a single partition or all partitions.

Warning: this is a destructive operation and will irrevocably delete data.

Examples:

get 

Remove and return the next object in the queue.

If block is True (the default) and the queue is empty, get will wait indefinitely for an object, or until timeout if specified. Raises a native queue.Empty exception if the timeout is reached.

If block is False, get returns None immediately if the queue is empty. The timeout is ignored in this case.

get_many 

Remove and return up to n_values objects from the queue.

If there are fewer than n_values items in the queue, return all of them.

If block is True (the default) and the queue is empty, get will wait indefinitely for at least 1 object to be present, or until timeout if specified. Raises the stdlib’s queue.Empty exception if the timeout is reached.

If block is False, get returns None immediately if the queue is empty. The timeout is ignored in this case.

put 

Add an object to the end of the queue.

If block is True and the queue is full, this method will retry indefinitely or until timeout if specified. Raises the stdlib’s queue.Full exception if the timeout is reached. If blocking it is not recommended to omit the timeout, as the operation could wait indefinitely.

If block is False, this method raises queue.Full immediately if the queue is full. The timeout is ignored in this case.

put_many 

Add several objects to the end of the queue.

If block is True and the queue is full, this method will retry indefinitely or until timeout if specified. Raises the stdlib’s queue.Full exception if the timeout is reached. If blocking it is not recommended to omit the timeout, as the operation could wait indefinitely.

If block is False, this method raises queue.Full immediately if the queue is full. The timeout is ignored in this case.

len 

Return the number of objects in the queue partition.

iterate 

Iterate through items in the queue without mutation.

Specify item_poll_timeout to control how long the iterator should wait for the next time before giving up.