Interface Streamer<T>

Type Parameters:
T - the element type. TODO proper docs
All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
Streamer.HiddenStreamer, Streamer.StreamerFinishViaDisposableContainerCanceller
public interface Streamer<@NonNull T> extends AutoCloseable
A realized stream which can then be consumed asynchronously in steps. Think of it as the of the Java world. Runs best on Virtual Threads.

To make sure you can run finish, use DisposableContainer.clear() or DisposableContainer.reset() to get rid of all previous registered disposables. finish() will create its own, and if that gets stuck, just call clear()/dispose() on the container to get rid of this sequence for good.

Since:
4.0.0

  • Method Details

    • next

      @NonNull @NonNull CompletionStage<Boolean> next(@NonNull @NonNull DisposableContainer cancellation)
      Determine if there are more elements available from the source.
      Parameters:
      cancellation - ability to perform cancellation on a per-virtual-pull request.
      Returns:
      eventually true or false, indicating availability or termination

    • current

      @NonNull T current()
      Returns the current element if next() yielded true. Can be called multiple times between next() calls.
      Returns:
      the current element
      Throws:
      NoSuchElementException - before the very first next() or after next() returned false

    • finish

      @NonNull @NonNull CompletionStage<Void> finish(@NonNull @NonNull DisposableContainer cancellation)
      Called when the stream ends or gets cancelled. Should be always invoked. TODO, this is inherited from IAsyncDisposable in C#...
      Parameters:
      cancellation - to cancel a stuck finish operation, just in case.
      Returns:
      the stage you can await to cleanups to happen

    • next

      @NonNull default @NonNull CompletionStage<Boolean> next()
      Determine if there are more elements available from the source. Uses a default, individual CompositeDisposable to manage cancellation.
      Returns:
      eventually true or false, indicating availability or termination

    • close

      default void close()
      Make this Streamer a resource and a Closeable, allowing virtually blocking closing.
      Specified by:
      close in interface AutoCloseable

    • finishVia

      default Streamer<T> finishVia(@NonNull @NonNull DisposableContainer canceller)
      Augments the streamer so that the given canceller is injected into the various lifecycle await calls.
      Parameters:
      canceller - the canceller to inject
      Returns:
      the augmented streamer

    • hide

      default Streamer<T> hide()
      Hides the identity of this Streamer for debug or deoptimization purposes.
      Returns:
      the augmented streamer, always unique.

    • awaitNext

      default boolean awaitNext()
      Moves and awaits the sequence's next element, returns false if there are no more data.
      Returns:
      true if the next element via current() can be read, or false if the stream ended.

    • awaitNext

      default boolean awaitNext(@NonNull @NonNull DisposableContainer cancellation)
      Moves and awaits the sequence's next element, returns false if there are no more data.
      Parameters:
      cancellation - to efficiently cancel this await if necessary
      Returns:
      true if the next element via current() can be read, or false if the stream ended.

    • awaitFinish

      default void awaitFinish()
      Finish and cleanup the sequence after its completion or cancellation.

    • awaitFinish

      default void awaitFinish(@NonNull @NonNull DisposableContainer cancellation)
      Who cancels the cancellation attempt? Another cancellation attempt!
      Parameters:
      cancellation - the token to cancel and ongoing cancel attempt

    • await

      @Nullable static <T> T await(@NonNull @NonNull CompletionStage<T> stage)
      The await keyword for async/await.
      Type Parameters:
      T - the type of the returned value if any.
      Parameters:
      stage - the stage to await virtual-blockingly
      Returns:
      the awaited value

    • await

      @Nullable static <T> T await(@NonNull @NonNull CompletionStage<T> stage, @Nullable @Nullable DisposableContainer canceller)
      The cancellable await keyword for async/await.
      Type Parameters:
      T - the type of the returned value if any.
      Parameters:
      stage - the stage to await virtual-blockingly
      canceller - the container that can trigger a cancellation on demand
      Returns:
      the awaited value

    • runStage

      static <U> CompletionStage<U> runStage(Function<DisposableContainer, U> function, DisposableContainer canceller, Executor executor)
      Runs a function while turning it into a CompletionStage with a canceller supplied too.
      Type Parameters:
      U - the return type of the function
      Parameters:
      function - the function to apply
      canceller - the canceller to use
      executor - the executor to use
      Returns:
      the new stage

    • runStage

      static <U> CompletionStage<U> runStage(Function<DisposableContainer, U> function, DisposableContainer canceller)
      Runs a function while turning it into a CompletionStage with a canceller supplied too.
      Type Parameters:
      U - the return type of the function
      Parameters:
      function - the function to apply
      canceller - the canceller to use
      Returns:
      the new stage