Package org.infinispan.util.concurrent

Interface BlockingManager

All Known Implementing Classes:
BlockingManagerImpl
public interface BlockingManager
Manager utility for blocking operations that runs tasks on the blocking executor and returns a CompletionStage or Publisher that continues on the non-blocking executor, similar to stage.handleAsync(callback, blockingExecutor).whenCompleteAsync(NOOP, nonBlockingExecutor).

If the current thread is blocking, it blocks until the task can run, then runs the task in the current thread and returns a completed CompletionStage so it does not continue the execution on the non-blocking executor.

Many of the methods on BlockingManager let you pass an identifier (ID) when performing the operation. This ID is printed with TRACE logs. For this reason, you should provide IDs that are unique, making it easier to track the stream of operations across threads if TRACE logs are used.

  • Method Details

    • runBlocking

      CompletionStage<Void> runBlocking(Runnable runnable, Object traceId)
      Replacement for CompletionStage.runAsync() that invokes the Runnable in a blocking thread if the current thread is non-blocking or in the current thread if the current thread is blocking. The returned stage, if not complete, resumes any chained stage on the non-blocking executor.

      Note that if the current thread is blocking, the task is invoked in the current thread, meaning the stage is always completed when returned, so any chained stage is also invoked on the current thread.

      Parameters:
      runnable - blocking operation that runs some code.
      traceId - an identifier that can be used to tell in a trace when an operation moves between threads.
      Returns:
      a stage that is completed after the runnable is done or throws an exception.

    • subscribeBlockingConsumer

      <E> CompletionStage<Void> subscribeBlockingConsumer(org.reactivestreams.Publisher<E> publisher, Consumer<E> consumer, Object traceId)
      Subscribes to the provided publisher on the invoking thread. Published values are observed on a blocking thread one a time passed to the provided consumer. The returned stage if not complete will resume any chained stage on the non blocking executor.

      If no values are published the returned stage will be completed upon return of this method and require no thread context switches

      Note that if the current thread is blocking everything including subscription, publication and consumption of values will be done on the current thread.

      Type Parameters:
      E - the type of entries
      Parameters:
      publisher - publisher of values to consume
      consumer - consumer to handle the values
      traceId - an identifier that can be used to tell in a trace when an operation moves between threads
      Returns:
      a stage that is completed after all values are consumed

    • subscribeBlockingCollector

      <T, A, R> CompletionStage<R> subscribeBlockingCollector(org.reactivestreams.Publisher<T> publisher, Collector<? super T,A,R> collector, Object traceId)
      Subscribes to the provided publisher on the invoking thread. Published values are observed on a blocking thread one a time passed to the provided collector. The returned stage if not complete will resume any chained stage on the non blocking executor.

      If no values are published the returned stage will be completed upon return of this method and require no thread context switches

      Note that if the current thread is blocking everything including subscription, publication and collection of values will be done on the current thread.

      Type Parameters:
      T - the type of entries
      A - accumulator type of the entries
      R - final value type
      Parameters:
      publisher - publisher of values to collect
      collector - collector of the values
      traceId - an identifier that can be used to tell in a trace when an operation moves between threads
      Returns:
      a stage that when complete contains the collected values as a single value

    • supplyBlocking

      <V> CompletionStage<V> supplyBlocking(Supplier<V> supplier, Object traceId)
      Replacement for CompletionStage.supplyAsync() that invokes the Supplier in a blocking thread (if the current thread is non-blocking) or in the current thread (if the current thread is blocking). The returned stage, if not complete, resumes any chained stage on the non-blocking executor.

      Note that if the current thread is blocking, the task is invoked in the current thread meaning the stage is always completed when returned, so any chained stage is also invoked on the current thread.

      Type Parameters:
      V - the supplied type.
      Parameters:
      supplier - blocking operation that returns a value.
      traceId - an identifier that can be used to tell in a trace when an operation moves between threads.
      Returns:
      a stage that, when complete, contains the value returned from the supplier or a throwable.

    • handleBlocking

      <I, O> CompletionStage<O> handleBlocking(CompletionStage<? extends I> stage, BiFunction<? super I,Throwable,? extends O> function, Object traceId)
      Replacement for CompletionStage.handleAsync() that invokes the BiFunction in a blocking thread (if the current thread is non-blocking) or in the current thread (if the current thread is blocking and the stage is completed). The returned stage, if not complete, resumes any chained stage on the non-blocking executor.

      Note that if the current thread is blocking and the stage is completed, the task is invoked in the current thread meaning the stage is always completed when returned, so any chained stage is also invoked on the current thread.

      Type Parameters:
      I - input value type to the function.
      O - output value type after being transformed via function.
      Parameters:
      stage - stage, that may or may not be complete, to handle.
      function - the blocking function.
      traceId - an identifier that can be used to tell in a trace when an operation moves between threads.
      Returns:
      a stage that, when complete, contains the value returned from the function or a throwable.

    • thenRunBlocking

      <I> CompletionStage<Void> thenRunBlocking(CompletionStage<? extends I> stage, Runnable runnable, Object traceId)
      Replacement for CompletionStage.thenRunAsync(Runnable) that invokes the Runnable in a blocking thread (if the current thread is non-blocking) or in the current thread (if the current thread is blocking and the stage is completed). The returned stage, if not complete, resumes any chained stage on the non-blocking executor.

      Note that if the current thread is blocking and the stage is completed, the task is invoked in the current thread meaning the stage is always completed when returned, so any chained stage is also invoked on the current thread.

      Type Parameters:
      I - input value type to the function.
      Parameters:
      stage - stage, that may or may not be complete, to apply.
      runnable - blocking operation that runs some code.
      traceId - an identifier that can be used to tell in a trace when an operation moves between threads.
      Returns:
      a stage that is completed after the action is done or throws an exception.

    • thenApplyBlocking

      <I, O> CompletionStage<O> thenApplyBlocking(CompletionStage<? extends I> stage, Function<? super I,? extends O> function, Object traceId)
      Replacement for CompletionStage.thenApplyAsync() that invokes the Function in a blocking thread (if the current thread is non-blocking) or in the current thread (if the current thread is blocking and the stage is completed). The returned stage, if not complete, resumes any chained stage on the non-blocking executor.

      Note that if the current thread is blocking and the stage is completed, the task is invoked in the current thread meaning the stage is always completed when returned, so any chained stage is also invoked on the current thread.

      Type Parameters:
      I - input value type to the function.
      O - output value type after being transformed via function.
      Parameters:
      stage - stage, that may or may not be complete, to apply.
      function - the blocking function.
      traceId - an identifier that can be used to tell in a trace when an operation moves between threads.
      Returns:
      a stage that, when complete, contains the value returned from the function or a throwable.

    • thenComposeBlocking

      <I, O> CompletionStage<O> thenComposeBlocking(CompletionStage<? extends I> stage, Function<? super I,? extends CompletionStage<O>> function, Object traceId)
      Replacement for CompletionStage.thenComposeAsync() that invokes the Function in a blocking thread (if the current thread is non-blocking) or in the current thread (if the current thread is blocking and the stage is completed). The returned stage, if not complete, resumes any chained stage on the non-blocking executor.

      Note that if the current thread is blocking and the stage is completed, the task is invoked in the current thread meaning the stage is always completed when returned, so any chained stage is also invoked on the current thread.

      Note this method is not normally required as the Function already returns a CompletionStage and it is recommended to have the composed function just be non-blocking to begin with. This method is here when invoking some method that may spuriously block to be safe.

      Type Parameters:
      I - input value type to the function.
      O - output value type after being transformed via function.
      Parameters:
      stage - stage, that may or may not be complete, to compose.
      function - the blocking function.
      traceId - an identifier that can be used to tell in a trace when an operation moves between threads.
      Returns:
      a stage that, when complete, contains the value returned from the composed function or a throwable.

    • whenCompleteBlocking

      <V> CompletionStage<V> whenCompleteBlocking(CompletionStage<V> stage, BiConsumer<? super V,? super Throwable> biConsumer, Object traceId)
      Replacement for CompletionStage.whenCompleteAsync() that invokes the BiConsumer in a blocking thread (if the current thread is non-blocking) or in the current thread (if the current thread is blocking). The returned stage, if not complete, resumes any chained stage on the non-blocking executor.

      Note that if the current thread is blocking and the stage is completed, the task is invoked in the current thread meaning the stage is always completed when returned, so any chained stage is also invoked on the current thread.

      Type Parameters:
      V - stage value type.
      Parameters:
      stage - stage, that may or may not be complete, to apply.
      biConsumer - the blocking biConsumer.
      traceId - an identifier that can be used to tell in a trace when an operation moves between threads.
      Returns:
      a stage that is complete when the biConsumer is complete, but retains the results from the original stage.

    • continueOnNonBlockingThread

      <V> CompletionStage<V> continueOnNonBlockingThread(CompletionStage<V> delay, Object traceId)
      When the provided stage is complete, continue the completion chain of the returned CompletionStage on the supplied executor. If tracing is enabled, a trace message is printed using the object as an identifier to more easily track the transition between threads.

      This method is useful when an asynchronous computation completes and you do not want to run further processing on the thread that returned it. An example may be that some blocking operation is performed on a special blocking thread pool. However when the blocking operation completes we want to continue processing that result in a thread pool that is for computational tasks.

      If the supplied stage is already completed when invoking this command, it returns an already completed stage, which means any additional dependent stages are run in the invoking thread.

      Type Parameters:
      V - return value type of the supplied stage.
      Parameters:
      delay - the stage to delay the continuation until complete.
      traceId - the identifier to print when tracing is enabled.
      Returns:
      a CompletionStage that, when depended upon, runs any callback in the supplied executor.

    • nonBlockingExecutor

      Executor nonBlockingExecutor()
      Returns the non blocking executor that this BlockingManager uses to resume tasks on when the task is not ran inline with the invoking blocking thread.
      Returns:
      an executor use for non blocking tasks

    • blockingPublisher

      <V> org.reactivestreams.Publisher<V> blockingPublisher(org.reactivestreams.Publisher<V> publisher)
      Provided a publisher that is known to block when subscribed to. Thus if the thread that subscribes in a non blocking thread we will instead subscribe on a blocking thread and observe on a non blocking thread for each published value.

      If, however, the subscribing thread is a blocking thread no threading changes will be done, which means the publisher will be subscribed to on the invoking thread. In this case values have no guarantee as to which thread they are observed on, dependent solely on how the Publisher publishes them.

      Type Parameters:
      V - the published entry types.
      Parameters:
      publisher - the publisher that, when subscribed to, blocks the current thread.
      Returns:
      publisher that does not block the current thread.

    • blockingPublisherToVoidStage

      <V> CompletionStage<Void> blockingPublisherToVoidStage(org.reactivestreams.Publisher<V> publisher, Object traceId)
      Subscribes to the provided blocking publisher using the the blocking executor, ignoring all elements and returning a CompletionStage with a value of null which completes on a non-blocking thread. This method is designed to be used by a Publisher that when subscribed to has some type of side-effect that is blocking.

      The returned CompletionStage will always be completed upon a non-blocking thread if the current thread is non-blocking.

      Note that if the current thread is blocking everything including subscription, publication and collection of values will be done on the current thread.

      Type Parameters:
      V - the published entry types.
      Parameters:
      publisher - the publisher that, when subscribed to, blocks the current thread.
      Returns:
      a completion stage that completes once the publisher has completed.

    • asExecutor

      Executor asExecutor(String name)
      Returns an executor that will run the given tasks on a blocking thread as required.

      Note that this executor will always submit the task to the blocking thread pool, even if the requestor is a blocking thread. This is different than other methods that will invoke the task in the invoking thread if the invoking thread is blocking.

      Returns:
      an executor that can run blocking commands.

    • limitedBlockingExecutor

      BlockingManager.BlockingExecutor limitedBlockingExecutor(String name, int concurrency)
      Provides a BlockingManager.BlockingExecutor which is limited to the provided concurrency amount.
      Parameters:
      name - name of the limited blocking executor.
      concurrency - maximum amount of concurrent operations to be performed via the returned executor.
      Returns:
      a blocking executor limited in the amount of concurrent invocations.

    • scheduleRunBlocking

      default BlockingManager.ScheduledBlockingCompletableStage<Void> scheduleRunBlocking(Runnable runnable, long delay, TimeUnit unit, Object traceId)
      Replacement for ScheduledExecutorService.schedule(Runnable, long, TimeUnit)} that invokes the Runnable in a blocking thread only after the elapsed time.

      Unlike other methods in this interface, the submitting thread does not impact this method's behavior.

      Parameters:
      runnable - blocking operation that runs some code.
      delay - the time from now to delay execution
      unit - the time unit of the delay parameter
      traceId - an identifier that can be used to tell in a trace when an operation moves between threads.
      Returns:
      a stage that is completed after the runnable is done or throws an exception.

    • scheduleRunBlocking

      <V> BlockingManager.ScheduledBlockingCompletableStage<V> scheduleRunBlocking(Supplier<V> supplier, long delay, TimeUnit unit, Object traceId)
      Replacement for ScheduledExecutorService.schedule(java.util.concurrent.Callable, long, TimeUnit)} that invokes the Callable in a blocking thread only after the elapsed time.

      Unlike other methods in this interface, the submitting thread does not impact this method's behavior.

      Parameters:
      supplier - blocking operation that runs some code.
      delay - the time from now to delay execution
      unit - the time unit of the delay parameter
      traceId - an identifier that can be used to tell in a trace when an operation moves between threads.
      Returns:
      a stage that is completed after the runnable is done or throws an exception.

    • scheduleRunBlockingAtFixedRate

      ScheduledFuture<Void> scheduleRunBlockingAtFixedRate(Runnable runnable, long initialDelay, long period, TimeUnit unit, Object traceId)
      Replacement for ScheduledExecutorService.scheduleAtFixedRate(Runnable, long, long, TimeUnit) that invokes the Runnable in a blocking thread periodically at fixed rate.

      Unlike other methods in this interface, the submitting thread does not impact this method's behavior.

      Parameters:
      runnable - blocking operation that runs some code
      initialDelay - the time to delay first execution
      period - the period between successive executions
      unit - the time unit of the delay parameter
      traceId - an identifier that can be used to tell in a trace when an operation moves between threads
      Returns:
      a stage that is completed after the runnable is done or throws an exception.