This page explains how to receive messages from Lite subscriptions. You can receive messages with the Pub/Sub Lite client library for Java.
Lite subscriptions connect Lite topics to subscriber applications; subscribers receive messages from Lite subscriptions. Subscribers receive every message that publisher applications send to the Lite topic, including the messages that publishers send before you create the Lite subscription.
Before receiving messages from a Lite subscription, create a Lite topic, create a Lite subscription to the Lite topic, and publish messages to the Lite topic.
Receiving messages
To receive messages from a Lite subscription, request messages from the Lite subscription. The client library automatically connects to the partitions in the Lite topic attached to the Lite subscription. If more than one subscriber client is instantiated, messages will be distributed across all clients. The number of partitions in the topic determines the maximum number of subscriber clients that can simultaneously connect to a subscription.
Subscribers might take up to one minute to initialize and start receiving messages. After initialization, messages are received with minimal latency.
The following sample shows you how to receive messages from Lite subscriptions:
gcloud
This command requires Python 3.6 or greater, and requires the grpcio Python package to be installed. For MacOS, Linux, and Cloud Shell users, run:
sudo pip3 install grpcio
export CLOUDSDK_PYTHON_SITEPACKAGES=1
To receive messages, use the gcloud pubsub lite-subscriptions subscribe command:
gcloud pubsub lite-subscriptions subscribe SUBSCRIPTION_ID \
--location=LITE_LOCATION \
--auto-ack
Replace the following:
- SUBSCRIPTION_ID: the ID of the Lite subscription
- LITE_LOCATION: the location of the Lite subscription
Go
Before running this sample, follow the Go setup instructions in Pub/Sub Lite Client Libraries.
Java
Before running this sample, follow the Java setup instructions in Pub/Sub Lite Client Libraries.
Python
Before running this sample, follow the Python setup instructions in Pub/Sub Lite Client Libraries.
The client library establishes bidirectional streaming connections to each of the partitions in the Lite topic.
The subscriber requests connections to the partitions.
The Pub/Sub Lite service delivers the messages to the subscriber.
After the subscriber processes the message, the subscriber must acknowledge the message. The client library asynchronously processes and acknowledges messages in a callback. To limit the number of unacknowledged messages the subscriber can store in memory, configure the flow control settings.
If multiple subscribers receive messages from the same Lite subscription, the Pub/Sub Lite service connects each subscriber to an equal proportion of partitions. For example, if two subscribers use the same Lite subscription and the Lite subscription is attached to a Lite topic with two partitions, each subscriber receives messages from one of the partitions.
Acknowledging messages
To acknowledge a message, send an acknowledgement to the Lite subscription.
Go
To send an acknowledgment, use the Message.Ack()
method.
Java
To send an acknowledgment, use the
AckReplyConsumer.ack()
method.
Python
To send an acknowledgment, use the Message.ack()
method.
Subscribers must acknowledge every message. Subscribers receive the oldest unacknowledged message first, followed by each subsequent message. If a subscriber skips one message, acknowledges the subsequent messages, and then reconnects, the subscriber receives the unacknowledged message and each subsequent, acknowledged message.
Lite subscriptions don't have an acknowledgment deadline and the Pub/Sub Lite service doesn't redeliver unacknowledged messages over an open streaming connection.
Using flow control
After the Pub/Sub Lite service delivers messages to subscribers, the subscribers store unacknowledged messages in memory. You can limit the number of outstanding messages that subscribers can store in memory using flow control settings. The flow control settings apply to each partition that a subscriber receives messages from.
You can configure the following flow control settings:
- Outstanding message size. The maximum size, in bytes, of the outstanding messages. The maximum size must be greater than the size of the largest message.
- Number of messages. The maximum number of outstanding messages.
The size of a message is in the
size_bytes
field.
You can configure flow control settings with the client library.
Go
To configure flow control settings, pass in ReceiveSettings
when calling pscompat.NewSubscriberClientWithSettings
. You can set the following parameters in ReceiveSettings
:
MaxOutstandingMessages
MaxOutstandingBytes
For an example, see this flow control sample.
Java
To configure flow control settings, use the following methods in the
FlowControlRequest.Builder
class:
Python
To configure flow control settings, set the following parameters in the
FlowControlSettings
class:
bytes_outstanding
messages_outstanding
For example, if the maximum number of messages is 100 and the subscriber connects to 10 partitions, the subscriber cannot receive more than 100 messages from any of the 10 partitions. The total number of outstanding messages might be greater than 100, but the subscriber cannot store more than 100 messages from each partition.