Skip to main content

Queue

The cloud.Queue resource represents a data structure for holding a list of messages. Queues are typically used to decouple producers of data and the consumers of said data in distributed systems. Queues by default are not FIFO (first in, first out) - so the order of messages is not guaranteed.

Usage

Setting a Queue Consumer

bring cloud;

let q = new cloud.Queue();

q.setConsumer(inflight (m: str) => {
log("message ${m} consumed");
});

new cloud.Function(inflight () => {
q.push("message a");
q.push("message b");
});

Using Queue inflight api

Pushing messages, popping them, and purging.

bring cloud;

let q = new cloud.Queue();

new cloud.Function(inflight () => {
q.push("message a");
q.push("message b", "message c", "message d");
log("approxSize is ${q.approxSize()}");
log("popping message ${q.pop()}");
log("popping message ${q.pop()}");
log("approxSize is ${q.approxSize()}");
q.purge();
log("approxSize is ${q.approxSize()}");
});

Adding a dead-letter queue

Creating a queue and adding a dead-letter queue with the maximum number of attempts configured

bring cloud;

let dlq = new cloud.Queue() as "dead-letter queue";
let q = new cloud.Queue(
dlq: {
queue: dlq,
maxDeliveryAttempts: 2
}
);

Referencing an external queue

If you would like to reference an existing queue from within your application you can use the QueueRef classes in the target-specific namespaces.

This is currently only supported for aws.

The following example defines a reference to an Amazon SQS queue with a specific ARN and sends a message to the queue from the function:

bring aws;

let outbox = new aws.QueueRef("arn:aws:sqs:us-east-1:111111111111:Outbox");

new cloud.Function(inflight () => {
outbox.push("send an email");
});

This works both when running in the simulator (requires AWS credentials on the developer's machine) and when deployed to AWS. When this is deployed to AWS, the AWS Lambda IAM policy will include the needed permissions.

Target-specific details

Simulator (sim)

The sim implementation of cloud.Queue uses JavaScript's Array

AWS (tf-aws and awscdk)

The AWS implementation of cloud.Queue uses Amazon Simple Queue Service.

Azure (tf-azure)

🚧 Not supported yet (tracking issue: #617)

GCP (tf-gcp)

🚧 Not supported yet (tracking issue: #616)

API Reference

Queue

A queue.

Initializers

bring cloud;

new cloud.Queue(props?: QueueProps);
NameTypeDescription
propsQueuePropsNo description.

propsOptional

Methods

Preflight Methods
NameDescription
setConsumerCreate a function to consume messages from this queue.
Inflight Methods
NameDescription
approxSizeRetrieve the approximate number of messages in the queue.
popPop a message from the queue.
purgePurge all of the messages in the queue.
pushPush one or more messages to the queue.

setConsumer
setConsumer(handler: IQueueSetConsumerHandler, props?: QueueSetConsumerOptions): Function

Create a function to consume messages from this queue.

handlerRequired

propsOptional

approxSize
inflight approxSize(): num

Retrieve the approximate number of messages in the queue.

pop
inflight pop(): str?

Pop a message from the queue.

purge
inflight purge(): void

Purge all of the messages in the queue.

push
inflight push(...messages: Array<str>): void

Push one or more messages to the queue.

messagesRequired
  • Type: str

Payload to send to the queue.

Each message must be non-empty.


Static Functions

NameDescription
onLiftTypeA hook called by the Wing compiler once for each inflight host that needs to use this type inflight.
toInflightGenerates an asynchronous JavaScript statement which can be used to create an inflight client for a resource.

onLiftType
bring cloud;

cloud.Queue.onLiftType(host: IInflightHost, ops: MutArray<str>);

A hook called by the Wing compiler once for each inflight host that needs to use this type inflight.

The list of requested inflight methods needed by the inflight host are given by ops.

This method is commonly used for adding permissions, environment variables, or other capabilities to the inflight host.

hostRequired

opsRequired
  • Type: MutArray<str>

toInflight
bring cloud;

cloud.Queue.toInflight(obj: IResource);

Generates an asynchronous JavaScript statement which can be used to create an inflight client for a resource.

NOTE: This statement must be executed within an async context.

objRequired

Properties

NameTypeDescription
nodeconstructs.NodeThe tree node.

nodeRequired
node: Node;
  • Type: constructs.Node

The tree node.


Structs

DeadLetterQueueProps

Dead letter queue options.

Initializer

bring cloud;

let DeadLetterQueueProps = cloud.DeadLetterQueueProps{ ... };

Properties

NameTypeDescription
queueQueueQueue to receive messages that failed processing.
maxDeliveryAttemptsnumNumber of times a message will be processed before being sent to the dead-letter queue.

queueRequired
queue: Queue;

Queue to receive messages that failed processing.


maxDeliveryAttemptsOptional
maxDeliveryAttempts: num;
  • Type: num
  • Default: 1

Number of times a message will be processed before being sent to the dead-letter queue.


QueueProps

Options for Queue.

Initializer

bring cloud;

let QueueProps = cloud.QueueProps{ ... };

Properties

NameTypeDescription
dlqDeadLetterQueuePropsA dead-letter queue.
retentionPerioddurationHow long a queue retains a message.
timeoutdurationHow long a queue's consumers have to process a message.

dlqOptional
dlq: DeadLetterQueueProps;

A dead-letter queue.


retentionPeriodOptional
retentionPeriod: duration;

How long a queue retains a message.


timeoutOptional
timeout: duration;

How long a queue's consumers have to process a message.


QueueSetConsumerOptions

Options for Queue.setConsumer.

Initializer

bring cloud;

let QueueSetConsumerOptions = cloud.QueueSetConsumerOptions{ ... };

Properties

NameTypeDescription
concurrencynumThe maximum concurrent invocations that can run at one time.
envMutMap<str>Environment variables to pass to the function.
logRetentionDaysnumSpecifies the number of days that function logs will be kept.
memorynumThe amount of memory to allocate to the function, in MB.
timeoutdurationThe maximum amount of time the function can run.
batchSizenumThe maximum number of messages to send to subscribers at once.

concurrencyOptional
concurrency: num;
  • Type: num
  • Default: platform specific limits (100 on the simulator)

The maximum concurrent invocations that can run at one time.


envOptional
env: MutMap<str>;
  • Type: MutMap<str>
  • Default: No environment variables.

Environment variables to pass to the function.


logRetentionDaysOptional
logRetentionDays: num;
  • Type: num
  • Default: 30

Specifies the number of days that function logs will be kept.

Setting negative value means logs will not expire.


memoryOptional
memory: num;
  • Type: num
  • Default: 1024

The amount of memory to allocate to the function, in MB.


timeoutOptional
timeout: duration;

The maximum amount of time the function can run.


batchSizeOptional
batchSize: num;
  • Type: num
  • Default: 1

The maximum number of messages to send to subscribers at once.


Protocols

IQueueSetConsumerHandler

Inflight client: @winglang/sdk.cloud.IQueueSetConsumerHandlerClient

A resource with an inflight "handle" method that can be passed to Queue.setConsumer.

IQueueSetConsumerHandlerClient

Inflight client for IQueueSetConsumerHandler.

Methods

NameDescription
handleFunction that will be called when a message is received from the queue.

handle
inflight handle(message: str): void

Function that will be called when a message is received from the queue.

messageRequired
  • Type: str