IOExample.java

• IOExample.java

Use IO_OP.delay to capture side effects. Use ioMonad.of for pure values within IO.

Monad<IOKind.Witness> ioMonad = Instances.monad(io());
java.util.Scanner scanner = new java.util.Scanner(System.in);

// IO action to print a message — nothing happens yet
Kind<IOKind.Witness, Unit> printHello = IO_OP.delay(() -> {
    System.out.println("Hello from IO!");
    return Unit.INSTANCE;
});

// IO action to read a line from the console — nothing happens yet
Kind<IOKind.Witness, String> readLine = IO_OP.delay(() -> {
    System.out.print("Enter your name: ");
    return scanner.nextLine();
});

// Lift a pure value — no side effect at all
Kind<IOKind.Witness, Integer> pureValueIO = ioMonad.of(42);

// Capture a time-dependent side effect
Kind<IOKind.Witness, Long> currentTime = IO_OP.delay(System::currentTimeMillis);

None of these execute when created. The Supplier inside delay is stored, not called.

• IOExample.java

Use IO_OP.unsafeRunSync to run the computation. This is the "end of the world" — call it at application boundaries, not deep inside your logic.

// Execute printHello — now the effect happens
IO_OP.unsafeRunSync(printHello); // prints "Hello from IO!"

// Execute pureValueIO
Integer value = IO_OP.unsafeRunSync(pureValueIO);
System.out.println("Fetched: " + value); // Output: 42

// Running the same action again re-executes the effect
IO_OP.unsafeRunSync(printHello); // prints "Hello from IO!" again

// Exceptions propagate — handle at the boundary
Kind<IOKind.Witness, String> risky = IO_OP.delay(() -> {
    if (Math.random() < 0.5) throw new RuntimeException("Boom!");
    return "OK";
});
try {
    IO_OP.unsafeRunSync(risky);
} catch (RuntimeException e) {
    System.err.println("Caught: " + e.getMessage());
}

• IOExample.java

map transforms the result of an IO action without executing it. flatMap sequences two IO actions — the second can depend on the first's result.

Monad<IOKind.Witness> ioMonad = Instances.monad(io());

// --- map: transform a result ---
Kind<IOKind.Witness, String> readLineAction = IO_OP.delay(() -> "Test Input");

Kind<IOKind.Witness, String> greetAction = ioMonad.map(
    name -> "Hello, " + name + "!",
    readLineAction
);

System.out.println("Greet action created, not executed yet.");
String greeting = IO_OP.unsafeRunSync(greetAction);
System.out.println(greeting); // Output: Hello, Test Input!

// --- flatMap: sequence dependent effects ---
Kind<IOKind.Witness, String> getName = IO_OP.delay(() -> {
    System.out.println("Effect: Getting name...");
    return "Alice";
});

Function<String, Kind<IOKind.Witness, Unit>> printGreeting = name ->
    IO_OP.delay(() -> {
        System.out.println("Welcome, " + name + "!");
        return Unit.INSTANCE;
    });

// Combine — nothing runs until unsafeRunSync
Kind<IOKind.Witness, Unit> combinedAction = ioMonad.flatMap(printGreeting, getName);

IO_OP.unsafeRunSync(combinedAction);
// Output:
// Effect: Getting name...
// Welcome, Alice!

• IOExample.java

Beyond map and flatMap, IOMonad provides utility methods for common patterns.

Kind<IOKind.Witness, String> getAliceName = ioMonad.of("Alice");

Function<String, Kind<IOKind.Witness, Unit>> printGreeting = name ->
    IO_OP.delay(() -> { System.out.println("Welcome, " + name + "!"); return Unit.INSTANCE; });

Function<String, Kind<IOKind.Witness, Unit>> doNothing = name -> ioMonad.of(Unit.INSTANCE);

// peek — log without affecting the pipeline
Kind<IOKind.Witness, String> logged =
    ioMonad.peek(name -> System.out.println("LOG: Name -> " + name), getAliceName);

// flatMapIfOrElse — conditional branching
Kind<IOKind.Witness, Unit> conditionalGreeting =
    ioMonad.flatMapIfOrElse(
        name -> !name.equalsIgnoreCase("admin"),  // predicate
        printGreeting,                              // true branch
        doNothing,                                  // false branch
        logged                                      // input value
    );

// as — replace the result, keeping the effect
Kind<IOKind.Witness, Unit> finalProgram =
    ioMonad.as(
        Unit.INSTANCE,
        ioMonad.peek(_ -> System.out.println("Program finished."), conditionalGreeting));

IO_OP.unsafeRunSync(finalProgram);
// Output:
// LOG: Name -> Alice
// Welcome, Alice!
// Program finished.

IO has dedicated JMH benchmarks measuring lazy construction, platform thread execution, and map/flatMap chains. Key expectations:

• Construction (delay, pure) is very fast (~100+ ops/us) — IO is a lazy wrapper with no immediate execution
• IO vs VTask: IO is ~10-30% faster for simple operations due to no virtual thread spawn overhead
• Deep chains (50+) complete without error — composition overhead dominates at depth
• At high concurrency (1000+ tasks), VTask scales better than IO due to virtual threads

./gradlew :hkj-benchmarks:jmh --includes=".*IOBenchmark.*"
./gradlew :hkj-benchmarks:jmh --includes=".*VTaskVsIOBenchmark.*"

See Benchmarks & Performance for full details, comparison benchmarks against VTask, and how to interpret results.