Package io.awspring.cloud.sqs.listener.backpressure

Class ThroughputBackPressureHandler

java.lang.Object

io.awspring.cloud.sqs.listener.backpressure.ThroughputBackPressureHandler

All Implemented Interfaces:

BackPressureHandler, IdentifiableContainerComponent

public class ThroughputBackPressureHandler
extends Object
implements BackPressureHandler, IdentifiableContainerComponent

A non-blocking BackPressureHandler that dynamically switches between high- and low-throughput modes to optimize polling behavior based on recent message availability.

Throughput modes

• Low-throughput mode: Only a single batch may be requested at a time. If a batch is already in-flight, zero permits are granted.
• High-throughput mode: Multiple batches may be requested concurrently. All requested permits are granted.

Throughput mode switching: The handler starts in low-throughput mode. It switches to high-throughput mode if messages are returned from a poll, and reverts to low-throughput mode if no messages are returned.

Typically used in conjunction with a concurrency-limiting BackPressureHandler such as ConcurrencyLimiterBlockingBackPressureHandler.

This handler builds on the original SemaphoreBackPressureHandler, separating specific responsibilities into a more modular form and enabling composition with other handlers as part of an extensible backpressure strategy.

Since:

4.0.0

Author:

Loïc Rouchon, Tomaz Fernandes

See Also:

• PollingMessageSource
• CompositeBackPressureHandler
• BackPressureHandlerFactories

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	ThroughputBackPressureHandler.Builder

Nested classes/interfaces inherited from interface io.awspring.cloud.sqs.listener.backpressure.BackPressureHandler

BackPressureHandler.ReleaseReason

Method Summary

Modifier and Type	Method	Description
static ThroughputBackPressureHandler.Builder	builder()
boolean	drain(Duration timeout)	Attempts to acquire all permits up to the specified timeout.
String	getId()	Get the component id.
void	release(int amount, BackPressureHandler.ReleaseReason reason)	Releases the specified amount of permits for processed messages.
int	request(int amount)	Requests a number of permits.
void	setId(String id)	Set the component id.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface io.awspring.cloud.sqs.listener.backpressure.BackPressureHandler

release

Method Details

builder

public static ThroughputBackPressureHandler.Builder builder()

setId

public void setId(String id)

Description copied from interface: IdentifiableContainerComponent

Set the component id.

Specified by:

setId in interface IdentifiableContainerComponent

Parameters:

id - the id.

getId

public String getId()

Description copied from interface: IdentifiableContainerComponent

Get the component id.

Specified by:

getId in interface IdentifiableContainerComponent

Returns:

the id.

request

public int request(int amount)
            throws InterruptedException

Description copied from interface: BackPressureHandler

Requests a number of permits. Each obtained permit allows the MessageSource to retrieve one message.

Specified by:

request in interface BackPressureHandler

Parameters:

amount - the amount of permits to request.

Returns:

the amount of permits obtained.

Throws:

InterruptedException - if the Thread is interrupted while waiting for permits.

release

public void release(int amount,
 BackPressureHandler.ReleaseReason reason)

Description copied from interface: BackPressureHandler

Releases the specified amount of permits for processed messages. Each message that has been processed should release one permit, whether processing was successful or not.

This method can be called in the following use cases:

• BackPressureHandler.ReleaseReason.LIMITED: all/some permits were not used because another BackPressureHandler has a lower permits limit and the difference in permits needs to be returned.
• BackPressureHandler.ReleaseReason.NONE_FETCHED: none of the permits were actually used because no messages were retrieved from SQS. Permits need to be returned.
• BackPressureHandler.ReleaseReason.PARTIAL_FETCH: some of the permits were used (some messages were retrieved from SQS). The unused ones need to be returned. The amount to be returned might be 0, in which case it means all the permits will be used as the same number of messages were fetched from SQS.
• BackPressureHandler.ReleaseReason.PROCESSED: a message processing finished, successfully or not.

Specified by:

release in interface BackPressureHandler

Parameters:

amount - the amount of permits to release.

reason - the reason why the permits were released.

drain

public boolean drain(Duration timeout)

Description copied from interface: BackPressureHandler

Attempts to acquire all permits up to the specified timeout. If successful, means all permits were returned and thus no activity is left in the MessageSource.

Specified by:

drain in interface BackPressureHandler

Parameters:

timeout - the maximum amount of time to wait for all permits to be released.

Returns:

whether all permits were acquired.