com.linkedin.parseq.batching

Class BatchingStrategy<G,K,T>

java.lang.Object

com.linkedin.parseq.batching.BatchingStrategy<G,K,T>

Type Parameters:

G - Type of a Group

K - Type of a Key

T - Type of a Value

Direct Known Subclasses:

SimpleBatchingStrategy, TaskBatchingStrategy

public abstract class BatchingStrategy<G,K,T>
extends Object

BatchingStrategy helps build "batching clients" in ParSeq. "Client" means an object that given K key provides a task that returns T value. "Batching" means that it can group together keys to resolve values in batches. The benefit of this approach is that batching happens transparently in the background and user's code does not have to deal with logic needed to implement batching.

Example of a batching client might be ParSeq client for a key-value store that provides batch get operation. For the sake of simplicity of the example we are using dummy, synchronous key-value store interface:

  interface KVStore {
    String get(Long key);
    Map <Long, String> batchGet(Collection <Long> keys);
  }
 

We can then implement a BatchingStrategy in the following way:

  public static class BatchingKVStoreClient extends BatchingStrategy <Integer, Long, String> {
    private final KVStore _store;
    public BatchingKVStoreClient(KVStore store) {
      _store = store;
    }

     @Override
    public void executeBatch(Integer group, Batch <Long, String> batch) {
      Map <Long, String> batchResult = _store.batchGet(batch.keys());
      batch.foreach((key, promise)  -> promise.done(batchResult.get(key)));
    }

     @Override
    public Integer classify(Long entry) {
      return 0;
    }
  }
 

In above example there is an assumption that all keys can be grouped together. This is why method classify() trivially returns a constant 0. In practice classify() returns a group for a key. Keys that have the same group will be batched together.

The interaction between ParSeq and BatchingStrategy is the following:

1. batchable(String desc, K key) is invoked to create Task instance
2. Plan is started by Engine.run()
3. When Task returned by batchable(String desc, K key) is started, the key K is remembered by a BatchingStrategy
4. When Plan can't make immediate progress BatchingStrategy will be invoked to run batchable operations:
   1. Every K key is classified using classify(K key) method
   2. Keys, together with adequate Promises, are batched together based on G group returned by previous step
   3. Method executeBatch(G group, Batch<K, T> batch) is invoked for every batch
   executeBatch(G group, Batch<K, T> batch) invocations are executed in the context of their own Task instances with description given by getBatchName(G group, Batch<K, T> batch). Implementation of BatchingStrategy has to be fast because it is executed sequentially with respect to tasks belonging to the plan. It means that no other task will be executed until BatchingStrategy completes. Typically classify(K key) is a synchronous and fast operation whilst executeBatch(G group, Batch<K, T> batch) returns quickly and completes promises asynchronously.

Author:

Jaroslaw Odzga (jodzga@linkedin.com)

See Also:

SimpleBatchingStrategy, TaskBatchingStrategy

Field Summary

Fields

Modifier and Type	Field and Description
static int	DEFAULT_MAX_BATCH_SIZE

Constructor Summary

Constructors

Constructor and Description
BatchingStrategy()

Method Summary

Modifier and Type	Method and Description
com.linkedin.parseq.Task<T>	batchable(K key) This method returns Task that returns value for a single key allowing this strategy to batch operations.
com.linkedin.parseq.Task<T>	batchable(String desc, K key) This method returns Task that returns value for a single key allowing this strategy to batch operations.
abstract G	classify(K key) Classify the K Key and by doing so assign it to a G group.
abstract void	executeBatch(G group, Batch<K,T> batch) This method will be called for every Batch.
protected void	executeBatchWithContext(G group, Batch<K,T> batch, com.linkedin.parseq.Context ctx)
BatchAggregationTimeMetric	getBatchAggregationTimeMetric()
String	getBatchName(G group, Batch<K,T> batch) Overriding this method allows providing custom name for a batch.
BatchSizeMetric	getBatchSizeMetric()
int	keySize(G group, K key) Overriding this method allows specifying size of the key for a given group.
int	maxBatchSizeForGroup(G group) Overriding this method allows specifying maximum batch size for a given group.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_MAX_BATCH_SIZE

public static final int DEFAULT_MAX_BATCH_SIZE

See Also:

Constant Field Values

Constructor Detail

BatchingStrategy

public BatchingStrategy()

Method Detail

batchable

public com.linkedin.parseq.Task<T> batchable(String desc,
                                             K key)

This method returns Task that returns value for a single key allowing this strategy to batch operations.

Parameters:

desc - description of the task

key - key

Returns:

Task that returns value for a single key allowing this strategy to batch operations

batchable

public com.linkedin.parseq.Task<T> batchable(K key)

This method returns Task that returns value for a single key allowing this strategy to batch operations.

Parameters:

key - key

Returns:

Task that returns value for a single key allowing this strategy to batch operations

getBatchSizeMetric

public BatchSizeMetric getBatchSizeMetric()

getBatchAggregationTimeMetric

public BatchAggregationTimeMetric getBatchAggregationTimeMetric()

executeBatch

public abstract void executeBatch(G group,
                                  Batch<K,T> batch)

This method will be called for every Batch. Implementation of this method must make sure that all SettablePromise contained in the Batch will eventually be resolved - typically asynchronously. Failing to eventually resolve any of the promises may lead to plan that never completes i.e. appears to hung and may lead to a memory leak.

Parameters:

group - group that represents the batch

batch - batch contains collection of SettablePromise that eventually need to be resolved - typically asynchronously

executeBatchWithContext

protected void executeBatchWithContext(G group,
                                       Batch<K,T> batch,
                                       com.linkedin.parseq.Context ctx)

classify

public abstract G classify(K key)

Classify the K Key and by doing so assign it to a G group. If two keys are classified by the same group then they will belong to the same Batch. This method needs to be thread safe.

Parameters:

key - key to be classified

Returns:

Group that represents a batch the key will belong to

maxBatchSizeForGroup

public int maxBatchSizeForGroup(G group)

Overriding this method allows specifying maximum batch size for a given group. Default value is 1024.

Parameters:

group - group for which maximum batch size needs to be decided

Returns:

maximum batch size for a given group

keySize

public int keySize(G group,
                   K key)

Overriding this method allows specifying size of the key for a given group. Default value is 1. This method is used when calculating batch size and making sure that it does not exceed max batch size for a group.

Parameters:

group - group

Returns:

max batch size for this group

See Also:

maxBatchSizeForGroup(Object)

getBatchName

public String getBatchName(G group,
                           Batch<K,T> batch)

Overriding this method allows providing custom name for a batch. Name will appear in the ParSeq trace as a description of the task that executes the batch.

Parameters:

batch - batch to be described

group - group to be described

Returns:

name for the batch and group