Package com.google.api.gax.batching

Interface Batcher<ElementT,ElementResultT>

Type Parameters:
ElementT - The type of each individual element to be batched.
ElementResultT - The type of the result for each individual element.
All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
BatcherImpl
@InternalExtensionOnly public interface Batcher<ElementT,ElementResultT> extends AutoCloseable
Represents a batching context where individual elements will be accumulated and flushed in a large batch request at some point in the future. The buffered elements can be flushed manually or when triggered by an internal threshold. This is intended to be used for high throughput scenarios at the cost of latency.

Batcher instances are not thread safe. To use across different threads, create a new Batcher instance per thread.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final ApiCallContext.Key<Long>
    THROTTLED_TIME_KEY
    ApiCallContext.Key for tracking batch total throttled time

  • Method Summary

    Modifier and Type
    Method
    Description
    ApiFuture<ElementResultT>
    add(ElementT entry)
    Queues the passed in element to be sent at some point in the future.
    void
    cancelOutstanding()
    Cancels all outstanding batch RPCs.
    void
    close()
    Closes this Batcher by preventing new elements from being added, then flushing the existing elements and waiting for all the outstanding work to be resolved.
    void
    close(Duration timeout)
    Closes this Batcher by preventing new elements from being added, then flushing the existing elements and waiting for all the outstanding work to be resolved.
    ApiFuture<Void>
    closeAsync()
    Closes this Batcher by preventing new elements from being added, and then sending outstanding elements.
    void
    flush()
    Synchronously sends any pending elements as a batch and waits for all outstanding batches to be complete.
    void
    sendOutstanding()
    Sends accumulated elements asynchronously for batching.

  • Field Details

  • Method Details

    • add

      ApiFuture<ElementResultT> add(ElementT entry)
      Queues the passed in element to be sent at some point in the future.

      The element will be sent as part of a larger batch request at some point in the future. The returned ApiFuture will be resolved once the result for the element has been extracted from the batch response.

      Note: Cancelling returned result simply marks the future cancelled, It would not stop the batch request.

    • flush

      void flush() throws InterruptedException
      Synchronously sends any pending elements as a batch and waits for all outstanding batches to be complete.
      Throws:
      InterruptedException

    • sendOutstanding

      void sendOutstanding()
      Sends accumulated elements asynchronously for batching.

      Note: This method can be invoked concurrently unlike add(ElementT) and close(), which can only be called from a single user thread. Please take caution to avoid race condition.

    • cancelOutstanding

      void cancelOutstanding()
      Cancels all outstanding batch RPCs.

    • close

      void close() throws InterruptedException
      Closes this Batcher by preventing new elements from being added, then flushing the existing elements and waiting for all the outstanding work to be resolved.
      Specified by:
      close in interface AutoCloseable
      Throws:
      InterruptedException

    • close

      void close(@Nullable Duration timeout) throws InterruptedException, TimeoutException
      Closes this Batcher by preventing new elements from being added, then flushing the existing elements and waiting for all the outstanding work to be resolved. If all of the outstanding work has not been resolved, then a BatchingException will be thrown with details of the remaining work. The batcher will remain in a closed state and will not allow additional elements to be added.
      Throws:
      InterruptedException
      TimeoutException

    • closeAsync

      ApiFuture<Void> closeAsync()
      Closes this Batcher by preventing new elements from being added, and then sending outstanding elements. The returned future will be resolved when the last element completes