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 cloud;
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
props
QueueProps
No description.
propsOptional ​

Methods ​

Preflight Methods​
NameDescription
setConsumer
Create a function to consume messages from this queue.
Inflight Methods​
NameDescription
approxSize
Retrieve the approximate number of messages in the queue.
pop
Pop a message from the queue.
purge
Purge all of the messages in the queue.
push
Push 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
onLiftType
A hook called by the Wing compiler once for each inflight host that needs to use this type inflight.
toInflight
Generates 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
node
constructs.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
queue
Queue
Queue to receive messages that failed processing.
maxDeliveryAttempts
numNumber 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
dlq
DeadLetterQueueProps
A dead-letter queue.
retentionPeriod
duration
How long a queue retains a message.
timeout
duration
How 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
concurrency
numThe maximum concurrent invocations that can run at one time.
env
MutMap<str>Environment variables to pass to the function.
logRetentionDays
numSpecifies the number of days that function logs will be kept.
memory
numThe amount of memory to allocate to the function, in MB.
timeout
duration
The maximum amount of time the function can run.
batchSize
numThe 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
handle
Function 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