org.terracotta.async
Class AsyncCoordinator<I>

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

public class AsyncCoordinator<I>
extends Object

An AsyncCoordinator allows work to be added and processed asynchronously in a fault-tolerant and high performance fashion when Terracotta DSO is active.

It's important that an instance of the coordinator is declared as a Terracotta DSO root to ensure that only one logical instance is used by all the nodes in the cluster. If the instance is a regular shared object, each node will have a different coordinator and much of the benefits are lost.

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) Attach the specified QuarantinedItemsFilter to this coordinator.
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, ItemScatterPolicy<? super I> policy) Start the coordinator.
void	start(ItemProcessor<I> processor, int processingConcurrency, ScatterPolicy policy) Deprecated. please use the #start(ItemProcessor, int, ItemScatterPolicy)
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

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)

Attach the specified QuarantinedItemsFilter to this coordinator.

A quarantined items filter allows scheduled work to be filtered (and possibly skipped) before being executed.

Assigning null as the quarantined filter causes any existing filter to be removed.

Parameters:

filter - filter to be applied

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, ItemScatterPolicy)

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, ItemScatterPolicy)

start

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

Deprecated. please use the #start(ItemProcessor, int, ItemScatterPolicy)

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 selected based on the item's hash code.

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), HashCodeScatterPolicy

start

public void start(ItemProcessor<I> processor,
                  int processingConcurrency,
                  ItemScatterPolicy<? super I> 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 selected based on the item's hash code.

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), HashCodeScatterPolicy

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, ItemScatterPolicy)

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