org.apache.samza.util

Interface RateLimiter

All Superinterfaces:

java.io.Serializable

@InterfaceStability.Unstable
public interface RateLimiter
extends java.io.Serializable

A rate limiter interface used by Samza components to limit throughput of operations against a resource. Operations against a resource are represented by credits. Resources could be streams, databases, web services, etc.

This interface supports two categories of policies: tagged and non-tagged. Tagged rate limiter is used, when further differentiation is required within a resource. For example: messages in a stream may be treated differently depending on the overall situation of processing; or read/write operations to a database. Tagging is the mechanism to allow this differentiation.

The following types of invocations are provided

• Block indefinitely until requested credits become available
• Block for a provided amount of time, then return available credits

Method Summary

Modifier and Type	Method and Description
void	acquire(int numberOfCredit) Attempt to acquire the provided number of credits, blocks indefinitely until all requested credits become available.
int	acquire(int numberOfCredit, long timeout, java.util.concurrent.TimeUnit unit) Attempt to acquire the provided number of credits, blocks for up to provided amount of time for credits to become available.
void	acquire(java.util.Map<java.lang.String,java.lang.Integer> tagToCreditMap) Attempt to acquire the provided number of credits for a number of tags, blocks indefinitely until all requested credits become available
java.util.Map<java.lang.String,java.lang.Integer>	acquire(java.util.Map<java.lang.String,java.lang.Integer> tagToCreditMap, long timeout, java.util.concurrent.TimeUnit unit) Attempt to acquire the provided number of credits for a number of tags, blocks for up to provided amount of time for credits to become available.
java.util.Set<java.lang.String>	getSupportedTags() Get the entire set of tags for which we have configured credits for rate limiting.
void	init(Context context) Initialize this rate limiter, this method should be called during container initialization.

Method Detail

init

void init(Context context)

Initialize this rate limiter, this method should be called during container initialization.

Parameters:

context - Context that corresponds to this rate limiter

acquire

void acquire(int numberOfCredit)

Attempt to acquire the provided number of credits, blocks indefinitely until all requested credits become available.

Parameters:

numberOfCredit - requested number of credits

acquire

int acquire(int numberOfCredit,
            long timeout,
            java.util.concurrent.TimeUnit unit)

Attempt to acquire the provided number of credits, blocks for up to provided amount of time for credits to become available. When timeout elapses and not all required credits can be acquired, it returns the number of credits currently available. It may return immediately, if it determines no credits can be acquired during the provided amount time.

Parameters:

numberOfCredit - requested number of credits

timeout - number of time unit to wait

unit - time unit to for timeout

Returns:

number of credits acquired

acquire

void acquire(java.util.Map<java.lang.String,java.lang.Integer> tagToCreditMap)

Attempt to acquire the provided number of credits for a number of tags, blocks indefinitely until all requested credits become available

Parameters:

tagToCreditMap - a map of requested number of credits keyed by tag

acquire

java.util.Map<java.lang.String,java.lang.Integer> acquire(java.util.Map<java.lang.String,java.lang.Integer> tagToCreditMap,
                                                          long timeout,
                                                          java.util.concurrent.TimeUnit unit)

Attempt to acquire the provided number of credits for a number of tags, blocks for up to provided amount of time for credits to become available. When timeout elapses and not all required credits can be acquired, it returns the number of credits currently available. It may return immediately, if it determines no credits can be acquired during the provided amount time.

Parameters:

tagToCreditMap - a map of requested number of credits keyed by tag

timeout - number of time unit to wait

unit - time unit to for timeout

Returns:

a map of number of credits acquired keyed by tag

getSupportedTags

java.util.Set<java.lang.String> getSupportedTags()

Get the entire set of tags for which we have configured credits for rate limiting.

Returns:

set of supported tags