Module org.elasticsearch.server
Package org.elasticsearch.action.support

Class CancellableFanOut<Item,ItemResponse,FinalResponse>

java.lang.Object
org.elasticsearch.action.support.CancellableFanOut<Item,ItemResponse,FinalResponse>
public abstract class CancellableFanOut<Item,ItemResponse,FinalResponse> extends Object
Allows an action to fan-out to several sub-actions and accumulate their results, but which reacts to a cancellation by releasing all references to itself, and hence the partially-accumulated results, allowing them to be garbage-collected. This is a useful protection for cases where the results may consume a lot of heap (e.g. stats) but the final response may be delayed by a single slow node for long enough that the client gives up.

Note that it's easy to accidentally capture another reference to this class when implementing it, and this will prevent the early release of any accumulated results. Beware of lambdas and method references. You must test your implementation carefully (using e.g. ReachabilityChecker) to make sure it doesn't do this.

  • Constructor Details

    • CancellableFanOut

      public CancellableFanOut()

  • Method Details

    • run

      public final void run(@Nullable Task task, Iterator<Item> itemsIterator, ActionListener<FinalResponse> listener)
      Run the fan-out action.
      Parameters:
      task - The task to watch for cancellations. If null or not a CancellableTask then the fan-out still works, just without any cancellation handling.
      itemsIterator - The items over which to fan out. Iterated on the calling thread.
      listener - A listener for the final response, which is completed after all the fanned-out actions have completed. It is not completed promptly on cancellation. Completed on the thread that handles the final per-item response (or the calling thread if there are no items).

    • sendItemRequest

      protected abstract void sendItemRequest(Item item, ActionListener<ItemResponse> listener)
      Run the action (typically by sending a transport request) for an individual item. Called in sequence on the thread that invoked run(org.elasticsearch.tasks.Task, java.util.Iterator<Item>, org.elasticsearch.action.ActionListener<FinalResponse>). May not be called for every item if the task is cancelled during the iteration.

      Note that it's easy to accidentally capture another reference to this class when implementing this method, and that will prevent the early release of any accumulated results. Beware of lambdas, and test carefully.

    • onItemResponse

      protected abstract void onItemResponse(Item item, ItemResponse itemResponse)
      Handle a successful response for an item. May be called concurrently for multiple items. Not called if the task is cancelled. Must not throw any exceptions.

      Note that it's easy to accidentally capture another reference to this class when implementing this method, and that will prevent the early release of any accumulated results. Beware of lambdas, and test carefully.

    • onItemFailure

      protected abstract void onItemFailure(Item item, Exception e)
      Handle a failure for an item. May be called concurrently for multiple items. Not called if the task is cancelled. Must not throw any exceptions.

      Note that it's easy to accidentally capture another reference to this class when implementing this method, and that will prevent the early release of any accumulated results. Beware of lambdas, and test carefully.

    • onCompletion

      protected abstract FinalResponse onCompletion() throws Exception
      Called when responses for all items have been processed, on the thread that processed the last per-item response or possibly the thread which called run(org.elasticsearch.tasks.Task, java.util.Iterator<Item>, org.elasticsearch.action.ActionListener<FinalResponse>) if all items were processed before run(org.elasticsearch.tasks.Task, java.util.Iterator<Item>, org.elasticsearch.action.ActionListener<FinalResponse>) returns. Not called if the task is cancelled.

      Note that it's easy to accidentally capture another reference to this class when implementing this method, and that will prevent the early release of any accumulated results. Beware of lambdas, and test carefully.

      Throws:
      Exception