Module com.spotify.futures

Package com.spotify.futures

Class ConcurrencyLimiter<T>

java.lang.Object

com.spotify.futures.ConcurrencyLimiter<T>

All Implemented Interfaces:

FutureJobInvoker<T>

public final class ConcurrencyLimiter<T>
extends java.lang.Object
implements FutureJobInvoker<T>

A ConcurrencyLimiter can be used for efficiently queueing up asynchronous work to only run up to a specific limit of work concurrently.

This is a threadsafe class.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	ConcurrencyLimiter.CapacityReachedException
private static class	ConcurrencyLimiter.Job<T>

Field Summary

Fields

Modifier and Type	Field	Description
private java.util.concurrent.Executor	executor
private java.util.concurrent.Semaphore	limit
private int	maxConcurrency
private int	maxQueueSize
private java.util.concurrent.BlockingQueue<ConcurrencyLimiter.Job<T>>	queue

Constructor Summary

Constructors

Modifier	Constructor	Description
private	ConcurrencyLimiter(java.util.concurrent.Executor executor, int maxConcurrency, int maxQueueSize)

Method Summary

Modifier and Type	Method	Description
com.google.common.util.concurrent.ListenableFuture<T>	add(java.util.concurrent.Callable<? extends com.google.common.util.concurrent.ListenableFuture<T>> callable)	the callable function will run as soon as the currently active set of futures is less than the maxConcurrency limit.
static <T> ConcurrencyLimiter<T>	create(java.util.concurrent.Executor executor, int maxConcurrency, int maxQueueSize)	Create a ConcurrencyLimiter instance.
private ConcurrencyLimiter.Job<T>	grabJob()	Return a Job with acquired permit, null otherwise.
private void	invoke(com.google.common.util.concurrent.SettableFuture<T> response, java.util.concurrent.Callable<? extends com.google.common.util.concurrent.ListenableFuture<T>> callable)
int	numActive()	Return the number of currently active futures that have not yet completed.
int	numQueued()	Return the number of callables that are queued up and haven't started yet.
private void	pump()
int	remainingActiveCapacity()	Return the number of additional callables that can be run without queueing.
int	remainingQueueCapacity()	Return the number of additional callables that can be queued before failing.

Methods inherited from class java.lang.Object

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

Field Detail

executor

private final java.util.concurrent.Executor executor

queue

private final java.util.concurrent.BlockingQueue<ConcurrencyLimiter.Job<T>> queue

limit

private final java.util.concurrent.Semaphore limit

maxQueueSize

private final int maxQueueSize

maxConcurrency

private final int maxConcurrency

Constructor Detail

ConcurrencyLimiter

private ConcurrencyLimiter(java.util.concurrent.Executor executor,
                           int maxConcurrency,
                           int maxQueueSize)

Method Detail

create

public static <T> ConcurrencyLimiter<T> create(java.util.concurrent.Executor executor,
                                               int maxConcurrency,
                                               int maxQueueSize)

Create a ConcurrencyLimiter instance.

Parameters:

executor - the executor to run callables on.

maxConcurrency - maximum number of futures in progress,

maxQueueSize - maximum number of jobs in queue. This is a soft bound and may be temporarily exceeded if add() is called concurrently.

Returns:

a new concurrency limiter

add

public com.google.common.util.concurrent.ListenableFuture<T> add(java.util.concurrent.Callable<? extends com.google.common.util.concurrent.ListenableFuture<T>> callable)

the callable function will run as soon as the currently active set of futures is less than the maxConcurrency limit.

Specified by:

add in interface FutureJobInvoker<T>

Parameters:

callable - - a function that creates a future.

Returns:

a proxy future that completes with the future created by the input function. This future will be immediately failed with ConcurrencyLimiter.CapacityReachedException if the soft queue size limit is exceeded.

Throws:

java.lang.NullPointerException - if callable is null

numQueued

public int numQueued()

Return the number of callables that are queued up and haven't started yet.

Returns:

the number of callables that are queued up and haven't started yet.

numActive

public int numActive()

Return the number of currently active futures that have not yet completed.

Returns:

the number of currently active futures that have not yet completed.

remainingQueueCapacity

public int remainingQueueCapacity()

Return the number of additional callables that can be queued before failing.

Returns:

the number of additional callables that can be queued before failing.

remainingActiveCapacity

public int remainingActiveCapacity()

Return the number of additional callables that can be run without queueing.

Returns:

the number of additional callables that can be run without queueing.

grabJob

private ConcurrencyLimiter.Job<T> grabJob()

Return a Job with acquired permit, null otherwise.

Does one of two things: 1) return a job and acquire a permit from the semaphore 2) return null and does not acquire a permit from the semaphore

pump

private void pump()

invoke

private void invoke(com.google.common.util.concurrent.SettableFuture<T> response,
                    java.util.concurrent.Callable<? extends com.google.common.util.concurrent.ListenableFuture<T>> callable)