README.adoc.jam

= Threaded Stream Library
javax0.vtstream

:toc:
:icons: font
:source-highlighter: highlightjs

This library provides an enhanced, multithreaded stream processing solution, `ThreadedStream`, enabling asynchronous and parallel processing of data elements within Java streams.
Utilizing Project Loom's virtual threads, it achieves optimized throughput and minimal latency, ideal for complex, concurrent data processing workflows.

== Features

- Asynchronous and parallel stream processing using virtual threads
- Fully customizable stream operations (e.g., map, filter, distinct, findFirst)
- Command-based pattern for flexible, reusable processing logic
- `Stream` API compatibility, offering familiar operations on `ThreadedStream`

== Getting Started

To use the `ThreadedStream` library, include the `javax0.vtstream` package in your project.

== Installation

Add the library as a dependency in your project's build configuration (e.g., `pom.xml` for Maven or `build.gradle` for Gradle).

== Basic Usage

Creating a `ThreadedStream` is straightforward.
You can initialize a stream directly from any standard Java `Stream`.

[source,java]
----
import javax0.vtstream.ThreadedStream;

Stream<Integer> numbers = IntStream.range(1, 100).boxed();
ThreadedStream<Integer> threadedStream = ThreadedStream.threaded(numbers);
threadedStream.filter(n -> n % 2 == 0)
              .map(n -> n * n)
              .forEach(System.out::println);
----

=== Parallel Execution

`ThreadedStream` supports both ordered and unordered parallel execution:
- `toUnorderedStream()`: Processes each element asynchronously in random order.
- `toOrderedStream()`: Ensures elements are processed in their original order, with blocking operations if necessary.

=== Stream Commands

The library offers several predefined command classes to apply complex processing on stream elements.
Here are a few examples:

- `Filter`: Filters elements based on a `Predicate`
- `Map`: Transforms elements with a `Function`
- `Distinct`: Filters out duplicate elements
- `Skip`: Skips a specified number of elements

[source,java]
----
threadedStream
    .filter(new Command.Filter<>(n -> n > 10))
    .map(new Command.Map<>(String::valueOf))
    .distinct()
    .forEach(System.out::println);
----

== Error Handling

The library includes an `exception()` method to gracefully handle errors during stream operations.
Commands can also return a `deleted` result to filter out elements that encounter errors or are deemed unnecessary.

== API Overview

=== ThreadedStream Class

The main class in the library, `ThreadedStream<T>`, implements `Stream<T>`.
It supports chaining of multiple processing commands and offers compatibility with the Java `Stream` API, making it an ideal choice for parallel data pipelines.

*Constructors:*

- `ThreadedStream(Command<Object, T> command, ThreadedStream<S> downstream, ExecutorService executorService)`
- `ThreadedStream(Stream<T> source, ExecutorService executorService)`

*Methods:*

- `filter(Predicate<? super T> predicate)`: Filters elements based on the predicate.
- `map(Function<? super T, ? extends R> mapper)`: Maps elements to another form.
- `distinct()`: Filters out duplicate elements.
- `sorted()`: Sorts elements in natural or specified order.
- `forEach(Consumer<? super T> action)`: Performs the action on each element.
- `close()`: Closes the stream, releasing resources.

== Custom Commands

You can create custom commands by extending the `Command` class, which encapsulates stream operations with flexible inputs and results.

[source,java]
----
class MyCustomCommand extends Command<Integer, String> {
    @Override
    public Result<String> execute(Integer input) {
        return new Result<>("Processed: " + input);
    }
}
----

== Dependencies

The library requires Java 17 or newer to support virtual threads.

== License

This project is licensed under the Apache License 2.0.

== Contributing

We welcome contributions!
Feel free to open issues or submit pull requests for new features, bug fixes, or improvements.

Readme entirely generated by ChatGPT4.