org.terracotta.modules.async
Class AsyncCoordinator<I>

java.lang.Object
  org.terracotta.modules.async.AsyncCoordinator<I>

public class AsyncCoordinator<I>
extends Object

Field Summary

static Collection

UNFLUSHABLE_STATE

Constructor Summary

AsyncCoordinator()
Creates a new coordinator instance using the default configuration and steal policy.

AsyncCoordinator(AsyncConfig config)
Creates a new coordinator instance with a custom configuration and the default steal policy.

AsyncCoordinator(AsyncConfig config, StealPolicy<I> stealPolicy)
Creates a new coordinator instance with a custom configuration and steal policy.

Method Summary

void	add(I item) Add a new item so that it will be asynchronously processed by the item processor that is provided when the coordinator is started up.
Collection<ProcessingBucket<I>>	getLocalBuckets() Returns the processing buckets that are local to the current node.
void	setQuarantinedItemsFilter(QuarantinedItemsFilter<I> filter)
void	start(ItemProcessor<I> processor) Start the coordinator with an item processor and a concurrency of 1.
void	start(ItemProcessor<I> processor, int processingConcurrency) Start the coordinator with an item processor and a custom concurrency.
void	start(ItemProcessor<I> processor, int processingConcurrency, ScatterPolicy policy) Start the coordinator.
void	stop() Stop the coordinator and all the internal data structures.

Methods inherited from class java.lang.Object

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

Field Detail

UNFLUSHABLE_STATE

public static final Collection UNFLUSHABLE_STATE

Constructor Detail

AsyncCoordinator

public AsyncCoordinator()

Creates a new coordinator instance using the default configuration and steal policy.

See Also:

AsyncCoordinator(AsyncConfig, StealPolicy)

AsyncCoordinator

public AsyncCoordinator(AsyncConfig config)

Creates a new coordinator instance with a custom configuration and the default steal policy.

Parameters:

config - the custom configuration instance that should be used by this coordinator, if null is used the default configuration will be used

See Also:

AsyncCoordinator(AsyncConfig, StealPolicy)

AsyncCoordinator

public AsyncCoordinator(AsyncConfig config,
                        StealPolicy<I> stealPolicy)

Creates a new coordinator instance with a custom configuration and steal policy.

In case null is provided for either argument, the corresponding default will be used. For the configuration, the default is DefaultAsyncConfig and for the steal policy, the default is FallBehindStealPolicy. The maxAllowedFallBehind value of the default steal policy will be retrieved from the configuration.

Parameters:

config - the custom configuration instance that should be used by this coordinator, if null is provided the default configuration will be used

stealPolicy - the custom steal policy that should be used by this coordinator, if null is provided the default steal policy will be used

Method Detail

setQuarantinedItemsFilter

public void setQuarantinedItemsFilter(QuarantinedItemsFilter<I> filter)

start

public void start(ItemProcessor<I> processor)

Start the coordinator with an item processor and a concurrency of 1.

Parameters:

processor - the item processor instance that will be used to process each item that has been added

See Also:

start(ItemProcessor, int, ScatterPolicy)

start

public void start(ItemProcessor<I> processor,
                  int processingConcurrency)

Start the coordinator with an item processor and a custom concurrency.

Parameters:

processor - the item processor instance that will be used to process each item that has been added

processingConcurrency - the number of buckets that will be created to store the work items

See Also:

start(ItemProcessor, int, ScatterPolicy)

start

public void start(ItemProcessor<I> processor,
                  int processingConcurrency,
                  ScatterPolicy policy)

Start the coordinator.

Note that while this coordinator instance has to be a Terracotta DSO root, the start method has to be executed by every node. The item processor instance will never be shared and will remain local to the cluster node that it was instantiated on. This allows each item processor to refer to local resources, like database connections, without having to worry about how to coordinate these across the cluster. If a lot of work items are added to the coordinator, there might be a high amount of lock contention while adding the items to the internal buckets. Increasing the concurrency will create a larger amount of buckets, which allows more work items to be added concurrently. A custom scatter policy can be provided to change how buckets are internally select when an item is added. If null is provided for the scatter policy, the default will be used. Meaning that when the concurrency is 1, the single bucket will always be selected and if the concurrency is higher, the bucket will be randomly selected at item addition.

Parameters:

processor - the item processor instance that will be used to process each item that has been added

processingConcurrency - the number of buckets that will be created to store the work items, this has to be minimal 1

policy - the scatter policy that will be used to select the bucket into which a work item will be added

See Also:

add(Object)

add

public void add(I item)

Add a new item so that it will be asynchronously processed by the item processor that is provided when the coordinator is started up.

Note that while the item processor is local and not shared across a Terracotta DSO cluster, the work items are. In the case of node failures or work stealing, item will be transferred to other nodes in the cluster and will be processed by the relevant local item processors there. An item should thus conceptually represent the application data that allows an item processor to work with it. All behavior should thus be implemented by the item processor class and not the item class.

Parameters:

item - the item of work to process asynchronously

See Also:

start(ItemProcessor, int, ScatterPolicy)

stop

public void stop()

Stop the coordinator and all the internal data structures.

This stops as quickly as possible without losing any previously added items. However, no guarantees are made towards the processing of these items. It's highly likely that items are still inside the internal buckets and not processed.

See Also:

start(ItemProcessor, int, ScatterPolicy)

getLocalBuckets

public Collection<ProcessingBucket<I>> getLocalBuckets()

Returns the processing buckets that are local to the current node.

This for instance makes it possible to register a ProcessingBucketListener for the buckets that have been created by the AsyncCoordinator for the current node.

Returns:

the collection of local processing buckets