Type Parameters:

T - result type - 结果类型

Security | 安全性:

Thread-safe: Implementation-dependent - 线程安全: 取决于实现
Null-safe: Yes (validates inputs) - 空值安全: 是（验证输入）

All Known Implementing Classes:: Trampoline.Done, Trampoline.FlatMap, Trampoline.More

public sealed interface Trampoline<T> permits Trampoline.Done<T>, Trampoline.More<T>, Trampoline.FlatMap<A,B>

Trampoline - Stack-safe recursion using trampolining Trampoline - 使用蹦床模式的栈安全递归

Converts recursive computations into iterative ones, preventing stack overflow. Instead of actual recursive calls, computations return either a final result or a continuation to be executed in the next iteration.

将递归计算转换为迭代计算，防止栈溢出。计算不进行实际的递归调用，而是返回最终结果或在下一次迭代中执行的延续。

Features | 主要功能:

Stack-safe recursion - 栈安全的递归
Constant stack space - 常量栈空间
Monadic operations (map, flatMap) - Monad 操作
Mutual recursion support - 支持相互递归

Usage Examples | 使用示例:

// Factorial (would overflow with normal recursion for large n)
Trampoline<Long> factorial(long n, long acc) {
    if (n <= 1) {
        return Trampoline.done(acc);
    }
    return Trampoline.more(() -> factorial(n - 1, n * acc));
}
long result = factorial(10000, 1).get(); // No stack overflow!

// Fibonacci (with accumulator pattern)
Trampoline<Long> fibonacci(int n, long a, long b) {
    if (n == 0) return Trampoline.done(a);
    if (n == 1) return Trampoline.done(b);
    return Trampoline.more(() -> fibonacci(n - 1, b, a + b));
}

// Using map for transformations
Trampoline<String> result = factorial(100, 1)
    .map(Object::toString);

// Using flatMap for dependent computations
Trampoline<Integer> sum = Trampoline.done(10)
    .flatMap(x -> Trampoline.done(x + 5));

// Mutual recursion example (even/odd)
Trampoline<Boolean> isEven(int n) {
    if (n == 0) return Trampoline.done(true);
    return Trampoline.more(() -> isOdd(n - 1));
}
Trampoline<Boolean> isOdd(int n) {
    if (n == 0) return Trampoline.done(false);
    return Trampoline.more(() -> isEven(n - 1));
}
boolean even = isEven(1000000).get(); // Stack-safe!

Performance | 性能特性:

Time: O(n) iterations for n recursive calls - 时间: n 次递归调用需要 O(n) 次迭代
Stack: O(1) - uses heap instead - 栈: O(1) - 使用堆代替
Heap: O(n) Trampoline objects - 堆: O(n) 个 Trampoline 对象

When to Use | 何时使用:

Deep recursive algorithms (thousands+ levels) - 深度递归算法（数千层以上）
Tail-recursive functions - 尾递归函数
Mutual recursion - 相互递归
When stack size cannot be increased - 当无法增加栈大小时

Since:

JDK 25, opencode-base-functional V1.0.0

Author:

Leon Soo www.LeonSoo.com

See Also:

Nested Class Summary

Nested Classes

Modifier and Type

Interface

Description

static final record

Trampoline.Done<T>

Completed Trampoline with a result.

static final record

Trampoline.FlatMap<A,B>

FlatMapped Trampoline for chaining computations.

static final record

Trampoline.More<T>

Suspended Trampoline with a continuation.
Method Summary

Modifier and Type

Method

Description

static <T> Trampoline<T>

delay(Supplier<T> supplier)

Lift a supplier into a Trampoline.

static <T> Trampoline<T>

done(T result)

Create a completed Trampoline with a result.

 Trampoline

flatMap(Function<? super T, Trampoline> f)

Chain another Trampoline computation.

default T

get()

Execute the trampoline and get the result.

boolean

isDone()

Check if the Trampoline is complete.

static <T> Trampoline<T>

iterate(T value, Predicate<T> predicate, Function<T,T> next)

Create a Trampoline for a recursive function.

default Trampoline

map(Function<? super T, ? extends U> mapper)

Transform the result when it becomes available.

static <T> Trampoline<T>

more(Supplier<Trampoline<T>> continuation)

Create a suspended Trampoline with a continuation.

default Trampoline<T>

peek(Consumer<? super T> action)

Execute a side effect when the result is available.

static <T> Trampoline<T>

repeat(int n, T initial, Function<T,T> step)

Create a Trampoline that repeats a computation n times.

default T

run()

Execute the trampoline and get the result.

static <T> Trampoline<T>

sequence(Trampoline<T>... trampolines)

Sequence multiple Trampolines, returning the last result.

static <T> Trampoline<T>

suspend(Supplier<Trampoline<T>> continuation)

Create a Trampoline that suspends computation.

default Lazy<T>

toLazy()

Convert to a Lazy that executes the trampoline.

default Try<T>

toTry()

Convert to a Try that captures exceptions.

Method Details
- done
 
 static <T> Trampoline<T> done(T result)
 
 Create a completed Trampoline with a result. 创建包含结果的已完成 Trampoline。
 Use this to return the final result of the computation.
 
 使用此方法返回计算的最终结果。
 
 Type Parameters:
 
 T - result type - 结果类型
 
 Parameters:
 
 result - the result value - 结果值
 
 Returns:
 
 completed Trampoline
- more
 
 static <T> Trampoline<T> more(Supplier<Trampoline<T>> continuation)
 
 Create a suspended Trampoline with a continuation. 创建包含延续的挂起 Trampoline。
 Use this to defer the next recursive call.
 
 使用此方法推迟下一次递归调用。
 
 Type Parameters:
 
 T - result type - 结果类型
 
 Parameters:
 
 continuation - supplier of the next Trampoline - 下一个 Trampoline 的供应商
 
 Returns:
 
 suspended Trampoline
- suspend
 
 static <T> Trampoline<T> suspend(Supplier<Trampoline<T>> continuation)
 
 Create a Trampoline that suspends computation. 创建挂起计算的 Trampoline。
 Alias for more(Supplier) for readability.
 
 more(Supplier) 的别名，增加可读性。
 
 Type Parameters:
 
 T - result type - 结果类型
 
 Parameters:
 
 continuation - supplier of the next Trampoline - 下一个 Trampoline 的供应商
 
 Returns:
 
 suspended Trampoline
- delay
 
 static <T> Trampoline<T> delay(Supplier<T> supplier)
 
 Lift a supplier into a Trampoline. 将供应商提升为 Trampoline。
 
 Type Parameters:
 
 T - result type - 结果类型
 
 Parameters:
 
 supplier - value supplier - 值供应商
 
 Returns:
 
 Trampoline containing the computed value
- get
 
 default T get()
 
 Execute the trampoline and get the result. 执行蹦床并获取结果。
 This method iteratively executes continuations until a final result is reached, using constant stack space.
 
 此方法迭代执行延续直到得到最终结果，使用常量栈空间。
 
 Returns:
 
 the computed result - 计算结果
- run
 
 default T run()
 
 Execute the trampoline and get the result. 执行蹦床并获取结果。
 Alias for get().
 
 get() 的别名。
 
 Returns:
 
 the computed result - 计算结果
- isDone
 
 boolean isDone()
 
 Check if the Trampoline is complete. 检查 Trampoline 是否完成。
 
 Returns:
 
 true if done - 如果完成返回 true
- map
 
 default Trampoline map(Function<? super T, ? extends U> mapper)
 
 Transform the result when it becomes available. 结果可用时转换它。
 The mapper is applied lazily when get() is called.
 
 映射函数在调用 get() 时惰性应用。
 
 Type Parameters:
 
 U - result type - 结果类型
 
 Parameters:
 
 mapper - transformation function - 转换函数
 
 Returns:
 
 transformed Trampoline
- flatMap
 
 Trampoline flatMap(Function<? super T, Trampoline> f)
 
 Chain another Trampoline computation. 链接另一个 Trampoline 计算。
 Enables composition of multiple trampolined computations.
 
 启用多个蹦床计算的组合。
 
 Type Parameters:
 
 U - result type - 结果类型
 
 Parameters:
 
 f - function producing the next Trampoline - 产生下一个 Trampoline 的函数
 
 Returns:
 
 chained Trampoline
- peek
 
 default Trampoline<T> peek(Consumer<? super T> action)
 
 Execute a side effect when the result is available. 结果可用时执行副作用。
 
 Parameters:
 
 action - the action to perform - 要执行的动作
 
 Returns:
 
 this Trampoline for chaining
- toLazy
 
 default Lazy<T> toLazy()
 
 Convert to a Lazy that executes the trampoline. 转换为执行蹦床的 Lazy。
 
 Returns:
 
 Lazy containing the result
- toTry
 
 default Try<T> toTry()
 
 Convert to a Try that captures exceptions. 转换为捕获异常的 Try。
 
 Returns:
 
 Try containing the result or exception
- iterate
 
 static <T> Trampoline<T> iterate(T value, Predicate<T> predicate, Function<T,T> next)
 
 Create a Trampoline for a recursive function. 为递归函数创建 Trampoline。
 Helper method for converting recursive functions to trampolined versions.
 
 用于将递归函数转换为蹦床版本的辅助方法。
 
 Type Parameters:
 
 T - value type - 值类型
 
 Parameters:
 
 value - initial value - 初始值
 
 predicate - termination condition - 终止条件
 
 next - function to compute next value - 计算下一个值的函数
 
 Returns:
 
 Trampoline that iterates until predicate is satisfied
- repeat
 
 static <T> Trampoline<T> repeat(int n, T initial, Function<T,T> step)
 
 Create a Trampoline that repeats a computation n times. 创建重复计算 n 次的 Trampoline。
 
 Type Parameters:
 
 T - value type - 值类型
 
 Parameters:
 
 n - number of times to repeat - 重复次数
 
 initial - initial value - 初始值
 
 step - step function - 步进函数
 
 Returns:
 
 Trampoline with final result
- sequence
 
 @SafeVarargs static <T> Trampoline<T> sequence(Trampoline<T>... trampolines)
 
 Sequence multiple Trampolines, returning the last result. 顺序执行多个 Trampoline，返回最后一个结果。
 
 Type Parameters:
 
 T - result type - 结果类型
 
 Parameters:
 
 trampolines - the trampolines to sequence - 要顺序执行的蹦床
 
 Returns:
 
 Trampoline with the last result

Interface Trampoline<T>

Nested Class Summary

Method Summary

Method Details

done

more

suspend

delay

get

run

isDone

map

flatMap

peek

toLazy

toTry

iterate

repeat

sequence